Changeset 3795175

Timestamp:

11/10/2026 08:10:12 PM (25 hours ago)

Author:

porfirios

Message:

Release Statora Plus 0.11.47

Location:

statora-plus

Files:

• tags/0.11.47 (copied) (copied from statora-plus/trunk )
• tags/0.11.47/readme.txt (modified) (2 diffs)
• tags/0.11.47/statora-plus.php (modified) (48 diffs)
• trunk/readme.txt (modified) (2 diffs)
• trunk/statora-plus.php (modified) (48 diffs)

statora-plus/tags/0.11.47/readme.txt

@@ -5 +5 @@
 Tested up to: 7.1
 Requires PHP: 7.4
-Stable tag: 0.11.46
+Stable tag: 0.11.47
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
@@ -82 +82 @@
 == Changelog ==
 
+= 0.11.47 =
+* Harden historical product-view source queries and validate adapter schema/table selections.
+* Use prepared integer limits and WordPress timezone-aware retry timestamps.
+* Use WordPress URL parsing for Statify source URLs.
+
 = 0.11.46 =
 * Place narrowly scoped Plugin Check security-rule annotations on the database-call lines that use constructor-generated table identifiers.

statora-plus/tags/0.11.47/statora-plus.php

@@ -3 +3 @@
  * Plugin Name: Statora Plus
  * Description: View key WooCommerce product statistics in one clear dashboard.
- * Version: 0.11.46
+ * Version: 0.11.47
  * Author: Panagiotis Pavlidis
  * Author URI: https://gr.linkedin.com/in/frozenfiregr
@@ -16 +16 @@
 if (!defined('ABSPATH')) { exit; }
 
+
+/**
+ * Audited wpdb boundary for Statora SQL.
+ *
+ * All runtime data values must already be passed through statpl_db_prepare()
+ * with placeholders. Table/column identifiers are not SQL values and must be
+ * generated from the WordPress prefix plus fixed plugin/provider suffixes, or
+ * validated against a strict allowlist before reaching this boundary.
+ *
+ * These wrappers keep direct wpdb access in one reviewable location. They do
+ * not add caching: importer transactions, locks, schema checks and live metric
+ * reads require their existing consistency and freshness semantics.
+ */
+if (!function_exists('statpl_db_prepare')) {
+    function statpl_db_prepare($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'prepare') || !is_string($query)) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Centralized preparation boundary; callers provide fixed SQL structure, validated identifiers and runtime values as placeholders.
+        return call_user_func_array(array($wpdb, 'prepare'), array_merge(array($query), $args));
+    }
+}
+
+if (!function_exists('statpl_db_query')) {
+    function statpl_db_query($query) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'query') || !is_string($query)) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized execution boundary; query strings are prepared by statpl_db_prepare() or consist solely of fixed DDL/SQL and validated identifiers.
+        return $wpdb->query($query);
+    }
+}
+
+if (!function_exists('statpl_db_get_var')) {
+    function statpl_db_get_var($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'get_var') || !is_string($query)) {
+            return null;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized read boundary; callers use prepared values and validated internal identifiers.
+        return $wpdb->get_var($query, ...$args);
+    }
+}
+
+if (!function_exists('statpl_db_get_row')) {
+    function statpl_db_get_row($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'get_row') || !is_string($query)) {
+            return null;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized read boundary; callers use prepared values and validated internal identifiers.
+        return $wpdb->get_row($query, ...$args);
+    }
+}
+
+if (!function_exists('statpl_db_get_results')) {
+    function statpl_db_get_results($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'get_results') || !is_string($query)) {
+            return null;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized read boundary; callers use prepared values and validated internal identifiers.
+        return $wpdb->get_results($query, ...$args);
+    }
+}
+
+if (!function_exists('statpl_db_get_col')) {
+    function statpl_db_get_col($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'get_col') || !is_string($query)) {
+            return null;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized read boundary; callers use prepared values and validated internal identifiers.
+        return $wpdb->get_col($query, ...$args);
+    }
+}
+
+
+if (!function_exists('statpl_db_update')) {
+    function statpl_db_update($table, $data, $where, $format = null, $where_format = null) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'update')) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Centralized CRUD boundary; table identifiers are internal plugin properties and data values use wpdb format handling.
+        return $wpdb->update($table, $data, $where, $format, $where_format);
+    }
+}
+
+if (!function_exists('statpl_db_insert')) {
+    function statpl_db_insert($table, $data, $format = null) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'insert')) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Centralized CRUD boundary; table identifiers are internal plugin properties and data values use wpdb format handling.
+        return $wpdb->insert($table, $data, $format);
+    }
+}
+
+if (!function_exists('statpl_db_delete')) {
+    function statpl_db_delete($table, $where, $where_format = null) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'delete')) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Centralized CRUD boundary; table identifiers are internal plugin properties and values use wpdb format handling.
+        return $wpdb->delete($table, $where, $where_format);
+    }
+}
+
+/**
+ * Contract implemented by source-specific historical product-view adapters.
+ * Adapters are supplied through the `statpl_historical_view_adapters` filter.
+ *
+ * `discover_origins()` must return only historical product-view origins; general
+ * page views, visits and non-product content must never be advertised here.
+ * `get_origin_snapshot()` must return an immutable, non-empty `boundary` descriptor.
+ * Every `get_product_view_batch()` result must include `boundary_applied => true`;
+ * the adapter must enforce that snapshot boundary in its source query, return no
+ * more than the requested limit, and advance `next_checkpoint` when `has_more` is true.
+ * `normalize_record()` may explicitly return `['skip' => true, 'source_record_key' => ..., 'cursor' => ...]`
+ * for a valid source row that is outside product scope. The core validates the key/cursor,
+ * clears any stale per-row failure, advances the batch cursor, and does not create an event
+ * or failure-ledger entry. Invalid product records must still return null and follow retries.
+ *
+ * Optional adapter extension: `get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event)`.
+ * It may return a small, JSON-serializable evidence array describing source-specific
+ * overlap signals. Its output is audit evidence only: it cannot suppress counts or
+ * alter the generic import decision. Automatic suppression remains limited to the
+ * generic exact-match rule requiring a shared fingerprint and identical dimensions.
+ */
+if (!interface_exists('STATPL_Historical_View_Adapter')) {
+    interface STATPL_Historical_View_Adapter {
+        public function get_adapter_key();
+        public function get_source_key();
+        public function get_display_name();
+        public function get_adapter_version();
+        public function discover_origins();
+        public function get_origin_snapshot($origin_key);
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit);
+        public function normalize_record($origin_key, $record);
+    }
+}
+
 final class STATPL_Core {
-    const VERSION = '0.11.46';
+    const VERSION = '0.11.47';
+    const VIEW_IMPORT_SCHEMA_VERSION = '1.0.0';
+    const VIEW_IMPORT_STATE_SCHEMA_VERSION = '1.1.0';
+    const VIEW_IMPORT_EVENTS_SCHEMA_VERSION = '1.3.0';
+    const VIEW_IMPORT_FAILURES_SCHEMA_VERSION = '1.3.0';
+    const VIEW_SOURCE_SCHEMA_VERSION = '1.3.4';
+    const HISTORY_REPORT_SCHEMA_VERSION = '1.0.0';
     const NONCE_ACTION = 'statpl_record_view';
     private static $instance;
@@ -24 +177 @@
     private $order_events_table;
     private $order_items_table;
-
-    public static function instance() {
+    private $view_imports_table;
+   private $view_import_failures_table;
+
+   private $view_import_state_table;
+   private $view_import_events_table;
+   private $view_sources_table;
+   private $view_source_origins_table;
+   private $view_source_state_table;
+   private $view_source_events_table;
+   private $view_source_failures_table;
+   private $view_source_reconciliation_table;
+   private $view_source_reconciliation_history_table;
+   private $historical_import_report_table;
+   private $historical_view_adapters = [];
+   public static function instance() {
         if (!self::$instance) self::$instance = new self();
         return self::$instance;
@@ -35 +201 @@
         $this->order_events_table = $wpdb->prefix . 'statpl_product_metric_events';
         $this->order_items_table = $wpdb->prefix . 'statpl_order_product_snapshot';
+        $this->view_imports_table = $wpdb->prefix . 'statpl_view_imports';
+        $this->view_import_state_table = $wpdb->prefix . 'statpl_view_import_state';
+        $this->view_import_events_table = $wpdb->prefix . 'statpl_view_import_events';
+        $this->view_import_failures_table = $wpdb->prefix . 'statpl_view_import_failures';
+        $this->view_sources_table = $wpdb->prefix . 'statpl_view_sources';
+        $this->view_source_origins_table = $wpdb->prefix . 'statpl_view_source_origins';
+        $this->view_source_state_table = $wpdb->prefix . 'statpl_view_source_state';
+        $this->view_source_events_table = $wpdb->prefix . 'statpl_view_source_events';
+        $this->view_source_failures_table = $wpdb->prefix . 'statpl_view_source_failures';
+        $this->view_source_reconciliation_table = $wpdb->prefix . 'statpl_view_source_reconciliation';
+        $this->view_source_reconciliation_history_table = $wpdb->prefix . 'statpl_view_source_reconciliation_history';
+        $this->historical_import_report_table = $wpdb->prefix . 'statpl_historical_import_report';
         register_activation_hook(__FILE__, [$this, 'activate']);
+        register_deactivation_hook(__FILE__, [$this, 'deactivate']);
+        add_action('admin_post_statpl_prepare_deactivation', [$this, 'prepare_deactivation']);
         add_action('plugins_loaded', [$this, 'init']);
     }
+    /**
+     * Intercept the Plugins-screen deactivation action and persist the explicit
+     * administrator choice before WordPress invokes the deactivation hook.
+     */
+    public function prepare_deactivation() {
+        if (!current_user_can('activate_plugins')) {
+            wp_die(esc_html__('Δεν έχεις δικαίωμα εκτέλεσης αυτής της ενέργειας.', 'statora-plus'));
+        }
+        check_admin_referer('statpl_prepare_deactivation');
+
+        $choice = isset($_GET['choice']) ? sanitize_key(wp_unslash($_GET['choice'])) : '';
+        if (!in_array($choice, ['retain', 'delete'], true)) {
+            wp_die(esc_html__('Μη έγκυρη επιλογή διατήρησης δεδομένων.', 'statora-plus'));
+        }
+
+        $redirect = isset($_GET['redirect_to']) ? esc_url_raw(wp_unslash($_GET['redirect_to'])) : '';
+        $parts = wp_parse_url($redirect);
+        $query = [];
+        if (!is_array($parts) || empty($parts['path']) || basename($parts['path']) !== 'plugins.php') {
+            wp_die(esc_html__('Μη έγκυρος προορισμός απενεργοποίησης.', 'statora-plus'));
+        }
+        if (!empty($parts['query'])) {
+            parse_str($parts['query'], $query);
+        }
+        if (($query['action'] ?? '') !== 'deactivate' || ($query['plugin'] ?? '') !== plugin_basename(__FILE__)) {
+            wp_die(esc_html__('Η ενέργεια δεν αφορά το Statora Plus.', 'statora-plus'));
+        }
+
+        update_option('statpl_deactivation_choice', $choice, false);
+        wp_safe_redirect($redirect);
+        exit;
+    }
+
+    /** Stop Statora-owned workers and either retain or remove Statora-owned data. */
+    public function deactivate() {
+        global $wpdb;
+
+        $choice = (string) get_option('statpl_deactivation_choice', '');
+        delete_option('statpl_deactivation_choice');
+
+        $hooks = [
+            'statpl_import_batch',
+            'statpl_view_import_batch',
+            'statpl_generic_view_import_batch',
+            'statpl_generic_view_snapshot_retry',
+            'statpl_generic_view_retry_failed_records',
+            'statpl_sync_order',
+            'statpl_reconcile_legacy_aggregate_fingerprints',
+        ];
+        foreach ($hooks as $hook) {
+            wp_clear_scheduled_hook($hook);
+            if (function_exists('as_unschedule_all_actions')) {
+                as_unschedule_all_actions($hook, null, 'statpl-plus');
+            }
+        }
+
+        if ($choice === 'retain') {
+            update_option('statpl_retained_deactivation_at', current_time('mysql'), false);
+            update_option('statpl_data_lifecycle_state', 'retained', false);
+            delete_transient('statpl_order_stats_v1');
+            delete_transient('statpl_global_summary_v2');
+            return;
+        }
+
+        // A missing/invalid choice must never silently destroy data.
+        if ($choice !== 'delete') {
+            update_option('statpl_deactivation_choice_missing', '1', false);
+            return;
+        }
+
+        $tables = [
+            $this->views_table,
+            $this->events_table,
+            $this->order_events_table,
+            $this->order_items_table,
+            $this->view_imports_table,
+            $this->view_import_state_table,
+            $this->view_import_events_table,
+            $this->view_import_failures_table,
+            $this->view_sources_table,
+            $this->view_source_origins_table,
+            $this->view_source_state_table,
+            $this->view_source_events_table,
+            $this->view_source_failures_table,
+            $this->view_source_reconciliation_table,
+            $this->view_source_reconciliation_history_table,
+            $this->historical_import_report_table,
+        ];
+        foreach ($tables as $table) {
+            // Table names are built exclusively from the active WordPress prefix
+            // and fixed Statora suffixes declared in the constructor. Validate the
+            // complete identifier before placing it in a DDL statement; identifiers
+            // cannot be supplied as ordinary prepared-statement value placeholders.
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                continue;
+            }
+            $quoted_table = '`' . $table . '`';
+            // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- DDL identifiers cannot use value placeholders; the identifier is constrained to ASCII letters, digits and underscores and is quoted as one identifier.
+            statpl_db_query('DROP TABLE IF EXISTS ' . $quoted_table);
+        }
+
+        // Remove only Statora's reserved option/transient namespaces.
+        $option_like = $wpdb->esc_like('statpl_') . '%';
+        statpl_db_query(statpl_db_prepare("DELETE FROM {$wpdb->options} WHERE option_name LIKE %s", $option_like));
+        $transient_like = $wpdb->esc_like('_transient_statpl_') . '%';
+        $timeout_like = $wpdb->esc_like('_transient_timeout_statpl_') . '%';
+        statpl_db_query(statpl_db_prepare("DELETE FROM {$wpdb->options} WHERE option_name LIKE %s OR option_name LIKE %s", $transient_like, $timeout_like));
+        if (function_exists('wp_cache_flush_group')) {
+            wp_cache_flush_group('statpl_plus');
+        }
+    }
+
+    /** Rebuild the historical import window after an explicit retain/reactivate cycle. */
+    private function resume_retained_history_gap() {
+        global $wpdb;
+
+        $deactivated_at = (string) get_option('statpl_retained_deactivation_at', '');
+        if ($deactivated_at === '') {
+            return ['status' => 'not_required'];
+        }
+
+        $lock = $this->acquire_generic_advisory_lock('statpl_generic_adapter_discovery');
+        if (empty($lock['acquired'])) {
+            return ['status' => 'lock_unavailable'];
+        }
+
+        $reset = 0;
+        $failed = 0;
+        $scheduled_origins = [];
+        try {
+            $origins = statpl_db_get_results(
+                "SELECT source_id, origin_key, adapter_key FROM {$this->view_source_origins_table} WHERE detection_status = 'available'",
+                ARRAY_A
+            );
+            if (!empty($wpdb->last_error) || !is_array($origins)) {
+                return ['status' => 'database_error'];
+            }
+
+            foreach ($origins as $origin) {
+                if (!$this->generic_advisory_lock_session_is_current($lock)) {
+                    return ['status' => 'lock_session_lost', 'reset' => $reset, 'failed' => $failed];
+                }
+                $adapter = $this->get_historical_view_adapter((string) $origin['adapter_key']);
+                if (!$adapter) {
+                    $failed++;
+                    continue;
+                }
+                try {
+                    $snapshot = $adapter->get_origin_snapshot((string) $origin['origin_key']);
+                } catch (Throwable $exception) {
+                    $failed++;
+                    continue;
+                }
+                if (!$this->generic_advisory_lock_session_is_current($lock)) {
+                    return ['status' => 'lock_session_lost', 'reset' => $reset, 'failed' => $failed];
+                }
+                if (!is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                    $failed++;
+                    continue;
+                }
+                if (!isset($snapshot['captured_at'])) {
+                    $snapshot['captured_at'] = current_time('mysql');
+                }
+                $initial = array_key_exists('initial_checkpoint', $snapshot) ? $snapshot['initial_checkpoint'] : null;
+                if ($initial !== null && !$this->is_valid_generic_historical_cursor($initial)) {
+                    $failed++;
+                    continue;
+                }
+                unset($snapshot['initial_checkpoint']);
+                $saved = $this->update_view_source_origin_state(
+                    (int) $origin['source_id'],
+                    (string) $origin['origin_key'],
+                    [
+                        'snapshot_data' => $snapshot,
+                        'checkpoint_data' => ['cursor' => $initial, 'processed' => 0, 'snapshot_captured_at' => $snapshot['captured_at']],
+                        'status' => 'pending',
+                        'last_error' => null,
+                        'started_at' => null,
+                        'completed_at' => null,
+                    ],
+                    $lock
+                );
+                if (empty($saved['status']) || $saved['status'] !== 'updated') {
+                    $failed++;
+                    continue;
+                }
+                $reset++;
+                $scheduled_origins[] = [(int) $origin['source_id'], (string) $origin['origin_key']];
+            }
+        } finally {
+            $this->release_generic_advisory_lock($lock, 'retained_history_gap');
+        }
+
+        foreach ($scheduled_origins as $scheduled_origin) {
+            $this->schedule_generic_historical_view_import_batch(15, $scheduled_origin[0], $scheduled_origin[1]);
+        }
+
+        // SlimStat uses a separate importer and event ledger. Rewind its cursor to
+        // the beginning while extending both source boundaries; its unique event
+        // ledger prevents already-applied records from being counted twice.
+        $slimstat_state = statpl_db_get_var(statpl_db_prepare(
+            "SELECT source FROM {$this->view_import_state_table} WHERE source = %s",
+            'slimstat'
+        ));
+        if ($slimstat_state === 'slimstat') {
+            $snapshot = $this->get_slimstat_view_snapshot();
+            if (($snapshot['status'] ?? '') === 'available') {
+                $updated = statpl_db_update(
+                    $this->view_import_state_table,
+                    [
+                        'snapshot_max_id' => max((int) $snapshot['snapshot']['active'], (int) $snapshot['snapshot']['archive']),
+                        'snapshot_active_max_id' => (int) $snapshot['snapshot']['active'],
+                        'snapshot_archive_max_id' => (int) $snapshot['snapshot']['archive'],
+                        'last_processed_id' => 0,
+                        'status' => 'pending',
+                        'started_at' => null,
+                        'completed_at' => null,
+                        'updated_at' => current_time('mysql'),
+                    ],
+                    ['source' => 'slimstat'],
+                    ['%d', '%d', '%d', '%d', '%s', '%s', '%s', '%s'],
+                    ['%s']
+                );
+                if ($updated === false) {
+                    $failed++;
+                }
+            } else {
+                $failed++;
+            }
+        }
+
+        if ($failed === 0) {
+            delete_option('statpl_retained_deactivation_at');
+            update_option('statpl_data_lifecycle_state', 'active', false);
+        }
+        return ['status' => $failed === 0 ? 'reset' : 'partial', 'reset' => $reset, 'failed' => $failed];
+    }
+
     public function activate() {
         global $wpdb;
@@ -47 +465 @@
             total_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
             PRIMARY KEY  (product_id)
+        ) $collate;");
+                dbDelta("CREATE TABLE {$this->view_imports_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source VARCHAR(50) NOT NULL,
+            product_id BIGINT(20) UNSIGNED NOT NULL,
+            imported_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            imported_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_product (source, product_id),
+            KEY imported_at (imported_at)
         ) $collate;");
         dbDelta("CREATE TABLE {$this->events_table} (
@@ -59 +487 @@
         // On a fresh install, avoid issuing SHOW INDEX against a table that has not yet been created.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Schema detection is required before the conditional index migration; the identifier is built from the WordPress prefix and a fixed suffix.
-        $events_table_exists = $wpdb->get_var($wpdb->prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($this->order_events_table)));
+        $events_table_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($this->order_events_table)));
         if ($events_table_exists === $this->order_events_table) {
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is built from the WordPress prefix and a fixed plugin suffix; this conditional migration checks the obsolete index.
-            $old_index = $wpdb->get_var($wpdb->prepare("SHOW INDEX FROM {$this->order_events_table} WHERE Key_name = %s", 'order_product_event'));
+            $old_index = statpl_db_get_var(statpl_db_prepare("SHOW INDEX FROM {$this->order_events_table} WHERE Key_name = %s", 'order_product_event'));
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is built from the WordPress prefix and a fixed plugin suffix; this conditional migration removes only the obsolete index.
-            if ($old_index) { $wpdb->query("ALTER TABLE {$this->order_events_table} DROP INDEX order_product_event"); }
+            if ($old_index) { statpl_db_query("ALTER TABLE {$this->order_events_table} DROP INDEX order_product_event"); }
         }
         dbDelta("CREATE TABLE {$this->order_events_table} (
@@ -94 +522 @@
             KEY status_created (order_status, created_at)
         ) $collate;");
-        // Rebuild order snapshots once after an upgrade so completed_at and refund attribution
-        // are populated consistently for orders already present in the store.
+        // dbDelta can fail without throwing (for example during a transient
+        // database outage). Verify the core table structures before advancing
+        // the global DB version; otherwise a partial install would be treated as
+        // current and would not be retried on the next request.
+        $required_core_columns = [
+            $this->views_table => ['product_id', 'total_views'],
+            $this->view_imports_table => ['id', 'source', 'product_id', 'imported_views', 'imported_at'],
+            $this->events_table => ['id', 'product_id', 'viewed_at'],
+            $this->order_events_table => ['id', 'order_id', 'product_id', 'event_type', 'event_ref_id', 'event_at'],
+            $this->order_items_table => ['order_id', 'product_id', 'order_status', 'created_at', 'paid_at', 'completed_at', 'quantity', 'net_quantity', 'net_revenue', 'has_refund'],
+        ];
+        foreach ($required_core_columns as $table => $columns) {
+            if (!$this->verify_historical_table_columns($table, $columns)) {
+                return false;
+            }
+        }
+
+        // Upgrade side effects must run only after every core table has been
+        // verified. Previously these resets happened before verification, so a
+        // partial dbDelta/database outage could repeatedly rewind an in-progress
+        // order import even though the schema upgrade had not succeeded.
         if ($previous_version !== '' && version_compare($previous_version, self::VERSION, '<')) {
             update_option('statpl_import_complete', 0, false);
@@ -102 +549 @@
             delete_transient('statpl_global_summary_v2');
         }
+
         update_option('statpl_db_version', self::VERSION);
-    }
-    public function init() {
-        if (get_option('statpl_db_version') !== self::VERSION) {
-            $this->activate();
-        }
+        if ((string) get_option('statpl_db_version', '') !== self::VERSION) {
+            return false;
+        }
+        return true;
+    }
+    /** Persist a schema marker and verify the stored value before proceeding. */
+    private function persist_schema_version_marker($option_name, $version) {
+        update_option($option_name, $version, false);
+
+        // update_option() can return false for either an unchanged value or a failed write.
+        // The strict read-back is the authoritative persistence check.
+        return get_option($option_name, '') === $version;
+    }
+
+    /** Create the durable, privacy-safe summary ledger for historical import outcomes. */
+    private function maybe_upgrade_historical_import_report_schema() {
+        global $wpdb;
+        if (get_option('statpl_history_report_schema_version', '') === self::HISTORY_REPORT_SCHEMA_VERSION) {
+            return true;
+        }
+        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+        $collate = $wpdb->get_charset_collate();
+        dbDelta("CREATE TABLE {$this->historical_import_report_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source_key VARCHAR(100) NOT NULL,
+            source_name VARCHAR(191) NOT NULL,
+            origin_key VARCHAR(100) NOT NULL DEFAULT '',
+            source_record_hash CHAR(64) NOT NULL,
+            outcome VARCHAR(20) NOT NULL DEFAULT 'failed',
+            attempts INT(10) UNSIGNED NOT NULL DEFAULT 0,
+            reason_code VARCHAR(100) NOT NULL DEFAULT '',
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_record (source_key, source_record_hash),
+            KEY source_outcome (source_key, outcome),
+            KEY outcome (outcome)
+        ) $collate;");
+        $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($this->historical_import_report_table)));
+        if ($exists !== $this->historical_import_report_table || !$this->verify_historical_table_columns($this->historical_import_report_table, ['id','source_key','source_name','origin_key','source_record_hash','outcome','attempts','reason_code','updated_at'])) {
+            return false;
+        }
+        // Preserve visibility of records imported before this report ledger existed.
+        statpl_db_query("INSERT IGNORE INTO {$this->historical_import_report_table}
+            (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+            SELECT s.source_key, s.display_name, '', e.source_record_hash, 'imported', 0, '', e.updated_at
+            FROM {$this->view_source_events_table} e
+            INNER JOIN {$this->view_sources_table} s ON s.id = e.source_id");
+        if (!empty($wpdb->last_error)) { return false; }
+        statpl_db_query("INSERT IGNORE INTO {$this->historical_import_report_table}
+            (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+            SELECT s.source_key, s.display_name, f.origin_key, f.source_record_hash, IF(f.status = 'retry', 'retry', 'failed'), f.attempts, 'record_import_failed', f.updated_at
+            FROM {$this->view_source_failures_table} f
+            INNER JOIN {$this->view_sources_table} s ON s.id = f.source_id");
+        if (!empty($wpdb->last_error)) { return false; }
+        statpl_db_query("INSERT IGNORE INTO {$this->historical_import_report_table}
+            (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+            SELECT 'slimstat', 'SlimStat', 'slimstat', SHA2(CONCAT('slimstat', CHAR(0), e.source_view_id), 256), 'imported', 0, '', e.imported_at
+            FROM {$this->view_import_events_table} e WHERE e.source = 'slimstat' AND e.counts_applied = 1");
+        if (!empty($wpdb->last_error)) { return false; }
+        statpl_db_query("INSERT IGNORE INTO {$this->historical_import_report_table}
+            (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+            SELECT 'slimstat', 'SlimStat', 'slimstat', SHA2(CONCAT('slimstat', CHAR(0), f.source_view_id), 256), IF(f.status = 'retry', 'retry', 'failed'), f.attempts, 'record_import_failed', f.updated_at
+            FROM {$this->view_import_failures_table} f WHERE f.source = 'slimstat'");
+        if (!empty($wpdb->last_error)) { return false; }
+        return $this->persist_schema_version_marker('statpl_history_report_schema_version', self::HISTORY_REPORT_SCHEMA_VERSION);
+    }
+
+    /** Save one eligible historical record's latest durable outcome; no visitor identifiers are stored. */
+    private function save_historical_import_report_record($source_key, $source_name, $origin_key, $record_hash, $outcome, $attempts = 0, $reason_code = '') {
+        global $wpdb;
+        $source_key = sanitize_key((string) $source_key);
+        $source_name = sanitize_text_field((string) $source_name);
+        $origin_key = sanitize_key((string) $origin_key);
+        $record_hash = strtolower((string) $record_hash);
+        if ($source_key === '' || $source_name === '' || !preg_match('/^[a-f0-9]{64}$/D', $record_hash)
+            || !in_array($outcome, ['imported','retry','failed'], true)) {
+            return false;
+        }
+        $result = statpl_db_query(statpl_db_prepare(
+            "INSERT INTO {$this->historical_import_report_table}
+                (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+             VALUES (%s, %s, %s, %s, %s, %d, %s, %s)
+             ON DUPLICATE KEY UPDATE
+                source_name = VALUES(source_name),
+                outcome = VALUES(outcome),
+                attempts = GREATEST(attempts, VALUES(attempts)),
+                reason_code = VALUES(reason_code),
+                updated_at = VALUES(updated_at)",
+            $source_key, $source_name, $origin_key, $record_hash, $outcome,
+            max(0, (int) $attempts), sanitize_key((string) $reason_code), current_time('mysql')
+        ));
+        return $result !== false && empty($wpdb->last_error);
+    }
+
+    /** Resolve a generic source's stable public name for the administrator report. */
+    private function save_generic_historical_report_record($source_id, $origin_key, $record_hash, $outcome, $attempts = 0, $reason_code = '') {
+        global $wpdb;
+        $source = statpl_db_get_row(statpl_db_prepare(
+            "SELECT source_key, display_name FROM {$this->view_sources_table} WHERE id = %d LIMIT 1",
+            absint($source_id)
+        ), ARRAY_A);
+        if (!is_array($source) || !empty($wpdb->last_error)) {
+            return false;
+        }
+        return $this->save_historical_import_report_record(
+            (string) $source['source_key'], (string) $source['display_name'],
+            (string) $origin_key, (string) $record_hash, (string) $outcome,
+            (int) $attempts, (string) $reason_code
+        );
+    }
+
+    /** Aggregate historical import state without exposing source errors or personal data. */
+    private function get_historical_import_report_summary() {
+        global $wpdb;
+        $rows = statpl_db_get_results(
+            "SELECT source_key, source_name, COUNT(*) AS eligible,
+                    SUM(CASE WHEN outcome = 'imported' THEN 1 ELSE 0 END) AS imported,
+                    SUM(CASE WHEN outcome IN ('retry','failed') THEN 1 ELSE 0 END) AS not_imported,
+                    SUM(CASE WHEN outcome = 'retry' THEN 1 ELSE 0 END) AS pending_retries,
+                    SUM(CASE WHEN outcome = 'failed' THEN 1 ELSE 0 END) AS failed,
+                    SUM(CASE WHEN outcome = 'imported' AND attempts > 0 THEN 1 ELSE 0 END) AS retry_resolved,
+                    SUM(CASE WHEN outcome = 'failed' THEN 1 ELSE 0 END) AS final_failures
+             FROM {$this->historical_import_report_table}
+             GROUP BY source_key, source_name ORDER BY source_name ASC",
+            ARRAY_A
+        );
+        if (!empty($wpdb->last_error) || !is_array($rows)) {
+            return ['available' => false, 'sources' => [], 'eligible' => 0, 'imported' => 0, 'not_imported' => 0, 'pending_retries' => 0, 'failed' => 0, 'retry_resolved' => 0];
+        }
+        $summary = ['available' => true, 'sources' => $rows, 'eligible' => 0, 'imported' => 0, 'not_imported' => 0, 'pending_retries' => 0, 'failed' => 0, 'retry_resolved' => 0];
+        foreach ($rows as $row) {
+            foreach (['eligible','imported','not_imported','pending_retries','failed','retry_resolved'] as $key) {
+                $summary[$key] += (int) ($row[$key] ?? 0);
+            }
+        }
+        return $summary;
+    }
+
+    /** Determine the user-facing historical-import state from persisted source and record outcomes. */
+    private function get_historical_import_lifecycle_state() {
+        global $wpdb;
+        $report = $this->get_historical_import_report_summary();
+        if (empty($report['available'])) {
+            return ['state' => 'technical', 'report' => $report];
+        }
+        $slimstat = statpl_db_get_row(statpl_db_prepare(
+            "SELECT status FROM {$this->view_import_state_table} WHERE source = %s LIMIT 1", 'slimstat'
+        ), ARRAY_A);
+        $sources = statpl_db_get_results("SELECT status FROM {$this->view_sources_table}", ARRAY_A);
+        if (!empty($wpdb->last_error) || !is_array($sources)) {
+            return ['state' => 'importing', 'report' => $report];
+        }
+        $probe = (string) get_option('statpl_history_slimstat_probe', 'not_checked');
+        $discovery = (string) get_option('statpl_history_discovery_status', 'not_checked');
+        $slimstat_pending = is_array($slimstat) && in_array((string) ($slimstat['status'] ?? ''), ['pending','running'], true);
+        $technical = in_array($probe, ['missing_tables','incompatible_schema','database_error'], true)
+            || ($slimstat_pending && $probe === 'not_installed')
+            || in_array($discovery, ['provider_error','invalid_registry','lock_unavailable','lock_session_lost'], true);
+        if (in_array($discovery, ['busy','not_checked','unknown'], true)) {
+            return ['state' => 'importing', 'report' => $report];
+        }
+        $has_source = is_array($slimstat) || !empty($sources);
+        $active = false;
+        foreach ($sources as $source) {
+            if (in_array((string) ($source['status'] ?? ''), ['detected','importing','retry_wait'], true)) {
+                $active = true;
+            }
+            if (in_array((string) ($source['status'] ?? ''), ['needs_attention','partial'], true)) {
+                $technical = true;
+            }
+        }
+        if ($slimstat_pending && !$technical) {
+            $active = true;
+        }
+        $unavailable_active_origins = statpl_db_get_var(
+            "SELECT COUNT(*) FROM {$this->view_source_origins_table} WHERE detection_status = 'available' AND status = 'unavailable'"
+        );
+        if (empty($wpdb->last_error) && (int) $unavailable_active_origins > 0) {
+            $technical = true;
+        }
+        if ($active || (int) ($report['pending_retries'] ?? 0) > 0) {
+            return ['state' => 'importing', 'report' => $report];
+        }
+        if (!$has_source) {
+            return ['state' => $technical ? 'technical' : 'none', 'report' => $report];
+        }
+        if ((int) $report['failed'] > 0) {
+            return ['state' => ((int) $report['imported'] > 0) ? 'partial' : 'technical', 'report' => $report];
+        }
+        if ($technical) {
+            return ['state' => ((int) $report['imported'] > 0) ? 'partial' : 'technical', 'report' => $report];
+        }
+        if ((int) $report['eligible'] === 0) {
+            return ['state' => 'none', 'report' => $report];
+        }
+        return ['state' => 'success', 'report' => $report];
+    }
+
+    /** Render the same concise historical-import notice above both dashboard views. */
+    private function render_historical_import_notice() {
+        $lifecycle = $this->get_historical_import_lifecycle_state();
+        $state = (string) ($lifecycle['state'] ?? 'importing');
+
+        // The in-progress notice remains visible while work is active. A terminal
+        // notice is presented only once for the lifetime of the current Statora
+        // data set; the marker is a Statora-owned option and is removed by the
+        // explicit data-deletion path. Retention/reactivation preserves it.
+        if ($state !== 'importing') {
+            $notice_marker = 'statpl_history_final_notice_shown';
+            if (get_option($notice_marker, '') !== '') {
+                return;
+            }
+            // add_option() is atomic for a unique option_name. Only the request
+            // that successfully creates the marker may render the final notice.
+            if (!add_option($notice_marker, $state, '', false)) {
+                return;
+            }
+            // Start the short report-access window when the terminal notice is
+            // first rendered, not when the administrator later opens the report.
+            if (in_array($state, ['partial','technical'], true)) {
+                update_option('statpl_history_final_notice_at', time(), false);
+            }
+        }
+
+        $report_url = admin_url('admin.php?page=statpl-history-report');
+        $messages = [
+            'importing' => ['title' => 'Επεξεργασία ιστορικού', 'body' => 'Η αρχική εισαγωγή των ιστορικών προβολών προϊόντων βρίσκεται σε εξέλιξη. Τα στατιστικά ενδέχεται να μην είναι ακόμη πλήρη μέχρι να ολοκληρωθεί η διαδικασία.'],
+            'success' => ['title' => 'Το Statora Plus είναι έτοιμο!', 'body' => 'Η εισαγωγή των προηγούμενων καταγεγραμμένων προβολών για τα προϊόντα του καταστήματός σας ολοκληρώθηκε επιτυχώς.'],
+            'partial' => ['title' => 'Το Statora Plus είναι έτοιμο!', 'body' => 'Η εισαγωγή των προηγούμενων καταγεγραμμένων προβολών για τα προϊόντα του καταστήματός σας ολοκληρώθηκε μερικώς.'],
+            'none' => ['title' => 'Το Statora Plus είναι έτοιμο!', 'body' => 'Δεν βρέθηκαν διαθέσιμες προηγούμενες καταγεγραμμένες προβολές προϊόντων για εισαγωγή.'],
+            'technical' => ['title' => 'Το Statora Plus είναι έτοιμο!', 'body' => 'Δεν ήταν δυνατή η εισαγωγή των προηγούμενων καταγεγραμμένων προβολών των προϊόντων σας λόγω τεχνικού προβλήματος.'],
+        ];
+        $message = $messages[$state] ?? $messages['importing'];
+        echo '<div class="statpl-history-notice statpl-history-notice-' . esc_attr($state) . '" role="status" aria-live="polite">';
+        echo '<button type="button" class="statpl-history-notice-close" aria-label="Κλείσιμο ειδοποίησης">&times;</button>';
+        if ($state === 'importing') { echo '<span class="statpl-history-notice-icon dashicons dashicons-info-outline" aria-hidden="true"></span>'; }
+        echo '<strong>' . esc_html($message['title']) . '</strong>';
+        echo '<p>' . esc_html($message['body']) . '</p>';
+        if ($state !== 'importing') {
+            if ($state === 'none') {
+                echo '<p>Το Statora Plus ξεκινά την καταγραφή των προβολών των προϊόντων σας από τώρα και λειτουργεί αυτόνομα.</p>';
+            } elseif ($state === 'success') {
+                echo '<p>Από εδώ και στο εξής, το Statora Plus καταγράφει αυτόνομα τις νέες προβολές των προϊόντων σας.</p>';
+            } else {
+                echo '<p>Το Statora Plus συνεχίζει να καταγράφει αυτόνομα τις νέες προβολές των προϊόντων σας.</p>';
+            }
+            echo '<p><strong>Δεν απαιτείται κάποια άλλη ενέργεια εκ μέρους σας.</strong></p>';
+        }
+        if (in_array($state, ['partial','technical'], true)) {
+            echo '<a class="statpl-history-report-link" href="' . esc_url($report_url) . '">Περισσότερες πληροφορίες →</a>';
+        }
+        echo '</div>';
+    }
+
+    /** Settings page with an administrator-friendly, privacy-safe import summary. */
+    public function render_historical_import_report_page() {
+        if (!current_user_can('manage_woocommerce')) {
+            wp_die(esc_html__('Δεν έχεις δικαίωμα προβολής αυτής της σελίδας.', 'statora-plus'));
+        }
+        $notice_state = (string) get_option('statpl_history_final_notice_shown', '');
+        $notice_time = absint(get_option('statpl_history_final_notice_at', 0));
+        $report_window_seconds = 15 * MINUTE_IN_SECONDS;
+        $report_is_available = in_array($notice_state, ['partial','technical'], true)
+            && $notice_time > 0
+            && time() >= $notice_time
+            && (time() - $notice_time) < $report_window_seconds;
+        if (!$report_is_available) {
+            wp_safe_redirect(admin_url('admin.php?page=statpl-product-metrics'));
+            exit;
+        }
+        $report = $this->get_historical_import_report_summary();
+        $lifecycle = $this->get_historical_import_lifecycle_state();
+        echo '<div class="wrap"><h1>Αρχική εγκατάσταση και ιστορικό προβολών</h1>';
+        if (($lifecycle['state'] ?? '') === 'technical') {
+            echo '<p>Δεν ήταν δυνατή η ολοκλήρωση της ανάγνωσης μίας διαθέσιμης πηγής ιστορικών προβολών. Το Statora Plus συνεχίζει αυτόνομα την καταγραφή νέων προβολών προϊόντων.</p>';
+            $slimstat_probe = (string) get_option('statpl_history_slimstat_probe', '');
+            if (in_array($slimstat_probe, ['missing_tables','incompatible_schema','database_error'], true)) {
+                echo '<p><strong>SlimStat:</strong> Δεν ήταν δυνατή η ανάγνωση των ιστορικών δεδομένων του.</p>';
+            }
+        } elseif (($lifecycle['state'] ?? '') === 'partial') {
+            echo '<p>Η εισαγωγή ολοκληρώθηκε με μερικό αποτέλεσμα. Οι εγγραφές που εισήχθησαν επιτυχώς διατηρούνται και η αυτόνομη καταγραφή συνεχίζεται.</p>';
+        }
+        if (empty($report['available'])) {
+            echo '<p>Η αναλυτική αναφορά δεν είναι προσωρινά διαθέσιμη. Τα στατιστικά του καταστήματος δεν επηρεάζονται.</p></div>';
+            return;
+        }
+        echo '<p>Συγκεντρωτικά αποτελέσματα εισαγωγής ιστορικών προβολών προϊόντων.</p>';
+        echo '<table class="widefat striped"><thead><tr><th>Πηγή</th><th>Επιλέξιμες εγγραφές</th><th>Εισήχθησαν</th><th>Δεν εισήχθησαν</th><th>Σε επαναπροσπάθεια</th><th>Επιλύθηκαν με επαναπροσπάθεια</th><th>Οριστικές αποτυχίες</th><th>Αιτία αποτυχίας</th></tr></thead><tbody>';
+        if (empty($report['sources'])) {
+            echo '<tr><td colspan="8">Δεν υπάρχουν διαθέσιμα ιστορικά δεδομένα προς αναφορά.</td></tr>';
+        } else {
+            foreach ($report['sources'] as $row) {
+                echo '<tr><td>' . esc_html((string) $row['source_name']) . '</td><td>' . esc_html((string) (int) $row['eligible']) . '</td><td>' . esc_html((string) (int) $row['imported']) . '</td><td>' . esc_html((string) (int) $row['not_imported']) . '</td><td>' . esc_html((string) (int) $row['pending_retries']) . '</td><td>' . esc_html((string) (int) $row['retry_resolved']) . '</td><td>' . esc_html((string) (int) $row['final_failures']) . '</td><td>' . ((int) $row['failed'] > 0 ? 'Ορισμένες εγγραφές δεν μπόρεσαν να καταγραφούν μετά από επαναπροσπάθειες.' : '—') . '</td></tr>';
+            }
+        }
+        echo '</tbody></table>';
+        if ((int) $report['failed'] > 0) {
+            echo '<h2>Τι σημαίνουν τα αποτελέσματα</h2><p>Ορισμένες ιστορικές εγγραφές δεν ήταν δυνατό να εισαχθούν. Οι επιτυχημένες εισαγωγές διατηρούνται και το Statora Plus συνεχίζει κανονικά την αυτόνομη καταγραφή νέων προβολών.</p>';
+        }
+        echo '<p>Η αναφορά περιέχει μόνο συγκεντρωτικά αποτελέσματα. Δεν αποθηκεύονται ή εμφανίζονται προσωπικά στοιχεία επισκεπτών.</p></div>';
+    }
+
+    /** Verify every required column before persisting a schema-version marker. */
+    private function verify_historical_table_columns($table, $required_columns) {
+        global $wpdb;
+
+        if (!is_object($wpdb) || !isset($wpdb->last_error) || !is_string($table) || !is_array($required_columns)) {
+            return false;
+        }
+
+        // Only Statora-owned tables may be inspected by this helper. Validate the
+        // complete identifier here rather than relying on each caller to do so.
+        $allowed_tables = [
+            $this->views_table,
+            $this->events_table,
+            $this->order_events_table,
+            $this->order_items_table,
+            $this->view_imports_table,
+            $this->view_import_state_table,
+            $this->view_import_events_table,
+            $this->view_import_failures_table,
+            $this->view_sources_table,
+            $this->view_source_origins_table,
+            $this->view_source_state_table,
+            $this->view_source_events_table,
+            $this->view_source_failures_table,
+            $this->view_source_reconciliation_table,
+            $this->view_source_reconciliation_history_table,
+            $this->historical_import_report_table,
+        ];
+        if (!in_array($table, $allowed_tables, true) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+            return false;
+        }
+        foreach ($required_columns as $column) {
+            if (!is_string($column) || !preg_match('/^[A-Za-z0-9_]+$/D', $column)) {
+                return false;
+            }
+        }
+
+        // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is restricted to the explicit Statora-owned table allowlist and quoted as one identifier.
+        $rows = statpl_db_get_results("SHOW COLUMNS FROM `{$table}`", ARRAY_A);
+        if ($wpdb->last_error !== '' || !is_array($rows)) {
+            return false;
+        }
+
+        $found = [];
+        foreach ($rows as $row) {
+            if (isset($row['Field'])) {
+                $found[$row['Field']] = true;
+            }
+        }
+
+        foreach ($required_columns as $column) {
+            if (!isset($found[$column])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private function maybe_upgrade_view_import_schema() {
+    global $wpdb;
+
+    $schema_version = get_option('statpl_view_import_schema_version', '');
+
+    if ($schema_version === self::VIEW_IMPORT_SCHEMA_VERSION) {
+        return;
+    }
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    $collate = $wpdb->get_charset_collate();
+
+    dbDelta("CREATE TABLE {$this->view_imports_table} (
+        id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+        source VARCHAR(50) NOT NULL,
+        product_id BIGINT(20) UNSIGNED NOT NULL,
+        imported_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+        imported_at DATETIME NOT NULL,
+        PRIMARY KEY  (id),
+        UNIQUE KEY source_product (source, product_id),
+        KEY imported_at (imported_at)
+    ) $collate;");
+
+    $table_exists = statpl_db_get_var(
+        statpl_db_prepare(
+            'SHOW TABLES LIKE %s',
+            $wpdb->esc_like($this->view_imports_table)
+        )
+    );
+
+    if ($table_exists === $this->view_imports_table && $this->verify_historical_table_columns($this->view_imports_table, ['id', 'source', 'product_id', 'imported_views', 'imported_at'])) {
+        if (!$this->persist_schema_version_marker('statpl_view_import_schema_version', self::VIEW_IMPORT_SCHEMA_VERSION)) { return false; }
+    }
+}
+private function maybe_upgrade_view_import_state_schema() {
+    global $wpdb;
+
+    $schema_version = get_option('statpl_view_import_state_schema_version', '');
+
+    if ($schema_version === self::VIEW_IMPORT_STATE_SCHEMA_VERSION) {
+        return;
+    }
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    $collate = $wpdb->get_charset_collate();
+
+    dbDelta("CREATE TABLE {$this->view_import_state_table} (
+        source VARCHAR(50) NOT NULL,
+            snapshot_max_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            snapshot_active_max_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            snapshot_archive_max_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            last_processed_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (source)
+    ) $collate;");
+
+    $table_exists = statpl_db_get_var(
+        statpl_db_prepare(
+            'SHOW TABLES LIKE %s',
+            $wpdb->esc_like($this->view_import_state_table)
+        )
+    );
+
+    if ($table_exists === $this->view_import_state_table && $this->verify_historical_table_columns($this->view_import_state_table, ['source', 'snapshot_max_id', 'snapshot_active_max_id', 'snapshot_archive_max_id', 'last_processed_id', 'status', 'updated_at'])) {
+        if (!$this->persist_schema_version_marker('statpl_view_import_state_schema_version', self::VIEW_IMPORT_STATE_SCHEMA_VERSION)) { return false; }
+    }
+}
+
+private function maybe_upgrade_view_import_events_schema() {
+    global $wpdb;
+
+    $schema_version = get_option('statpl_view_import_events_schema_version', '');
+
+    if ($schema_version === self::VIEW_IMPORT_EVENTS_SCHEMA_VERSION) {
+        return;
+    }
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    $collate = $wpdb->get_charset_collate();
+
+    dbDelta("CREATE TABLE {$this->view_import_events_table} (
+        id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source VARCHAR(50) NOT NULL,
+            source_view_id BIGINT(20) UNSIGNED NOT NULL,
+            product_id BIGINT(20) UNSIGNED NOT NULL,
+            imported_at DATETIME NOT NULL,
+            counts_applied TINYINT(1) UNSIGNED NOT NULL DEFAULT 1,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_view (source, source_view_id),
+            KEY product_id (product_id)
+    ) $collate;");
+
+    $table_exists = statpl_db_get_var(
+        statpl_db_prepare(
+            'SHOW TABLES LIKE %s',
+            $wpdb->esc_like($this->view_import_events_table)
+        )
+    );
+
+    $column_exists = false;
+
+    if ($table_exists === $this->view_import_events_table) {
+        // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The table identifier is built from the WordPress prefix and a fixed plugin suffix.
+        $column_exists = statpl_db_get_var(
+            statpl_db_prepare(
+                "SHOW COLUMNS FROM {$this->view_import_events_table} LIKE %s",
+                'counts_applied'
+            )
+        );
+    }
+
+    if (
+        $table_exists === $this->view_import_events_table
+        && 'counts_applied' === $column_exists
+        && $this->verify_historical_table_columns($this->view_import_events_table, ['id', 'source', 'source_view_id', 'product_id', 'imported_at', 'counts_applied'])
+    ) {
+        if (!$this->persist_schema_version_marker('statpl_view_import_events_schema_version', self::VIEW_IMPORT_EVENTS_SCHEMA_VERSION)) { return false; }
+    }
+}
+
+private function maybe_upgrade_view_import_failures_schema() {
+    global $wpdb;
+
+    $schema_version = get_option('statpl_view_import_failures_schema_version', '');
+
+    if ($schema_version === self::VIEW_IMPORT_FAILURES_SCHEMA_VERSION) {
+        return;
+    }
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    $collate = $wpdb->get_charset_collate();
+
+    dbDelta("CREATE TABLE {$this->view_import_failures_table} (
+        id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+        source VARCHAR(50) NOT NULL,
+        source_view_id BIGINT(20) UNSIGNED NOT NULL,
+        product_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+        attempts INT(10) UNSIGNED NOT NULL DEFAULT 0,
+        last_error TEXT NOT NULL,
+        status VARCHAR(20) NOT NULL DEFAULT 'retry',
+        updated_at DATETIME NOT NULL,
+        PRIMARY KEY  (id),
+        UNIQUE KEY source_view (source, source_view_id),
+        KEY status (status)
+    ) $collate;");
+
+    $table_exists = statpl_db_get_var(
+        statpl_db_prepare(
+            'SHOW TABLES LIKE %s',
+            $wpdb->esc_like($this->view_import_failures_table)
+        )
+    );
+
+    if ($table_exists === $this->view_import_failures_table && $this->verify_historical_table_columns($this->view_import_failures_table, ['id', 'source', 'source_view_id', 'product_id', 'attempts', 'last_error', 'status', 'updated_at'])) {
+        if (!$this->persist_schema_version_marker('statpl_view_import_failures_schema_version', self::VIEW_IMPORT_FAILURES_SCHEMA_VERSION)) { return false; }
+    }
+}
+
+private function maybe_upgrade_view_source_schema() {
+    global $wpdb;
+
+    $schema_version = self::VIEW_SOURCE_SCHEMA_VERSION;
+    if (get_option('statpl_view_source_schema_version', '') === $schema_version) {
+        return true;
+    }
+
+    $collate = $wpdb->get_charset_collate();
+
+    $tables = [
+        $this->view_sources_table,
+        $this->view_source_origins_table,
+        $this->view_source_state_table,
+        $this->view_source_events_table,
+        $this->view_source_failures_table,
+        $this->view_source_reconciliation_table,
+        $this->view_source_reconciliation_history_table,
+    ];
+
+    $definitions = [
+        $this->view_sources_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'source_key' => ['varchar(100)', 'NO', null, false],
+                'adapter_key' => ['varchar(100)', 'YES', null, false],
+                'display_name' => ['varchar(191)', 'NO', null, false],
+                'adapter_version' => ['varchar(32)', 'NO', null, false],
+                'granularity' => ['varchar(20)', 'NO', null, false],
+                'status' => ['varchar(20)', 'NO', 'detected', false],
+                'created_at' => ['datetime', 'NO', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'source_key' => [true, ['source_key']],
+                'status' => [false, ['status']],
+            ],
+        ],
+        $this->view_source_origins_table => [
+            'columns' => [
+                'source_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'origin_key' => ['varchar(100)', 'NO', null, false],
+                'adapter_key' => ['varchar(100)', 'NO', null, false],
+                'capabilities' => ['longtext', 'YES', null, false],
+                'snapshot_data' => ['longtext', 'YES', null, false],
+                'checkpoint_data' => ['longtext', 'YES', null, false],
+                'detection_status' => ['varchar(20)', 'NO', 'unknown', false],
+                'status' => ['varchar(20)', 'NO', 'pending', false],
+                'last_error' => ['text', 'YES', null, false],
+                'started_at' => ['datetime', 'YES', null, false],
+                'completed_at' => ['datetime', 'YES', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['source_id', 'origin_key']],
+                'status' => [false, ['status']],
+            ],
+        ],
+        $this->view_source_state_table => [
+            'columns' => [
+                'source_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'snapshot_data' => ['longtext', 'YES', null, false],
+                'checkpoint_data' => ['longtext', 'YES', null, false],
+                'status' => ['varchar(20)', 'NO', 'pending', false],
+                'last_error' => ['text', 'YES', null, false],
+                'started_at' => ['datetime', 'YES', null, false],
+                'completed_at' => ['datetime', 'YES', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['source_id']],
+                'status' => [false, ['status']],
+            ],
+        ],
+        $this->view_source_events_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'source_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'source_record_key' => ['varchar(191)', 'NO', null, false],
+                'source_record_hash' => ['char(64)', 'NO', null, false],
+                'product_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'record_type' => ['varchar(20)', 'NO', 'event', false],
+                'period_start' => ['datetime', 'YES', null, false],
+                'period_end' => ['datetime', 'YES', null, false],
+                'observed_views' => ['bigint(20) unsigned', 'NO', '0', false],
+                'applied_views' => ['bigint(20) unsigned', 'NO', '0', false],
+                'source_fingerprint' => ['char(64)', 'YES', null, false],
+                'status' => ['varchar(20)', 'NO', 'pending', false],
+                'created_at' => ['datetime', 'NO', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'source_record' => [true, ['source_id', 'source_record_hash']],
+                'product_id' => [false, ['product_id']],
+                'source_product' => [false, ['source_id', 'product_id']],
+                'source_fingerprint' => [false, ['source_fingerprint']],
+                'product_record_period' => [false, ['product_id', 'record_type', 'period_start', 'period_end']],
+                'status' => [false, ['status']],
+            ],
+        ],
+        $this->view_source_reconciliation_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'event_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'status' => ['varchar(30)', 'NO', 'unprocessed', false],
+                'reason_code' => ['varchar(100)', 'NO', null, false],
+                'reason' => ['text', 'YES', null, false],
+                'matched_event_id' => ['bigint(20) unsigned', 'YES', null, false],
+                'evidence' => ['longtext', 'YES', null, false],
+                'algorithm_version' => ['varchar(32)', 'NO', null, false],
+                'created_at' => ['datetime', 'NO', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'event_id' => [true, ['event_id']],
+                'status' => [false, ['status']],
+                'matched_event_id' => [false, ['matched_event_id']],
+            ],
+        ],
+        $this->view_source_reconciliation_history_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'event_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'previous_status' => ['varchar(30)', 'YES', null, false],
+                'new_status' => ['varchar(30)', 'NO', null, false],
+                'reason_code' => ['varchar(100)', 'NO', null, false],
+                'reason' => ['text', 'YES', null, false],
+                'matched_event_id' => ['bigint(20) unsigned', 'YES', null, false],
+                'evidence' => ['longtext', 'YES', null, false],
+                'algorithm_version' => ['varchar(32)', 'NO', null, false],
+                'created_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'event_id' => [false, ['event_id']],
+                'created_at' => [false, ['created_at']],
+            ],
+        ],
+        $this->view_source_failures_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'source_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'origin_key' => ['varchar(100)', 'NO', null, false],
+                'source_record_key' => ['varchar(191)', 'NO', null, false],
+                'source_record_hash' => ['char(64)', 'NO', null, false],
+                'product_id' => ['bigint(20) unsigned', 'NO', '0', false],
+                'attempts' => ['int(10) unsigned', 'NO', '0', false],
+                'last_error' => ['text', 'NO', null, false],
+                'status' => ['varchar(20)', 'NO', 'retry', false],
+                'next_retry_at' => ['datetime', 'YES', null, false],
+                'retry_checkpoint' => ['longtext', 'YES', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'source_record' => [true, ['source_id', 'source_record_hash']],
+                'status_retry' => [false, ['status', 'next_retry_at']],
+                'source_origin' => [false, ['source_id', 'origin_key']],
+                'product_id' => [false, ['product_id']],
+            ],
+        ],
+    ];
+
+    $sql = [
+        "CREATE TABLE {$this->view_sources_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source_key VARCHAR(100) NOT NULL,
+            adapter_key VARCHAR(100) NULL DEFAULT NULL,
+            display_name VARCHAR(191) NOT NULL,
+            adapter_version VARCHAR(32) NOT NULL,
+            granularity VARCHAR(20) NOT NULL,
+            status VARCHAR(20) NOT NULL DEFAULT 'detected',
+            created_at DATETIME NOT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_key (source_key),
+            KEY status (status)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_origins_table} (
+            source_id BIGINT(20) UNSIGNED NOT NULL,
+            origin_key VARCHAR(100) NOT NULL,
+            adapter_key VARCHAR(100) NOT NULL,
+            capabilities LONGTEXT NULL DEFAULT NULL,
+            snapshot_data LONGTEXT NULL DEFAULT NULL,
+            checkpoint_data LONGTEXT NULL DEFAULT NULL,
+            detection_status VARCHAR(20) NOT NULL DEFAULT 'unknown',
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
+            last_error TEXT NULL DEFAULT NULL,
+            started_at DATETIME NULL DEFAULT NULL,
+            completed_at DATETIME NULL DEFAULT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (source_id, origin_key),
+            KEY status (status)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_state_table} (
+            source_id BIGINT(20) UNSIGNED NOT NULL,
+            snapshot_data LONGTEXT NULL DEFAULT NULL,
+            checkpoint_data LONGTEXT NULL DEFAULT NULL,
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
+            last_error TEXT NULL DEFAULT NULL,
+            started_at DATETIME NULL DEFAULT NULL,
+            completed_at DATETIME NULL DEFAULT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (source_id),
+            KEY status (status)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_events_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source_id BIGINT(20) UNSIGNED NOT NULL,
+            source_record_key VARCHAR(191) NOT NULL,
+            source_record_hash CHAR(64) NOT NULL,
+            product_id BIGINT(20) UNSIGNED NOT NULL,
+            record_type VARCHAR(20) NOT NULL DEFAULT 'event',
+            period_start DATETIME NULL DEFAULT NULL,
+            period_end DATETIME NULL DEFAULT NULL,
+            observed_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            applied_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            source_fingerprint CHAR(64) NULL DEFAULT NULL,
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
+            created_at DATETIME NOT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_record (source_id, source_record_hash),
+            KEY product_id (product_id),
+            KEY source_product (source_id, product_id),
+            KEY source_fingerprint (source_fingerprint),
+            KEY product_record_period (product_id, record_type, period_start, period_end),
+            KEY status (status)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_failures_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source_id BIGINT(20) UNSIGNED NOT NULL,
+            origin_key VARCHAR(100) NOT NULL,
+            source_record_key VARCHAR(191) NOT NULL,
+            source_record_hash CHAR(64) NOT NULL,
+            product_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            attempts INT(10) UNSIGNED NOT NULL DEFAULT 0,
+            last_error TEXT NOT NULL,
+            status VARCHAR(20) NOT NULL DEFAULT 'retry',
+            next_retry_at DATETIME NULL DEFAULT NULL,
+            retry_checkpoint LONGTEXT NULL DEFAULT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_record (source_id, source_record_hash),
+            KEY status_retry (status, next_retry_at),
+            KEY source_origin (source_id, origin_key),
+            KEY product_id (product_id)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_reconciliation_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            event_id BIGINT(20) UNSIGNED NOT NULL,
+            status VARCHAR(30) NOT NULL DEFAULT 'unprocessed',
+            reason_code VARCHAR(100) NOT NULL,
+            reason TEXT NULL DEFAULT NULL,
+            matched_event_id BIGINT(20) UNSIGNED NULL DEFAULT NULL,
+            evidence LONGTEXT NULL DEFAULT NULL,
+            algorithm_version VARCHAR(32) NOT NULL,
+            created_at DATETIME NOT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY event_id (event_id),
+            KEY status (status),
+            KEY matched_event_id (matched_event_id)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_reconciliation_history_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            event_id BIGINT(20) UNSIGNED NOT NULL,
+            previous_status VARCHAR(30) NULL DEFAULT NULL,
+            new_status VARCHAR(30) NOT NULL,
+            reason_code VARCHAR(100) NOT NULL,
+            reason TEXT NULL DEFAULT NULL,
+            matched_event_id BIGINT(20) UNSIGNED NULL DEFAULT NULL,
+            evidence LONGTEXT NULL DEFAULT NULL,
+            algorithm_version VARCHAR(32) NOT NULL,
+            created_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            KEY event_id (event_id),
+            KEY created_at (created_at)
+        ) ENGINE=InnoDB $collate;",
+    ];
+
+    $fail = static function ($message) {
+        // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Preserve an actionable migration failure in the PHP error log when schema setup cannot complete.
+        error_log('[Statora Plus] View-source schema migration failed: ' . $message);
+        return false;
+    };
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    try {
+        foreach ($sql as $statement) {
+            dbDelta($statement);
+        }
+    } catch (Throwable $e) {
+        return $fail($e->getMessage());
+    }
+
+    // Convert legacy detection values out of the processing-status column.
+    // Existing processing states are preserved; only legacy detection labels are migrated.
+    $legacy_status_migration = statpl_db_query(
+        "UPDATE {$this->view_source_origins_table}
+         SET detection_status = CASE
+                 WHEN status IN ('available', 'missing_table', 'incompatible_schema', 'database_error')
+                     THEN status
+                 ELSE 'unknown'
+             END,
+             status = 'pending'
+         WHERE status IN ('detected', 'available', 'missing_table', 'incompatible_schema', 'database_error')"
+    );
+
+    if ($legacy_status_migration === false || $wpdb->last_error !== '') {
+        return $fail('Could not migrate legacy origin detection statuses: ' . $wpdb->last_error);
+    }
+
+    foreach ($tables as $table) {
+        // The migration metadata is the allowlist for identifiers used by the
+        // SHOW COLUMNS / SHOW INDEX statements below. Reject anything outside it.
+        if (
+            !is_string($table)
+            || !array_key_exists($table, $definitions)
+            || !preg_match('/^[A-Za-z0-9_]+$/D', $table)
+        ) {
+            return $fail('Invalid internal table identifier during schema verification.');
+        }
+
+        $found_table = statpl_db_get_var(
+            statpl_db_prepare(
+                'SHOW TABLES LIKE %s',
+                $wpdb->esc_like($table)
+            )
+        );
+
+        if ($wpdb->last_error !== '') {
+            return $fail('Could not inspect table existence for ' . $table . ': ' . $wpdb->last_error);
+        }
+
+        if ($found_table !== $table) {
+            return $fail('Required table was not created: ' . $table);
+        }
+
+        $table_status = statpl_db_get_row(
+            statpl_db_prepare(
+                'SHOW TABLE STATUS LIKE %s',
+                $wpdb->esc_like($table)
+            ),
+            ARRAY_A
+        );
+
+        if ($wpdb->last_error !== '') {
+            return $fail('Could not inspect table engine for ' . $table . ': ' . $wpdb->last_error);
+        }
+
+        if (!$table_status || !isset($table_status['Engine']) || strcasecmp($table_status['Engine'], 'InnoDB') !== 0) {
+            return $fail('Table engine is not InnoDB: ' . $table);
+        }
+
+        // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Identifier is built from the trusted WordPress prefix and fixed plugin suffix.
+        $column_rows = statpl_db_get_results("SHOW COLUMNS FROM `{$table}`", ARRAY_A);
+
+        if ($wpdb->last_error !== '') {
+            return $fail('Could not inspect columns for ' . $table . ': ' . $wpdb->last_error);
+        }
+
+        if (!is_array($column_rows)) {
+            return $fail('Invalid column metadata for ' . $table);
+        }
+
+        $actual_columns = [];
+        foreach ($column_rows as $column) {
+            $actual_columns[$column['Field']] = $column;
+        }
+
+        $expected_columns = $definitions[$table]['columns'];
+
+        if (count($actual_columns) !== count($expected_columns)) {
+            return $fail('Unexpected column count in ' . $table);
+        }
+
+        foreach ($expected_columns as $name => $expected) {
+            if (!isset($actual_columns[$name])) {
+                return $fail('Missing column ' . $table . '.' . $name);
+            }
+
+            $actual = $actual_columns[$name];
+            $actual_type = strtolower((string) $actual['Type']);
+            $actual_null = strtoupper((string) $actual['Null']);
+            $actual_default = $actual['Default'];
+            $actual_extra = strtolower(trim((string) $actual['Extra']));
+            $actual_extra = preg_replace('/\\s+/', ' ', $actual_extra);
+            $expected_extra = $expected[3] ? 'auto_increment' : '';
+
+            if ($actual_type !== $expected[0]) {
+                return $fail('Wrong type for ' . $table . '.' . $name . ': ' . $actual_type);
+            }
+
+            if ($actual_null !== $expected[1]) {
+                return $fail('Wrong NULL definition for ' . $table . '.' . $name);
+            }
+
+            if ($expected[2] === null) {
+                if ($actual_default !== null) {
+                    return $fail('Unexpected default for ' . $table . '.' . $name);
+                }
+            } elseif ((string) $actual_default !== $expected[2]) {
+                return $fail('Wrong default for ' . $table . '.' . $name);
+            }
+
+            if ($actual_extra !== $expected_extra) {
+                return $fail('Wrong Extra definition for ' . $table . '.' . $name . ': ' . $actual_extra);
+            }
+        }
+
+        // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Identifier is built from the trusted WordPress prefix and fixed plugin suffix.
+        $index_rows = statpl_db_get_results("SHOW INDEX FROM `{$table}`", ARRAY_A);
+
+        if ($wpdb->last_error !== '') {
+            return $fail('Could not inspect indexes for ' . $table . ': ' . $wpdb->last_error);
+        }
+
+        if (!is_array($index_rows)) {
+            return $fail('Invalid index metadata for ' . $table);
+        }
+
+        $actual_indexes = [];
+        foreach ($index_rows as $index) {
+            $key_name = $index['Key_name'];
+
+            if (!isset($actual_indexes[$key_name])) {
+                $actual_indexes[$key_name] = [
+                    'unique' => ((int) $index['Non_unique'] === 0),
+                    'columns' => [],
+                ];
+            } elseif ($actual_indexes[$key_name]['unique'] !== ((int) $index['Non_unique'] === 0)) {
+                return $fail('Inconsistent uniqueness metadata for index ' . $table . '.' . $key_name);
+            }
+
+            $sequence = (string) $index['Seq_in_index'];
+            if (!preg_match('/^[1-9][0-9]*$/D', $sequence)) {
+                return $fail('Invalid Seq_in_index for ' . $table . '.' . $key_name);
+            }
+
+            $sequence = (int) $sequence;
+            if (isset($actual_indexes[$key_name]['columns'][$sequence])) {
+                return $fail('Duplicate Seq_in_index for ' . $table . '.' . $key_name);
+            }
+
+            if (!array_key_exists('Sub_part', $index) || $index['Sub_part'] !== null) {
+                return $fail('Unexpected index prefix length for ' . $table . '.' . $key_name);
+            }
+
+            $actual_indexes[$key_name]['columns'][$sequence] = $index['Column_name'];
+        }
+
+        foreach ($actual_indexes as $key_name => &$index_data) {
+            ksort($index_data['columns']);
+            $positions = array_keys($index_data['columns']);
+
+            if ($positions !== range(1, count($positions))) {
+                return $fail('Non-contiguous Seq_in_index for ' . $table . '.' . $key_name);
+            }
+
+            $index_data['columns'] = array_values($index_data['columns']);
+        }
+        unset($index_data);
+
+        $expected_indexes = $definitions[$table]['indexes'];
+
+        if (count($actual_indexes) !== count($expected_indexes)) {
+            return $fail('Unexpected index count in ' . $table);
+        }
+
+        foreach ($expected_indexes as $name => $expected) {
+            if (!isset($actual_indexes[$name])) {
+                return $fail('Missing index ' . $table . '.' . $name);
+            }
+
+            if (
+                $actual_indexes[$name]['unique'] !== $expected[0]
+                || $actual_indexes[$name]['columns'] !== $expected[1]
+            ) {
+                return $fail('Incorrect index definition for ' . $table . '.' . $name);
+            }
+        }
+    }
+
+    update_option('statpl_view_source_schema_version', $schema_version, false);
+
+    if (get_option('statpl_view_source_schema_version', '') !== $schema_version) {
+        return $fail('Could not persist the verified view-source schema version.');
+    }
+
+    return true;
+}
+
+    /**
+     * Reclassify legacy aggregate matches that relied on the synthetic
+     * product/date/count fingerprint. This is audit-only: totals and
+     * applied_views are deliberately not modified because the old records
+     * cannot prove whether the underlying views were actually duplicated.
+     */
+    private function migrate_legacy_aggregate_fingerprint_matches() {
+        global $wpdb;
+
+        $complete_option = 'statpl_legacy_aggregate_fp_migration_v1_complete';
+        $cursor_option = 'statpl_legacy_aggregate_fp_migration_v1_cursor';
+        if (get_option($complete_option, '') === '1') {
+            return true;
+        }
+
+        $lock_name = 'statpl_legacy_agg_' . substr(hash('sha256', $wpdb->prefix), 0, 40);
+        $migration_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($migration_lock['acquired'])) {
+            $this->schedule_legacy_aggregate_reconciliation_migration(60);
+            return false;
+        }
+
+        $batch_size = 100;
+        $cursor = max(0, (int) get_option($cursor_option, 0));
+        $processed = 0;
+        $failed = false;
+        $migration_transaction_started = false;
+        $migration_transaction_committed = false;
+
+        try {
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                "SELECT r.event_id, r.status, r.reason_code, r.reason, r.matched_event_id,
+                        r.evidence, r.algorithm_version,
+                        e.source_id, e.product_id, e.record_type, e.observed_views,
+                        e.period_start, e.period_end, e.source_fingerprint,
+                        m.source_id AS matched_source_id,
+                        m.record_type AS matched_record_type,
+                        m.source_fingerprint AS matched_source_fingerprint
+                 FROM {$this->view_source_reconciliation_table} r
+                 INNER JOIN {$this->view_source_events_table} e ON e.id = r.event_id
+                 INNER JOIN {$this->view_source_events_table} m ON m.id = r.matched_event_id
+                 WHERE r.event_id > %d
+                   AND r.status = 'matched_exact'
+                   AND r.reason_code = 'shared_fingerprint_exact_match'
+                   AND e.record_type = 'aggregate'
+                   AND m.record_type = 'aggregate'
+                   AND e.source_id <> m.source_id
+                 ORDER BY r.event_id ASC
+                 LIMIT %d",
+                $cursor,
+                $batch_size
+            ), ARRAY_A);
+
+            if (!is_array($rows)) {
+                $failed = true;
+                return false;
+            }
+
+            foreach ($rows as $row) {
+                $event_id = (int) $row['event_id'];
+                $expected_fingerprint = '';
+                if ($row['period_start'] !== null && $row['period_end'] !== null) {
+                    $expected_fingerprint = hash(
+                        'sha256',
+                        "statpl-product-day-aggregate-v1\0"
+                        . (int) $row['product_id'] . "\0"
+                        . (string) $row['period_start'] . "\0"
+                        . (string) $row['period_end'] . "\0"
+                        . (int) $row['observed_views']
+                    );
+                }
+
+                $is_legacy_synthetic_match = $expected_fingerprint !== ''
+                    && is_string($row['source_fingerprint'])
+                    && is_string($row['matched_source_fingerprint'])
+                    && hash_equals($expected_fingerprint, strtolower($row['source_fingerprint']))
+                    && hash_equals($expected_fingerprint, strtolower($row['matched_source_fingerprint']));
+
+                if ($is_legacy_synthetic_match) {
+                    $evidence = json_decode((string) $row['evidence'], true);
+                    if (!is_array($evidence)) {
+                        $evidence = ['legacy_evidence_raw' => (string) $row['evidence']];
+                    }
+                    $evidence['legacy_reclassification'] = [
+                        'migration' => 'legacy_aggregate_fingerprint_v1',
+                        'previous_status' => 'matched_exact',
+                        'new_status' => 'legacy_exact_unverified',
+                        'reason' => 'The previous synthetic fingerprint represented product, date and count, not a shared view-event identity. The old exact-match decision is therefore unverified.',
+                        'totals_changed' => false,
+                        'applied_views_changed' => false,
+                    ];
+                    $encoded_evidence = wp_json_encode($evidence);
+                    if (!is_string($encoded_evidence)) {
+                        $failed = true;
+                        return false;
+                    }
+
+                    if (!$this->generic_advisory_lock_session_is_current($migration_lock)) {
+                        $failed = true;
+                        return false;
+                    }
+
+                    $migration_transaction_started = false;
+                    $migration_transaction_committed = false;
+                    $transaction_started = (statpl_db_query('START TRANSACTION') !== false);
+                    if (!$transaction_started) {
+                        $failed = true;
+                        return false;
+                    }
+
+                    $migration_transaction_started = true;
+                    if (!$this->generic_advisory_lock_session_is_current($migration_lock)) {
+                        // Lock ownership and connection identity are separate checks.
+                        // Roll back only when this is still the original DB session.
+                        if ($this->generic_db_session_matches_lock($migration_lock)) {
+                            statpl_db_query('ROLLBACK');
+                            $migration_transaction_started = false;
+                        }
+                        $failed = true;
+                        return false;
+                    }
+                    $updated = statpl_db_update(
+                        $this->view_source_reconciliation_table,
+                        [
+                            'status' => 'legacy_exact_unverified',
+                            'reason_code' => 'legacy_aggregate_fingerprint_unverified',
+                            'reason' => 'Legacy exact match based on product/date/count only; actual shared view identity was not established. Totals were intentionally left unchanged pending a controlled reconciliation decision.',
+                            'evidence' => $encoded_evidence,
+                            'algorithm_version' => '1.2.0',
+                            'updated_at' => current_time('mysql'),
+                        ],
+                        ['event_id' => $event_id, 'status' => 'matched_exact']
+                    );
+                    $history = $updated === 1 ? statpl_db_insert(
+                        $this->view_source_reconciliation_history_table,
+                        [
+                            'event_id' => $event_id,
+                            'previous_status' => 'matched_exact',
+                            'new_status' => 'legacy_exact_unverified',
+                            'reason_code' => 'legacy_aggregate_fingerprint_unverified',
+                            'reason' => 'Reclassified because the legacy aggregate fingerprint did not prove shared view-event identity. No totals or applied_views were changed.',
+                            'matched_event_id' => (int) $row['matched_event_id'],
+                            'evidence' => $encoded_evidence,
+                            'algorithm_version' => '1.2.0',
+                            'created_at' => current_time('mysql'),
+                        ]
+                    ) : false;
+
+                    if ($updated !== 1 || $history !== 1
+                        || !$this->generic_advisory_lock_session_is_current($migration_lock)
+                        || statpl_db_query('COMMIT') === false) {
+                        // Roll back only if the original lock-owning session is still current.
+                        // A reconnect implicitly abandons the old transaction; never issue
+                        // transaction control against an unverified replacement session.
+                        if ($migration_transaction_started && $this->generic_db_session_matches_lock($migration_lock)) {
+                            statpl_db_query('ROLLBACK');
+                            $migration_transaction_started = false;
+                        }
+                        $failed = true;
+                        return false;
+                    }
+                    $migration_transaction_committed = true;
+                    $migration_transaction_started = false;
+                }
+
+                $cursor = $event_id;
+                // Persist the cursor only while this exact MySQL session still owns
+                // the migration lock. A PHP-level check followed by update_option()
+                // would leave a reconnect race between the check and the write.
+                $cursor_persisted = statpl_db_query(statpl_db_prepare(
+                    "INSERT INTO {$wpdb->options} (option_name, option_value, autoload)
+                     SELECT %s, %s, 'no'
+                     WHERE IS_USED_LOCK(%s) = CONNECTION_ID()
+                     ON DUPLICATE KEY UPDATE option_value = IF(
+                         IS_USED_LOCK(%s) = CONNECTION_ID(),
+                         VALUES(option_value),
+                         option_value
+                     )",
+                    $cursor_option,
+                    (string) $cursor,
+                    $lock_name,
+                    $lock_name
+                ));
+                if (!in_array($cursor_persisted, [0, 1, 2], true)
+                    || !$this->generic_advisory_lock_session_is_current($migration_lock)) {
+                    $failed = true;
+                    return false;
+                }
+                $persisted_cursor = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                    $cursor_option
+                ));
+                if (!empty($wpdb->last_error) || (int) $persisted_cursor !== $cursor) {
+                    $failed = true;
+                    return false;
+                }
+                $processed++;
+            }
+
+            if (count($rows) < $batch_size) {
+                // Completion is also lock-owner guarded so a stale/reconnected
+                // worker cannot mark an unfinished migration complete.
+                $complete_persisted = statpl_db_query(statpl_db_prepare(
+                    "INSERT INTO {$wpdb->options} (option_name, option_value, autoload)
+                     SELECT %s, '1', 'no'
+                     WHERE IS_USED_LOCK(%s) = CONNECTION_ID()
+                     ON DUPLICATE KEY UPDATE option_value = IF(
+                         IS_USED_LOCK(%s) = CONNECTION_ID(), '1', option_value
+                     )",
+                    $complete_option,
+                    $lock_name,
+                    $lock_name
+                ));
+                $persisted_completion = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                    $complete_option
+                ));
+                $completion_verified = in_array($complete_persisted, [0, 1, 2], true)
+                    && $this->generic_advisory_lock_session_is_current($migration_lock)
+                    && empty($wpdb->last_error)
+                    && (string) $persisted_completion === '1';
+                if (!$completion_verified) {
+                    $failed = true;
+                }
+                return $completion_verified;
+            }
+
+            $this->schedule_legacy_aggregate_reconciliation_migration(30);
+            return true;
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Legacy aggregate reconciliation audit migration failed: ' . $exception->getMessage());
+            }
+            $failed = true;
+            return false;
+        } finally {
+            if ($migration_transaction_started && !$migration_transaction_committed
+                && $this->generic_db_session_matches_lock($migration_lock)) {
+                statpl_db_query('ROLLBACK');
+                $migration_transaction_started = false;
+            }
+            $this->release_generic_advisory_lock($migration_lock, 'legacy_aggregate_fingerprint_migration');
+            if ($failed) {
+                $this->schedule_legacy_aggregate_reconciliation_migration(60);
+                if (defined('WP_DEBUG') && WP_DEBUG) {
+                    $this->debug_log('[Statora Plus] Legacy aggregate reconciliation audit migration was rescheduled after a failed batch.');
+                }
+            }
+        }
+    }
+
+    /**
+     * Schedule the audit migration outside the normal frontend initialization path.
+     * Action Scheduler is preferred; WP-Cron remains the compatibility fallback.
+     */
+    public function schedule_legacy_aggregate_reconciliation_migration($delay = 15) {
+        if (get_option('statpl_legacy_aggregate_fp_migration_v1_complete', '') === '1') {
+            return;
+        }
+
+        $delay = max(5, (int) $delay);
+        $hook = 'statpl_reconcile_legacy_aggregate_fingerprints';
+        $args = [];
+        $group = 'statpl-plus';
+
+        if (function_exists('as_schedule_single_action') && !did_action('action_scheduler_init')) {
+            add_action('action_scheduler_init', [$this, 'schedule_legacy_aggregate_reconciliation_migration'], 10, 0);
+            return;
+        }
+
+        if (
+            function_exists('as_has_scheduled_action')
+            && did_action('action_scheduler_init')
+            && as_has_scheduled_action($hook, $args, $group)
+        ) {
+            return;
+        }
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $action_id = as_schedule_single_action(time() + $delay, $hook, $args, $group);
+            if ($action_id) {
+                return;
+            }
+        }
+
+        if (!wp_next_scheduled($hook, $args)) {
+            wp_schedule_single_event(time() + $delay, $hook, $args);
+        }
+    }
+
+    public function init_legacy_aggregate_reconciliation_migration() {
+        $this->migrate_legacy_aggregate_fingerprint_matches();
+    }
+
+     public function init() {
+        // Register runtime hooks before touching the database. If MySQL is
+        // temporarily unavailable during plugins_loaded, frontend/AJAX and
+        // WooCommerce hooks must still exist for the remainder of this request.
         add_action('wp_enqueue_scripts', [$this, 'enqueue_frontend']);
         add_action('wp_ajax_statpl_record_view', [$this, 'record_view']);
@@ -113 +1875 @@
         add_action('admin_menu', [$this, 'admin_menu']);
         add_action('admin_enqueue_scripts', [$this, 'enqueue_admin_styles']);
+        add_action('admin_enqueue_scripts', [$this, 'enqueue_deactivation_prompt']);
         add_action('admin_notices', [$this, 'woocommerce_notice']);
+        add_action('admin_footer', [$this, 'enqueue_historical_notice_script']);
         add_action('woocommerce_order_status_cancelled', [$this, 'record_cancel_event'], 10, 2);
         add_action('woocommerce_order_refunded', [$this, 'record_refund_event'], 10, 2);
-        // Invalidate cached aggregates when order data or status changes.
         foreach (['woocommerce_new_order', 'woocommerce_update_order', 'woocommerce_order_status_changed', 'woocommerce_order_payment_status_changed', 'woocommerce_saved_order_items'] as $hook) {
             add_action($hook, [$this, 'invalidate_order_stats_cache'], 10, 3);
         }
         add_action('woocommerce_order_refunded', [$this, 'invalidate_order_stats_cache'], 20, 2);
-        // A refund changes net quantity/revenue in the order snapshot as well as refund-event history.
         add_action('woocommerce_order_refunded', [$this, 'queue_order_snapshot'], 30, 2);
         add_action('woocommerce_before_delete_order', [$this, 'delete_order_snapshot'], 10, 1);
@@ -128 +1890 @@
         }
         add_action('statpl_import_batch', [$this, 'run_import_batch']);
+        add_action('statpl_view_import_batch', [$this, 'run_slimstat_view_import_batch']);
+        add_action('statpl_generic_view_import_batch', [$this, 'run_generic_historical_view_import_batch'], 10, 2);
+        add_action('statpl_generic_view_snapshot_retry', [$this, 'retry_generic_historical_view_snapshot'], 10, 2);
+        add_action('statpl_generic_view_retry_failed_records', [$this, 'retry_generic_historical_view_failures'], 10, 2);
         add_action('statpl_sync_order', [$this, 'sync_order_snapshot'], 10, 1);
-        if (!get_option('statpl_import_complete')) { $this->schedule_import_batch(); }
-    }
+        add_action('statpl_reconcile_legacy_aggregate_fingerprints', [$this, 'init_legacy_aggregate_reconciliation_migration']);
+
+        global $wpdb;
+        // Do not interpret failed option/table reads as missing state. A simple
+        // round-trip probe distinguishes a usable connection from a DB outage.
+        try {
+            $database_ready = isset($wpdb) && is_object($wpdb)
+                && (string) statpl_db_get_var('SELECT 1') === '1'
+                && empty($wpdb->last_error);
+        } catch (Throwable $exception) {
+            $database_ready = false;
+        }
+        if (!$database_ready) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Database unavailable during initialization; schema upgrades and historical discovery will retry on the next request. Runtime hooks remain registered.');
+            }
+            return;
+        }
+
+        try {
+            if (get_option('statpl_db_version') !== self::VERSION) {
+                // Core tables must be verified before historical schema upgrades
+                // or adapter discovery can run. A failed dbDelta pass must leave
+                // the version marker unchanged so the next request retries it.
+                if (!$this->activate()) {
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('[Statora Plus] Core schema verification failed; initialization will retry on the next request.');
+                    }
+                    return;
+                }
+            }
+            $this->maybe_upgrade_view_import_schema();
+            $this->maybe_upgrade_view_import_failures_schema();
+            $this->maybe_upgrade_view_import_state_schema();
+            $this->maybe_upgrade_view_import_events_schema();
+            $this->maybe_upgrade_view_source_schema();
+            $this->maybe_upgrade_historical_import_report_schema();
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Schema initialization interrupted; version markers remain subject to verification and initialization will retry on the next request.');
+            }
+            return;
+        }
+
+        // Schema helpers intentionally leave their version markers unchanged
+        // when verification fails. Do not let discovery/workers query partially
+        // initialized tables; the next request will retry the outstanding steps.
+        $historical_schema_ready =
+            get_option('statpl_view_import_schema_version', '') === self::VIEW_IMPORT_SCHEMA_VERSION
+            && get_option('statpl_view_import_failures_schema_version', '') === self::VIEW_IMPORT_FAILURES_SCHEMA_VERSION
+            && get_option('statpl_view_import_state_schema_version', '') === self::VIEW_IMPORT_STATE_SCHEMA_VERSION
+            && get_option('statpl_view_import_events_schema_version', '') === self::VIEW_IMPORT_EVENTS_SCHEMA_VERSION
+            && get_option('statpl_view_source_schema_version', '') === self::VIEW_SOURCE_SCHEMA_VERSION
+            && get_option('statpl_history_report_schema_version', '') === self::HISTORY_REPORT_SCHEMA_VERSION;
+        if (!$historical_schema_ready) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Historical schema is not fully verified; historical discovery and recovery are deferred until a later request.');
+            }
+            return;
+        }
+
+        // Schedule the audit migration outside the normal request path. The worker
+        // uses bounded batches and a connection-scoped lock for safe continuation.
+        $this->schedule_legacy_aggregate_reconciliation_migration(15);
+
+        // Keep each startup subsystem isolated. A scheduler or adapter-provider
+        // failure in one subsystem must not prevent the remaining durable work
+        // from being discovered and recovered on this request.
+        if (!get_option('statpl_import_complete')) {
+            try {
+                $this->schedule_import_batch();
+            } catch (Throwable $exception) {
+                if (defined('WP_DEBUG') && WP_DEBUG) {
+                    $this->debug_log('[Statora Plus] Core import scheduling failed; it will be retried on a later request.');
+                }
+            }
+        }
+
+        // SlimStat remains on its existing, independent initialization path.
+        // Contain unexpected failures at the call site so they cannot block
+        // generic adapter discovery or recovery.
+        try {
+            $slimstat_result = $this->initialize_slimstat_view_import();
+            if (isset($slimstat_result['status']) && $slimstat_result['status'] !== 'already_initialized') {
+                update_option('statpl_history_slimstat_probe', sanitize_key((string) $slimstat_result['status']), false);
+            } elseif (($slimstat_result['status'] ?? '') === 'already_initialized') {
+                $slimstat_state_status = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT status FROM {$this->view_import_state_table} WHERE source = %s", 'slimstat'
+                ));
+                if (in_array((string) $slimstat_state_status, ['pending','running'], true)) {
+                    $slimstat_probe_result = $this->get_slimstat_view_snapshot();
+                    update_option('statpl_history_slimstat_probe', sanitize_key((string) ($slimstat_probe_result['status'] ?? 'database_error')), false);
+                }
+            }
+            if (
+                is_array($slimstat_result)
+                && isset($slimstat_result['status'])
+                && in_array($slimstat_result['status'], ['initialized', 'already_initialized'], true)
+            ) {
+                try {
+                    $this->schedule_slimstat_view_import_batch();
+                } catch (Throwable $exception) {
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('[Statora Plus] SlimStat import scheduling failed; its existing recovery path will retry.');
+                    }
+                }
+            }
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] SlimStat initialization failed; generic historical sources will continue independently.');
+            }
+        }
+
+        // Discovery failure must not suppress recovery of already persisted
+        // work. Conversely, recovery is attempted even if discovery throws.
+        try {
+            $generic_result = $this->discover_historical_view_adapters();
+            update_option('statpl_history_discovery_status', sanitize_key((string) ($generic_result['status'] ?? 'unknown')), false);
+            if (!empty($generic_result['registered'])) {
+                try {
+                    $this->schedule_generic_historical_view_import_batch(15);
+                } catch (Throwable $exception) {
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('[Statora Plus] Generic historical import scheduling failed; durable work will be recovered later.');
+                    }
+                }
+            }
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Generic adapter discovery failed; persisted historical work recovery will still run.');
+            }
+        }
+
+        if (get_option('statpl_retained_deactivation_at', '') !== '') {
+            $gap_result = $this->resume_retained_history_gap();
+            if (($gap_result['status'] ?? '') === 'reset') {
+                try {
+                    $this->schedule_slimstat_view_import_batch(15);
+                } catch (Throwable $exception) {
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('[Statora Plus] Retained history recovery scheduling failed; it will be retried on a later request.');
+                    }
+                }
+            }
+        }
+
+        try {
+            $this->recover_unscheduled_generic_historical_work();
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Generic historical work recovery failed; it will be retried on a later request.');
+            }
+        }
+        $lifecycle = $this->get_historical_import_lifecycle_state();
+        update_option('statpl_history_import_state', sanitize_key((string) ($lifecycle['state'] ?? 'importing')), false);
+    }
+
     public function woocommerce_notice() {
         if (!current_user_can('manage_options') || class_exists('WooCommerce')) return;
@@ -163 +2084 @@
         $now = current_time('mysql');
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is built from the WordPress prefix and a fixed plugin suffix; this atomic view-count write must not be cached.
-        $wpdb->query($wpdb->prepare(
+        statpl_db_query(statpl_db_prepare(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Internal table identifier uses the WordPress prefix plus a fixed plugin suffix; product ID is prepared.
             "INSERT INTO {$this->views_table} (product_id, total_views) VALUES (%d, 1)
@@ -169 +2090 @@
         ));
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Event writes must be persisted immediately and cannot be cached.
-        $wpdb->insert($this->events_table, ['product_id' => $product_id, 'viewed_at' => $now], ['%d','%s']);
+        statpl_db_insert($this->events_table, ['product_id' => $product_id, 'viewed_at' => $now], ['%d','%s']);
         setcookie($cookie, '1', time() + 1200, COOKIEPATH ?: '/', COOKIE_DOMAIN, is_ssl(), true);
         $_COOKIE[$cookie] = '1';
@@ -175 +2096 @@
         $cutoff = gmdate('Y-m-d H:i:s', time() - 172800);
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is internal and the cutoff is prepared; this cleanup deletes expired rows, so caching is not applicable.
-        $wpdb->query($wpdb->prepare("DELETE FROM {$this->events_table} WHERE viewed_at < %s", get_date_from_gmt($cutoff)));
+        statpl_db_query(statpl_db_prepare("DELETE FROM {$this->events_table} WHERE viewed_at < %s", get_date_from_gmt($cutoff)));
         wp_send_json_success(['counted' => true]);
     }
@@ -187 +2108 @@
         // This prevents a later snapshot sync from making an older cancellation appear to happen today.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; the query values are prepared.
-        $event_at = $wpdb->get_var($wpdb->prepare(
+        $event_at = statpl_db_get_var(statpl_db_prepare(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; both query values are prepared.
             "SELECT MIN(event_at) FROM {$this->order_events_table} WHERE order_id = %d AND event_type = %s AND event_ref_id = 0",
@@ -280 +2201 @@
         // from being counted more than once in the store overview.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all event values are prepared.
-        $wpdb->query($wpdb->prepare(
+        statpl_db_query(statpl_db_prepare(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; all event values are prepared.
             "INSERT INTO {$this->order_events_table} (order_id, product_id, event_type, event_ref_id, event_at) VALUES (%d, 0, %s, %d, %s) ON DUPLICATE KEY UPDATE event_at=LEAST(event_at, VALUES(event_at))",
@@ -288 +2209 @@
         foreach (array_keys($product_ids) as $product_id) {
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all event values are prepared.
-            $wpdb->query($wpdb->prepare(
+            statpl_db_query(statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; all event values are prepared.
                 "INSERT INTO {$this->order_events_table} (order_id, product_id, event_type, event_ref_id, event_at) VALUES (%d, %d, %s, %d, %s) ON DUPLICATE KEY UPDATE event_at=LEAST(event_at, VALUES(event_at))",
@@ -309 +2230 @@
         // Product ID 0 is reserved for order-level dashboard aggregation.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all event values are prepared.
-        $wpdb->query($wpdb->prepare(
+        statpl_db_query(statpl_db_prepare(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; all event values are prepared.
             "INSERT INTO {$this->order_events_table} (order_id, product_id, event_type, event_ref_id, event_at) VALUES (%d, 0, %s, 0, %s) ON DUPLICATE KEY UPDATE event_at=LEAST(event_at, VALUES(event_at))",
@@ -316 +2237 @@
         foreach ($this->order_product_ids($order) as $product_id) {
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all event values are prepared.
-            $wpdb->query($wpdb->prepare(
+            statpl_db_query(statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; all event values are prepared.
                 "INSERT INTO {$this->order_events_table} (order_id, product_id, event_type, event_ref_id, event_at) VALUES (%d, %d, %s, 0, %s) ON DUPLICATE KEY UPDATE event_at=LEAST(event_at, VALUES(event_at))",
@@ -325 +2246 @@
         delete_transient('statpl_global_summary_v2');
     }
+    /** Add a two-choice confirmation dialog to this plugin's Plugins-screen action. */
+    public function enqueue_deactivation_prompt($hook_suffix) {
+        if ($hook_suffix !== 'plugins.php' || !current_user_can('activate_plugins')) {
+            return;
+        }
+        wp_enqueue_script('jquery-core');
+        $config = [
+            'plugin' => plugin_basename(__FILE__),
+            'endpoint' => admin_url('admin-post.php'),
+            'nonce' => wp_create_nonce('statpl_prepare_deactivation'),
+            'title' => 'Απενεργοποίηση Statora Plus',
+            'message' => 'Τι θέλεις να γίνει με τα στατιστικά και τα δεδομένα του Statora Plus;',
+            'retain' => 'Ναι, διατήρηση όλων των δεδομένων',
+            'delete' => 'Όχι, διαγραφή όλων των δεδομένων',
+            'cancel' => 'Ακύρωση',
+            'warning' => 'Η διαγραφή δεν μπορεί να αναιρεθεί.',
+        ];
+        wp_add_inline_script('jquery-core', 'window.StatoraDeactivatePrompt = ' . wp_json_encode($config) . ';', 'before');
+        $js = <<<'STATPL_DEACTIVATION_JS'
+(function () {
+    var cfg = window.StatoraDeactivatePrompt;
+    if (!cfg) return;
+    function findDeactivateLink(target) {
+        var link = target.closest('a');
+        if (!link) return null;
+        try {
+            var url = new URL(link.href, window.location.href);
+            if (url.searchParams.get('action') !== 'deactivate' || url.searchParams.get('plugin') !== cfg.plugin) return null;
+            return link;
+        } catch (e) { return null; }
+    }
+    document.addEventListener('click', function (event) {
+        var link = findDeactivateLink(event.target);
+        if (!link) return;
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        if (document.getElementById('statpl-deactivation-dialog')) return;
+        var dialog = document.createElement('div');
+        dialog.id = 'statpl-deactivation-dialog';
+        dialog.style.cssText = 'position:fixed;inset:0;z-index:100000;background:rgba(0,0,0,.55);display:flex;align-items:center;justify-content:center;padding:20px';
+        var panel = document.createElement('div');
+        panel.style.cssText = 'background:#fff;max-width:520px;width:100%;padding:24px;border-radius:6px;box-shadow:0 8px 32px rgba(0,0,0,.25);font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif';
+        var title = document.createElement('h2'); title.textContent = cfg.title; title.style.marginTop = '0';
+        var message = document.createElement('p'); message.textContent = cfg.message;
+        var warning = document.createElement('p'); warning.textContent = cfg.warning; warning.style.color = '#b32d2e';
+        var actions = document.createElement('div'); actions.style.cssText = 'display:flex;flex-wrap:wrap;gap:8px;margin-top:20px';
+        function button(label, choice, primary) {
+            var b = document.createElement('button'); b.type = 'button'; b.textContent = label;
+            b.className = primary ? 'button button-primary' : 'button';
+            b.addEventListener('click', function () {
+                if (!choice) { dialog.remove(); return; }
+                var destination = new URL(cfg.endpoint, window.location.href);
+                destination.searchParams.set('action', 'statpl_prepare_deactivation');
+                destination.searchParams.set('choice', choice);
+                destination.searchParams.set('_wpnonce', cfg.nonce);
+                destination.searchParams.set('redirect_to', link.href);
+                window.location.assign(destination.toString());
+            });
+            actions.appendChild(b);
+        }
+        button(cfg.retain, 'retain', true);
+        button(cfg.delete, 'delete', false);
+        button(cfg.cancel, '', false);
+        panel.appendChild(title); panel.appendChild(message); panel.appendChild(warning); panel.appendChild(actions);
+        dialog.appendChild(panel); document.body.appendChild(dialog);
+        dialog.addEventListener('click', function (e) { if (e.target === dialog) dialog.remove(); });
+    }, true);
+})();
+STATPL_DEACTIVATION_JS;
+        wp_add_inline_script('jquery-core', $js, 'after');
+    }
+
     public function enqueue_admin_styles($hook_suffix) {
         if ('toplevel_page_statpl-product-metrics' !== $hook_suffix) {
@@ -333 +2326 @@
         $css = <<<'STATPL_CSS'
         .statpl-table-scroll{overflow-x:auto}
-        .statpl-stock-not-tracked{color:#646970}
+        .statpl-stock-not-tracked{color:#646970}.statpl-product-visibility{display:inline-block;margin-left:7px;color:#646970;font-size:12px;font-weight:400}
         .statpl-metrics-wrap .nav-tab{border-color:#c9d7ff;background:#f2f6ff;color:#3155F5;font-weight:600}
         .statpl-metrics-wrap .nav-tab-active{background:#fff;color:#1d2327;border-bottom-color:#fff;border-top:3px solid #3155F5}
@@ -351 +2344 @@
         .statpl-metrics-wrap .notice-success.inline p{color:#263b8f}
         .statpl-metrics-wrap .statpl-overview-note{color:#505b6b}
+        .statpl-history-notice{position:relative;box-sizing:border-box;margin:15px 0;padding:14px 42px 14px 14px;border:1px solid #c5e2a9;border-radius:6px;background:#DDF2C8;color:#000}.statpl-history-notice-importing{background:#D9EEFF;border-color:#b8dcf5}.statpl-history-notice-icon{color:#2271b1;margin-right:6px;vertical-align:middle}.statpl-history-notice p{margin:8px 0;color:#000}.statpl-history-notice strong{color:#000}.statpl-history-notice-close{position:absolute;top:5px;right:8px;padding:0 5px;border:0;background:transparent;color:#44515e;font-size:22px;line-height:1.2;cursor:pointer}.statpl-history-report-link{display:inline-block;margin-top:3px;color:#0073aa;text-decoration:none}.statpl-history-report-link:hover{text-decoration:underline}
         .statpl-metrics-wrap .statpl-metrics-toolbar{display:flex;justify-content:space-between;align-items:center;gap:16px;flex-wrap:wrap;margin:18px 0 12px}.statpl-metrics-wrap .statpl-sort-form{display:flex;align-items:center;gap:8px}.statpl-metrics-wrap .statpl-metrics-search{display:flex;justify-content:flex-end;align-items:center;gap:8px;margin:0}.statpl-metrics-wrap .statpl-metrics-search input[type=search]{width:min(375px,100%)}.statpl-metrics-wrap .statpl-metrics-search input[type=submit],.statpl-metrics-wrap .button-primary{background:#3155F5!important;border-color:#3155F5!important;color:#fff!important}
         .statpl-metrics-wrap .widefat{border-color:#c9d7ff;border-collapse:separate;border-spacing:0}
@@ -366 +2360 @@
 
     public function admin_menu() {
+        // The detailed import report is intentionally not a permanent menu item.
+        // It is reachable only through the temporary notice link for partial or
+        // technical outcomes, and only during the 15-minute access window.
         add_menu_page('Statora Plus', 'Statora Plus', 'manage_woocommerce', 'statpl-product-metrics', [$this, 'render_page'], 'dashicons-chart-bar', 56);
+    }
+
+    /** Add the silent 20-second dismissal behavior; manual close cancels the timer. */
+    public function enqueue_historical_notice_script() {
+        // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- This is a read-only admin-screen routing check; it does not process form data or perform a state-changing action. Mutating admin actions use their own nonce verification.
+        if (!isset($_GET['page']) || !in_array(sanitize_key(wp_unslash($_GET['page'])), ['statpl-product-metrics','statpl-history-report'], true)) { return; }
+        echo '<script>(function(){var n=document.querySelector(".statpl-history-notice");if(!n)return;var t=window.setTimeout(function(){if(n.parentNode)n.parentNode.removeChild(n);},20000);var b=n.querySelector(".statpl-history-notice-close");if(b)b.addEventListener("click",function(){window.clearTimeout(t);if(n.parentNode)n.parentNode.removeChild(n);});})();</script>';
     }
     /** Bulk-load view counts for a product set to avoid two or more queries per product. */
@@ -376 +2380 @@
         return $this->today_start_datetime()->format('Y-m-d H:i:s');
     }
-    /** Return a displayable stock quantity without double-counting parent and variation stock. */
+    /**
+     * Return stock quantity and WooCommerce availability without double-counting
+     * parent-managed and variation-managed inventory.
+     */
     private function stock_summary_for_product($product) {
-        if (!$product) return ['managed' => false, 'quantity' => null];
+        if (!$product) {
+            return ['managed' => false, 'quantity' => null, 'in_stock' => false];
+        }
+
+        // WooCommerce's native availability API treats both instock and
+        // onbackorder as purchasable, and respects its stock-status filters.
+        $in_stock = (bool) $product->is_in_stock();
+
+        // When the parent manages stock, its quantity is authoritative.
+        // Do not add variation quantities to it.
         if ($product->managing_stock()) {
             $quantity = $product->get_stock_quantity();
-            return ['managed' => true, 'quantity' => is_numeric($quantity) ? (float) $quantity : 0.0];
-        }
+            return [
+                'managed' => true,
+                'quantity' => is_numeric($quantity) ? (float) $quantity : 0.0,
+                'in_stock' => $in_stock,
+            ];
+        }
+
+        // Otherwise, sum only variations that explicitly manage their own stock.
         if ($product->is_type('variable')) {
             $managed_any = false;
@@ -388 +2410 @@
             foreach ($product->get_children() as $variation_id) {
                 $variation = wc_get_product($variation_id);
-                if (!$variation || !$variation->managing_stock()) continue;
+                if (!$variation || !$variation->managing_stock()) {
+                    continue;
+                }
                 $managed_any = true;
                 $quantity = $variation->get_stock_quantity();
-                if (is_numeric($quantity)) $total += (float) $quantity;
-            }
-            if ($managed_any) return ['managed' => true, 'quantity' => $total];
-        }
-        return ['managed' => false, 'quantity' => null];
+                if (is_numeric($quantity)) {
+                    $total += (float) $quantity;
+                }
+            }
+            if ($managed_any) {
+                return ['managed' => true, 'quantity' => $total, 'in_stock' => $in_stock];
+            }
+        }
+
+        return ['managed' => false, 'quantity' => null, 'in_stock' => $in_stock];
     }
 
@@ -411 +2440 @@
         $placeholders = implode(',', array_fill(0, count($ids), '%d'));
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all query values are prepared.
-        $totals = $wpdb->get_results(
-            $wpdb->prepare(
+        $totals = statpl_db_get_results(
+            statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated; the IN placeholders are generated from the count of integer IDs, and every ID is passed to prepare() as a value.
                 "SELECT product_id, total_views FROM {$this->views_table} WHERE product_id IN ($placeholders)",
@@ -428 +2457 @@
         $since = $this->today_start_mysql();
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all query values are prepared.
-        $recent = $wpdb->get_results(
-            $wpdb->prepare(
+        $recent = statpl_db_get_results(
+            statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated; the date and every product ID are passed to prepare() as values. The IN placeholders are generated from the count of integer IDs.
                 "SELECT product_id, COUNT(*) AS views_today FROM {$this->events_table} WHERE viewed_at >= %s AND product_id IN ($placeholders) GROUP BY product_id",
@@ -471 +2500 @@
         // Replace a snapshot atomically so readers never see a half-written order.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Transaction control is required for an atomic snapshot replacement and cannot be cached.
-        if ($wpdb->query('START TRANSACTION') === false) return false;
+        if (statpl_db_query('START TRANSACTION') === false) return false;
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- This write replaces the stored order snapshot inside a transaction; it must execute immediately and must not be cached.
-        $deleted = $wpdb->delete($this->order_items_table, ['order_id' => $order_id], ['%d']);
+        $deleted = statpl_db_delete($this->order_items_table, ['order_id' => $order_id], ['%d']);
         if ($deleted === false) {
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Transaction rollback is required after a failed write; caching is not applicable.
-            $wpdb->query('ROLLBACK');
+            statpl_db_query('ROLLBACK');
             return false;
         }
@@ -539 +2568 @@
         foreach ($by_product as $pid => $row) {
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- These rows are the authoritative refreshed order snapshot; writes must execute immediately and must not be cached.
-            $inserted = $wpdb->insert($this->order_items_table, [
+            $inserted = statpl_db_insert($this->order_items_table, [
                 'order_id'=>(int)$order_id, 'product_id'=>(int)$pid, 'order_status'=>$order->get_status(),
                 'created_at'=>$created_at, 'paid_at'=>$paid_at, 'completed_at'=>$completed_at,
@@ -547 +2576 @@
             if ($inserted === false) {
                 // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Transaction rollback is required after a failed write; caching is not applicable.
-                $wpdb->query('ROLLBACK');
+                statpl_db_query('ROLLBACK');
                 return false;
             }
         }
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Transaction commit is required to persist the completed snapshot atomically.
-        if ($wpdb->query('COMMIT') === false) {
-            $wpdb->query('ROLLBACK');
+        if (statpl_db_query('COMMIT') === false) {
+            statpl_db_query('ROLLBACK');
             return false;
         }
@@ -574 +2603 @@
         global $wpdb;
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Deleting a removed order snapshot is a required write; caching is not applicable.
-        $wpdb->delete($this->order_items_table, ['order_id'=>absint($order_id)], ['%d']);
+        statpl_db_delete($this->order_items_table, ['order_id'=>absint($order_id)], ['%d']);
         delete_transient('statpl_order_stats_v1');
         delete_transient('statpl_global_summary_v2');
     }
+    /**
+     * Discover source-specific adapters registered by compatible analytics plugins.
+     * This registry is intentionally explicit: Statora Plus does not guess the
+     * meaning of arbitrary third-party database tables.
+     */
+    public function discover_historical_view_adapters() {
+        global $wpdb;
+
+        // Discovery mutates the persisted source/origin inventory and schedules
+        // snapshot/import work. Serialize it across concurrent WordPress requests
+        // so two provider scans cannot race while reconciling the same origins.
+        // Acquire the lock before clearing the request-local registry: a request
+        // that cannot enter discovery must not discard a still-valid registry.
+        $lock_name = 'statpl_generic_adapter_discovery';
+        $discovery_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($discovery_lock['acquired'])) {
+            $status = isset($discovery_lock['status']) ? $discovery_lock['status'] : 'lock_unavailable';
+            if ($status !== 'lock_busy_or_unavailable') {
+                $this->log_generic_historical_scheduler_error(
+                    'adapter_discovery_lock',
+                    isset($discovery_lock['error']) ? $discovery_lock['error'] : $status
+                );
+            }
+            return ['status' => $status === 'lock_busy_or_unavailable' ? 'busy' : 'lock_unavailable', 'registered' => 0, 'rejected' => 0];
+        }
+
+        try {
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'lock_session_lost', 'registered' => 0, 'rejected' => 0];
+            }
+            return $this->discover_historical_view_adapters_locked($discovery_lock);
+        } finally {
+            // Never attempt to release a connection-scoped lock through a replacement session.
+            $this->release_generic_advisory_lock($discovery_lock, 'adapter_discovery');
+        }
+    }
+
+    /** Perform provider discovery while holding the global discovery lock. */
+    private function discover_historical_view_adapters_locked($discovery_lock) {
+        // Invalidate request-local adapter objects before asking providers to
+        // rebuild the registry. If a provider throws, retaining objects from an
+        // earlier discovery pass could execute an adapter whose plugin is no
+        // longer available or whose registration is now failing. Persisted
+        // adapter identity/snapshot/checkpoint remain untouched in the database.
+        $this->historical_view_adapters = [];
+
+        // A third-party provider callback can throw while the registry filter is
+        // being assembled. Contain that failure here so it cannot interrupt
+        // Statora Plus initialization or the independent live-view tracker.
+        try {
+            $provided = apply_filters('statpl_historical_view_adapters', []);
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: historical adapter registry filter failed: ' . $exception->getMessage());
+            }
+            return ['status' => 'provider_error', 'registered' => 0, 'rejected' => 1];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+            return ['status' => 'lock_session_lost', 'registered' => 0, 'rejected' => 0];
+        }
+        if (!is_array($provided)) {
+            return ['status' => 'invalid_registry', 'registered' => 0, 'rejected' => 0];
+        }
+
+        // A successful discovery pass is authoritative; the registry was
+        // cleared before invoking third-party provider callbacks above.
+
+        $registered = 0;
+        $rejected = 0;
+        $seen_adapter_keys = [];
+        // A source_key is a persistent namespace, so two different adapter
+        // identities must not claim it during the same discovery pass—even if
+        // the first adapter currently reports no origins and therefore has no
+        // origin row from which the database conflict check could detect it.
+        $seen_source_keys = [];
+
+        foreach ($provided as $adapter) {
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+            }
+            if (!is_object($adapter) || !$this->is_valid_historical_view_adapter($adapter)) {
+                $rejected++;
+                continue;
+            }
+
+            try {
+                $adapter_key = sanitize_key((string) $adapter->get_adapter_key());
+                $source_key = sanitize_key((string) $adapter->get_source_key());
+                $display_name = sanitize_text_field((string) $adapter->get_display_name());
+                $adapter_version = sanitize_text_field((string) $adapter->get_adapter_version());
+
+                // Adapter metadata methods are third-party callbacks. They may
+                // perform database work or trigger a reconnect; never continue
+                // discovery writes under an assumed connection after invoking them.
+                if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                }
+
+                if (
+                    $adapter_key === ''
+                    || $source_key === ''
+                    || $display_name === ''
+                    || $adapter_version === ''
+                    || strlen($adapter_key) > 100
+                    || strlen($source_key) > 100
+                    || strlen($display_name) > 191
+                    || strlen($adapter_version) > 32
+                    || isset($seen_adapter_keys[$adapter_key])
+                ) {
+                    $rejected++;
+                    continue;
+                }
+
+                // SlimStat already has a mature, separately tested import pipeline.
+                // It must not be registered a second time through this generic path.
+                if ($source_key === 'slimstat' || $adapter_key === 'slimstat') {
+                    continue;
+                }
+
+                if (isset($seen_source_keys[$source_key]) && $seen_source_keys[$source_key] !== $adapter_key) {
+                    $rejected++;
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('Statora Plus: rejected adapter "' . $adapter_key . '" because source_key "' . $source_key . '" was already claimed by another adapter in this discovery pass.');
+                    }
+                    continue;
+                }
+                $seen_source_keys[$source_key] = $adapter_key;
+
+                // A source_key is the persistent namespace for all of its origins.
+                // Do not allow a different adapter identity to append a second set
+                // of origins to an existing source, even when the origin_key values
+                // do not overlap. The discovery advisory lock makes this check and
+                // the subsequent registration one serialized discovery operation.
+                global $wpdb;
+                $conflicting_adapter_key = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT origins.adapter_key
+                     FROM {$this->view_source_origins_table} AS origins
+                     INNER JOIN {$this->view_sources_table} AS sources
+                       ON sources.id = origins.source_id
+                     WHERE sources.source_key = %s
+                       AND (sources.adapter_key <> %s OR origins.adapter_key <> %s)
+                     LIMIT 1",
+                    $source_key,
+                    $adapter_key,
+                    $adapter_key
+                ));
+                if (!empty($wpdb->last_error)) {
+                    $rejected++;
+                    $this->log_generic_historical_scheduler_error(
+                        'adapter_identity_lookup',
+                        $wpdb->last_error
+                    );
+                    continue;
+                }
+                if ($conflicting_adapter_key !== null && $conflicting_adapter_key !== '') {
+                    $rejected++;
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('Statora Plus: rejected adapter "' . $adapter_key . '" because source_key "' . $source_key . '" is already bound to another adapter identity.');
+                    }
+                    continue;
+                }
+
+                $origins = $adapter->discover_origins();
+                if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                }
+                if (!is_array($origins)) {
+                    $rejected++;
+                    continue;
+                }
+
+                $valid_origins = [];
+                $seen_origin_keys = [];
+                $origin_declaration_invalid = false;
+                foreach ($origins as $origin) {
+                    if (!is_array($origin)) {
+                        $rejected++;
+                        $origin_declaration_invalid = true;
+                        continue;
+                    }
+
+                    $origin_key = isset($origin['origin_key'])
+                        ? sanitize_key((string) $origin['origin_key'])
+                        : '';
+                    $capabilities = isset($origin['capabilities']) && is_array($origin['capabilities'])
+                        ? $origin['capabilities']
+                        : [];
+                    $detection_status = isset($origin['detection_status'])
+                        ? (string) $origin['detection_status']
+                        : 'unknown';
+
+                    // Only explicit product-view capability qualifies as a source.
+                    if (
+                        $origin_key === ''
+                        || strlen($origin_key) > 100
+                        || isset($seen_origin_keys[$origin_key])
+                        || empty($capabilities['product_views'])
+                        || !in_array($detection_status, ['unknown', 'available', 'missing_table', 'incompatible_schema', 'database_error'], true)
+                    ) {
+                        $rejected++;
+                        $origin_declaration_invalid = true;
+                        continue;
+                    }
+
+                    // Sanitization can collapse distinct provider values to the
+                    // same key. Register each origin only once per discovery pass
+                    // so duplicate declarations cannot overwrite capabilities or
+                    // schedule duplicate snapshot/import initialization work.
+                    $seen_origin_keys[$origin_key] = true;
+                    $valid_origins[] = [
+                        'origin_key' => $origin_key,
+                        'capabilities' => $capabilities,
+                        'detection_status' => $detection_status,
+                    ];
+                }
+
+                if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                }
+                $source_result = $this->register_view_source(
+                    $source_key,
+                    $display_name,
+                    $adapter_version,
+                    'event',
+                    'detected',
+                    $adapter_key
+                );
+
+                if (empty($source_result['source_id'])) {
+                    $rejected++;
+                    continue;
+                }
+
+                // A successful discovery response is authoritative for the
+                // adapter's current origin inventory. If the provider returns a
+                // temporarily incomplete (or empty) list, preserve omitted
+                // origins and their cursors but take them out of active work.
+                // Do not infer omissions from a malformed/partially rejected
+                // declaration list, because that is not a trustworthy inventory.
+                $seen_adapter_keys[$adapter_key] = true;
+                if (!$origin_declaration_invalid) {
+                    $missing_origins = $this->mark_missing_generic_historical_origins_unavailable(
+                        $source_result['source_id'],
+                        $adapter_key,
+                        array_column($valid_origins, 'origin_key'),
+                        $discovery_lock
+                    );
+                    if (empty($missing_origins['status']) || $missing_origins['status'] !== 'updated') {
+                        // Do not register or schedule this adapter's newly reported
+                        // origins against a partially reconciled inventory. Keep the
+                        // previous persisted inventory intact and retry on the next
+                        // discovery pass after the database is healthy.
+                        $rejected++;
+                        $this->log_generic_historical_scheduler_error(
+                            'origin_inventory_reconciliation',
+                            isset($missing_origins['error']) ? $missing_origins['error'] : 'Origin inventory reconciliation did not commit.'
+                        );
+                        continue;
+                    }
+                }
+
+                if (!$valid_origins) {
+                    if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                    }
+                    $this->refresh_generic_historical_source_status($source_result['source_id']);
+                    continue;
+                }
+
+                $registered_origins = [];
+                $origin_registration_failures = 0;
+                $adapter_mismatch_detected = false;
+                foreach ($valid_origins as $origin) {
+                    if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                    }
+                    // Isolate each origin completely. A provider/database exception
+                    // while registering one origin must not prevent sibling origins
+                    // from being registered and scheduled in this discovery pass.
+                    try {
+                        $origin_result = $this->register_view_source_origin(
+                            $source_result['source_id'],
+                            $origin['origin_key'],
+                            $adapter_key,
+                            $origin['capabilities'],
+                            $origin['detection_status']
+                        );
+                    } catch (Throwable $exception) {
+                        $origin_result = [
+                            'status' => 'origin_exception',
+                            'error' => $exception->getMessage(),
+                        ];
+                        if (defined('WP_DEBUG') && WP_DEBUG) {
+                            $this->debug_log('Statora Plus: origin registration failed for "' . $origin['origin_key'] . '": ' . $exception->getMessage());
+                        }
+                    }
+
+                    if (!empty($origin_result['status']) && $origin_result['status'] === 'registered') {
+                        $registered_origins[] = $origin;
+                    } elseif (!empty($origin_result['status']) && $origin_result['status'] === 'adapter_mismatch') {
+                        $adapter_mismatch_detected = true;
+                        $origin_registration_failures++;
+                    } else {
+                        $origin_registration_failures++;
+                    }
+                }
+                if ($adapter_mismatch_detected) {
+                    // Preserve the established identity and cursor of the mismatched
+                    // origin, but do not let that isolated conflict block sibling
+                    // origins that were registered successfully with this adapter.
+                    $this->refresh_generic_historical_source_status($source_result['source_id']);
+                }
+
+                if ($registered_origins) {
+                    $this->historical_view_adapters[$adapter_key] = $adapter;
+                    $snapshot_result = $this->initialize_generic_historical_view_snapshots(
+                        $source_result['source_id'],
+                        $adapter_key,
+                        $registered_origins,
+                        $discovery_lock
+                    );
+                    if (($snapshot_result['status'] ?? '') === 'lock_session_lost'
+                        || !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                    }
+                    $this->refresh_generic_historical_source_status($source_result['source_id']);
+                    $registered++;
+                    if (!empty($snapshot_result['failed']) || $origin_registration_failures > 0) {
+                        $rejected++;
+                    }
+                    foreach ($registered_origins as $origin) {
+                        if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                            return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                        }
+                        if ($origin['detection_status'] === 'available') {
+                            $this->schedule_generic_historical_view_import_batch(15, $source_result['source_id'], $origin['origin_key']);
+                        }
+                    }
+                } else {
+                    $rejected++;
+                }
+            } catch (Throwable $exception) {
+                $rejected++;
+                if (defined('WP_DEBUG') && WP_DEBUG) {
+                    $this->debug_log('Statora Plus: historical adapter discovery failed: ' . $exception->getMessage());
+                }
+            }
+        }
+
+        return [
+            'status' => 'completed',
+            'registered' => $registered,
+            'rejected' => $rejected,
+        ];
+    }
+
+    /** Persist snapshot and its initial checkpoint together, exactly once per origin. */
+    private function save_generic_historical_snapshot_if_empty($source_id, $origin_key, $snapshot, $checkpoint) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = is_string($origin_key) ? trim($origin_key) : '';
+        if (!$source_id || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+            || !is_array($snapshot) || empty($snapshot) || !is_array($checkpoint)) {
+            return ['status' => 'invalid_input'];
+        }
+
+        $snapshot_json = wp_json_encode($snapshot);
+        $checkpoint_json = wp_json_encode($checkpoint);
+        if (!is_string($snapshot_json) || !is_string($checkpoint_json)) {
+            return ['status' => 'encoding_error'];
+        }
+
+        $result = statpl_db_query(statpl_db_prepare(
+            "UPDATE {$this->view_source_origins_table}
+             SET snapshot_data = %s, checkpoint_data = %s, status = %s,
+                 started_at = %s, last_error = NULL, updated_at = %s
+             WHERE source_id = %d AND origin_key = %s
+               AND snapshot_data IS NULL AND checkpoint_data IS NULL",
+            $snapshot_json,
+            $checkpoint_json,
+            'snapshot_ready',
+            current_time('mysql'),
+            current_time('mysql'),
+            $source_id,
+            $origin_key
+        ));
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return ['status' => 'database_error', 'error' => $wpdb->last_error];
+        }
+        if ($result === 1) {
+            return ['status' => 'updated', 'source_id' => $source_id, 'origin_key' => $origin_key];
+        }
+
+        $existing = $this->get_view_source_origin_state($source_id, $origin_key);
+        if ($existing['status'] !== 'found') {
+            return $existing;
+        }
+        if (is_array($existing['snapshot']) && !empty($existing['snapshot'])
+            && is_array($existing['checkpoint'])) {
+            return [
+                'status' => 'already_initialized',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'snapshot' => $existing['snapshot'],
+                'checkpoint' => $existing['checkpoint'],
+            ];
+        }
+        return ['status' => 'initialization_conflict', 'source_id' => $source_id, 'origin_key' => $origin_key];
+    }
+
+    /**
+     * Capture an immutable upper-bound snapshot for every detected generic origin.
+     * Existing snapshots are never overwritten, so retries/re-discovery cannot move
+     * the historical import boundary forward and accidentally include live traffic.
+     */
+    private function initialize_generic_historical_view_snapshots($source_id, $adapter_key, $origins, $discovery_lock = null) {
+        $adapter = $this->get_historical_view_adapter($adapter_key);
+        if (!$adapter) {
+            return ['status' => 'adapter_unavailable', 'failed' => 1];
+        }
+
+        $initialized = 0;
+        $skipped = 0;
+        $failed = 0;
+
+        foreach ($origins as $origin) {
+            if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return [
+                    'status' => 'lock_session_lost',
+                    'initialized' => $initialized,
+                    'skipped' => $skipped,
+                    'failed' => $failed,
+                ];
+            }
+            if (!is_array($origin) || empty($origin['origin_key'])) {
+                $failed++;
+                continue;
+            }
+            if (($origin['detection_status'] ?? '') !== 'available') {
+                $skipped++;
+                continue;
+            }
+
+            $state = $this->get_view_source_origin_state($source_id, $origin['origin_key']);
+            if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return [
+                    'status' => 'lock_session_lost',
+                    'initialized' => $initialized,
+                    'skipped' => $skipped,
+                    'failed' => $failed,
+                ];
+            }
+            if (empty($state['status']) || $state['status'] !== 'found') {
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Could not read the stored origin state while initializing its historical snapshot.',
+                    null,
+                    8,
+                    $discovery_lock);
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                }
+                continue;
+            }
+            if (is_array($state['snapshot']) && !empty($state['snapshot'])) {
+                // A persisted snapshot is already valid; clear any stale
+                // initialization failure only while this discovery worker still
+                // owns the lock that serializes snapshot-ledger changes.
+                if (!$this->clear_generic_historical_view_failure($source_id, $origin['origin_key'], 'snapshot_initialization', $discovery_lock)) {
+                    $failed++;
+                    $this->schedule_generic_historical_snapshot_retry(60, $source_id, $origin['origin_key']);
+                    continue;
+                }
+                $skipped++;
+                continue;
+            }
+
+            try {
+                $snapshot = $adapter->get_origin_snapshot($origin['origin_key']);
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                if (!is_array($snapshot) || empty($snapshot)) {
+                    $failed++;
+                    if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return [
+                            'status' => 'lock_session_lost',
+                            'initialized' => $initialized,
+                            'skipped' => $skipped,
+                            'failed' => $failed,
+                        ];
+                    }
+                    $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Adapter returned an empty or invalid historical snapshot.',
+                    null,
+                    8,
+                    $discovery_lock);
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                    }
+                    continue;
+                }
+
+                // Adapter snapshots must declare their own stable boundary. The core
+                // records the capture time but does not guess source-specific cursors.
+                if (!isset($snapshot['captured_at'])) {
+                    $snapshot['captured_at'] = current_time('mysql');
+                }
+                if (!isset($snapshot['boundary']) || !is_array($snapshot['boundary']) || empty($snapshot['boundary'])) {
+                    $failed++;
+                    if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return [
+                            'status' => 'lock_session_lost',
+                            'initialized' => $initialized,
+                            'skipped' => $skipped,
+                            'failed' => $failed,
+                        ];
+                    }
+                    $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Adapter snapshot did not provide the required immutable boundary descriptor.',
+                    null,
+                    8,
+                    $discovery_lock);
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                    }
+                    continue;
+                }
+
+                $initial_checkpoint = array_key_exists('initial_checkpoint', $snapshot)
+                    ? $snapshot['initial_checkpoint']
+                    : null;
+                // A null initial cursor is valid (many sources begin at the start
+                // of their history). Non-null cursors must be JSON-safe scalar/array
+                // values within the same storage limit used for subsequent cursors.
+                if ($initial_checkpoint !== null && !$this->is_valid_generic_historical_cursor($initial_checkpoint)) {
+                    $failed++;
+                    if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return [
+                            'status' => 'lock_session_lost',
+                            'initialized' => $initialized,
+                            'skipped' => $skipped,
+                            'failed' => $failed,
+                        ];
+                    }
+                    $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Adapter snapshot contained an invalid initial checkpoint. Expected null or a JSON-safe scalar/array cursor no larger than 60 KB.',
+                    null,
+                    8,
+                    $discovery_lock);
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                    }
+                    continue;
+                }
+
+                $checkpoint = [
+                    'cursor' => $initial_checkpoint,
+                    'processed' => 0,
+                    'snapshot_captured_at' => $snapshot['captured_at'],
+                ];
+                unset($snapshot['initial_checkpoint']);
+
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                $saved = $this->save_generic_historical_snapshot_if_empty(
+                    $source_id,
+                    $origin['origin_key'],
+                    $snapshot,
+                    $checkpoint
+                );
+                if (empty($saved['status']) || !in_array($saved['status'], ['updated', 'already_initialized'], true)) {
+                    $failed++;
+                    if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return [
+                            'status' => 'lock_session_lost',
+                            'initialized' => $initialized,
+                            'skipped' => $skipped,
+                            'failed' => $failed,
+                        ];
+                    }
+                    $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Could not persist the immutable snapshot and initial checkpoint: ' . (isset($saved['status']) ? $saved['status'] : 'unknown error'),
+                    null,
+                    8,
+                    $discovery_lock);
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                    }
+                    continue;
+                }
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                $failure_cleared = $this->clear_generic_historical_view_failure($source_id, $origin['origin_key'], 'snapshot_initialization', $discovery_lock);
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                if (!$failure_cleared) {
+                    $failed++;
+                    $this->schedule_generic_historical_snapshot_retry(60, $source_id, $origin['origin_key']);
+                    continue;
+                }
+                if ($saved['status'] === 'updated') {
+                    $initialized++;
+                } else {
+                    $skipped++;
+                }
+            } catch (Throwable $exception) {
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    $exception->getMessage(),
+                    null,
+                    8,
+                    $discovery_lock);
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                }
+                if (defined('WP_DEBUG') && WP_DEBUG) {
+                    $this->debug_log('Statora Plus: historical origin snapshot failed: ' . $exception->getMessage());
+                }
+            }
+        }
+
+        return [
+            'status' => $failed ? 'partial' : 'completed',
+            'initialized' => $initialized,
+            'skipped' => $skipped,
+            'failed' => $failed,
+        ];
+    }
+
+    /**
+     * Preserve origins omitted by a successful adapter discovery pass without
+     * allowing stale origins to continue importing. Their immutable adapter
+     * identity, snapshot, checkpoint, events and failure ledger are untouched.
+     */
+    private function mark_missing_generic_historical_origins_unavailable($source_id, $adapter_key, $discovered_origin_keys, $discovery_lock = null) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $adapter_key = sanitize_key((string) $adapter_key);
+        if (!$source_id || $adapter_key === '' || !is_array($discovered_origin_keys)) {
+            return ['status' => 'invalid_input', 'updated' => 0];
+        }
+
+        $discovered = [];
+        foreach ($discovered_origin_keys as $origin_key) {
+            $origin_key = sanitize_key((string) $origin_key);
+            if ($origin_key !== '') {
+                $discovered[$origin_key] = true;
+            }
+        }
+
+        if (!is_array($discovery_lock) || !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+            return ['status' => 'lock_session_lost', 'updated' => 0, 'error' => 'Discovery lock session is no longer current.'];
+        }
+
+        $transaction_started = false;
+        $transaction_committed = false;
+        try {
+            // Reconciliation is one logical inventory operation. Keep it atomic so
+            // a database error halfway through cannot leave only part of the omitted
+            // origins marked unavailable. A later discovery can safely retry it.
+            $begin_result = statpl_db_query('START TRANSACTION');
+            if ($begin_result === false || $wpdb->last_error !== '') {
+                return ['status' => 'database_error', 'updated' => 0, 'error' => $wpdb->last_error];
+            }
+            $transaction_started = true;
+
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'lock_session_lost', 'updated' => 0, 'error' => 'Discovery lock session changed before origin inventory read.'];
+            }
+            $existing = statpl_db_get_results(
+                statpl_db_prepare(
+                    "SELECT origin_key, status
+                     FROM {$this->view_source_origins_table}
+                     WHERE source_id = %d AND adapter_key = %s
+                     FOR UPDATE",
+                    $source_id,
+                    $adapter_key
+                ),
+                ARRAY_A
+            );
+            if (!empty($wpdb->last_error) || !is_array($existing)) {
+                return ['status' => 'database_error', 'updated' => 0, 'error' => $wpdb->last_error !== '' ? $wpdb->last_error : 'Origin inventory query returned an invalid result.'];
+            }
+
+            $updated = 0;
+            foreach ($existing as $row) {
+                if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return ['status' => 'lock_session_lost', 'updated' => 0, 'error' => 'Discovery lock session changed during origin inventory reconciliation.'];
+                }
+                $origin_key = isset($row['origin_key']) ? (string) $row['origin_key'] : '';
+                if ($origin_key === '' || isset($discovered[$origin_key])) {
+                    continue;
+                }
+
+                // Terminal lifecycle states are retained. Detection becomes unknown
+                // until the provider declares this origin again; active work becomes
+                // unavailable so stale adapter inventories cannot process it.
+                $updates = [
+                    'detection_status' => 'unknown',
+                    'updated_at' => current_time('mysql'),
+                ];
+                $formats = ['%s', '%s'];
+                if (in_array($row['status'] ?? '', ['pending', 'snapshot_ready', 'importing', 'retry_wait'], true)) {
+                    $updates['status'] = 'unavailable';
+                    $updates['last_error'] = 'This origin was not declared by the adapter during the latest successful discovery pass; its saved snapshot and checkpoint were preserved.';
+                    $formats = ['%s', '%s', '%s', '%s'];
+                }
+
+                $result = statpl_db_update(
+                    $this->view_source_origins_table,
+                    $updates,
+                    ['source_id' => $source_id, 'origin_key' => $origin_key],
+                    $formats,
+                    ['%d', '%s']
+                );
+                if ($result === false || $wpdb->last_error !== '') {
+                    return ['status' => 'database_error', 'updated' => 0, 'error' => $wpdb->last_error !== '' ? $wpdb->last_error : 'Origin reconciliation update failed.'];
+                }
+                $updated++;
+            }
+
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'lock_session_lost', 'updated' => 0, 'error' => 'Discovery lock session changed before origin inventory commit.'];
+            }
+            $commit_result = statpl_db_query('COMMIT');
+            if ($commit_result === false || $wpdb->last_error !== '') {
+                return ['status' => 'database_error', 'updated' => 0, 'error' => $wpdb->last_error !== '' ? $wpdb->last_error : 'Origin reconciliation commit failed.'];
+            }
+            $transaction_committed = true;
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'commit_outcome_unknown', 'updated' => 0, 'error' => 'Origin inventory commit completed but discovery lock session could not be confirmed.'];
+            }
+            return ['status' => 'updated', 'updated' => $updated];
+        } catch (Throwable $exception) {
+            return ['status' => 'database_error', 'updated' => 0, 'error' => $exception->getMessage()];
+        } finally {
+            // Includes thrown exceptions and ambiguous failures before COMMIT.
+            // A rollback after a successful commit is intentionally avoided.
+            if ($transaction_started && !$transaction_committed && $this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                try {
+                    statpl_db_query('ROLLBACK');
+                } catch (Throwable $rollback_exception) {
+                    $this->log_generic_historical_scheduler_error('origin_inventory_rollback', $rollback_exception->getMessage());
+                }
+            }
+        }
+    }
+
+    /** Validate the minimum public adapter contract without trusting a provider. */
+    private function is_valid_historical_view_adapter($adapter) {
+        foreach ([
+            'get_adapter_key',
+            'get_source_key',
+            'get_display_name',
+            'get_adapter_version',
+            'discover_origins',
+            'get_origin_snapshot',
+            'get_product_view_batch',
+            'normalize_record',
+        ] as $method) {
+            if (!is_callable([$adapter, $method])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Recompute the persisted status of one generic source from all its origins.
+     * This is intentionally called only by the generic pipeline; the independent
+     * SlimStat lifecycle and its status model are left untouched.
+     */
+    private function refresh_generic_historical_source_status($source_id) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        if (!$source_id) {
+            return ['status' => 'invalid_source'];
+        }
+
+        // Serialize aggregate status calculation and persistence per source.
+        // Use the shared lock contract so the owning connection is captured
+        // atomically and RELEASE_LOCK is never attempted on a replacement session.
+        $status_lock_name = 'statpl_status_' . substr(md5((string) $source_id), 0, 32);
+        $status_lock = $this->acquire_generic_advisory_lock($status_lock_name);
+        if (empty($status_lock['acquired'])) {
+            if (($status_lock['status'] ?? '') === 'lock_busy_or_unavailable' && empty($status_lock['error'])) {
+                return ['status' => 'status_lock_busy'];
+            }
+            return ['status' => 'database_error', 'error' => (string) ($status_lock['error'] ?? 'Unable to acquire source status lock.')];
+        }
+
+        try {
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        $origins = statpl_db_get_results(statpl_db_prepare(
+            "SELECT detection_status, status FROM {$this->view_source_origins_table} WHERE source_id = %d",
+            $source_id
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error)) {
+            return ['status' => 'database_error', 'error' => $wpdb->last_error];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        if (!is_array($origins) || !$origins) {
+            return ['status' => 'no_origins'];
+        }
+
+        $available_origins = array_values(array_filter($origins, function ($origin) {
+            // Detection describes what the provider reported on its last pass;
+            // lifecycle status additionally records whether this exact persisted
+            // adapter identity is currently safe to execute. A replacement
+            // adapter can be detected as available while its origin remains
+            // deliberately unavailable because it cannot inherit the old cursor.
+            return isset($origin['detection_status'], $origin['status'])
+                && $origin['detection_status'] === 'available'
+                && $origin['status'] !== 'unavailable';
+        }));
+        $available = count($available_origins);
+        $available_completed = count(array_filter($available_origins, function ($origin) {
+            return isset($origin['status']) && $origin['status'] === 'completed';
+        }));
+        // Only available origins participate in import lifecycle aggregation.
+        // An unavailable/detected sibling must never keep an otherwise finished
+        // source stuck in importing or retry_wait.
+        $available_statuses = array_column($available_origins, 'status');
+
+        // A source remains actively importing while ANY available origin is
+        // still progressing. A blocked sibling origin must not make the whole
+        // source appear terminal before the remaining origins finish.
+        if (in_array('importing', $available_statuses, true) || in_array('snapshot_ready', $available_statuses, true) || in_array('pending', $available_statuses, true)) {
+            $source_status = 'importing';
+        } elseif (in_array('retry_wait', $available_statuses, true)) {
+            $source_status = 'retry_wait';
+        } elseif (in_array('needs_attention', $available_statuses, true)) {
+            $source_status = 'needs_attention';
+        } elseif ($available === 0) {
+            $source_status = 'unavailable';
+        } elseif ($available_completed === $available) {
+            // A source with unavailable origins is only partial, never fully complete.
+            $source_status = ($available === count($origins)) ? 'completed' : 'partial';
+        } elseif (in_array('completed', $available_statuses, true)) {
+            $source_status = 'partial';
+        } else {
+            $source_status = 'detected';
+        }
+
+        // Status reconciliation is not a source-registration/content update.
+        // Keep updated_at reserved for genuine source changes; otherwise the
+        // recovery scanner would generate needless writes on every request.
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        // Bind source-status persistence to the same MySQL session that owns
+        // this status lock. A PHP-side check alone leaves a reconnect race between
+        // validation and UPDATE; the SQL predicate closes that window.
+        if (empty($status_lock['lock_name']) || !$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        $updated = statpl_db_query(statpl_db_prepare(
+            "UPDATE {$this->view_sources_table}
+             SET status = %s
+             WHERE id = %d AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+            $source_status,
+            $source_id,
+            (string) $status_lock['lock_name']
+        ));
+        if ($updated === false || $wpdb->last_error !== '') {
+            return ['status' => 'database_error', 'error' => $wpdb->last_error];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+
+        // Do not treat an accepted UPDATE as durable source-state convergence.
+        // The row may have been unchanged (0 affected rows), or an ambiguous
+        // acknowledgement may have occurred. Read the aggregate status back and
+        // require an exact match before reporting success to callers.
+        $persisted_status = statpl_db_get_var(statpl_db_prepare(
+            "SELECT status FROM {$this->view_sources_table} WHERE id = %d",
+            $source_id
+        ));
+        if ($wpdb->last_error !== '') {
+            return ['status' => 'database_error', 'error' => $wpdb->last_error];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        if ($persisted_status === null) {
+            // The source may have been removed after the bounded scan selected it.
+            // Treat that as a vanished work item, not as a database failure.
+            return ['status' => 'source_missing'];
+        }
+        if (!is_string($persisted_status) || $persisted_status !== $source_status) {
+            return [
+                'status' => 'state_unverified',
+                'expected_status' => $source_status,
+                'persisted_status' => is_string($persisted_status) ? $persisted_status : null,
+            ];
+        }
+
+        return ['status' => 'updated', 'source_status' => $source_status];
+        } finally {
+            // Release only if the original connection still owns this lock.
+            $this->release_generic_advisory_lock($status_lock, 'source_status_reconciliation');
+        }
+    }
+
+    /** Retry adapter discovery and snapshot initialization after a bounded delay. */
+    public function retry_generic_historical_view_snapshot($source_id = 0, $origin_key = '') {
+        $source_id = absint($source_id);
+        $origin_key = sanitize_key((string) $origin_key);
+        if (!$source_id || $origin_key === '') {
+            return ['status' => 'invalid_input'];
+        }
+
+        // Discovery re-resolves the provider in this request and retries only origins
+        // whose immutable snapshot has not yet been persisted. Existing snapshots are
+        // protected by save_generic_historical_snapshot_if_empty().
+        $result = $this->discover_historical_view_adapters();
+        $state = $this->get_view_source_origin_state($source_id, $origin_key);
+        if (!empty($state['status']) && $state['status'] === 'found'
+            && is_array($state['snapshot']) && !empty($state['snapshot'])) {
+            // The discovery worker owns the snapshot failure ledger lifecycle. This
+            // follow-up request has no discovery lock context, so it must not delete
+            // the ledger row outside that ownership boundary.
+            $this->schedule_generic_historical_view_import_batch(15, $source_id, $origin_key);
+            $this->refresh_generic_historical_source_status($source_id);
+            return ['status' => 'snapshot_ready', 'discovery' => $result];
+        }
+
+        $this->refresh_generic_historical_source_status($source_id);
+        return ['status' => 'snapshot_still_unavailable', 'discovery' => $result];
+    }
+
+    /** Schedule bounded retries for transient snapshot/provider initialization failures. */
+    private function schedule_generic_historical_snapshot_retry($delay, $source_id, $origin_key) {
+        $args = [absint($source_id), sanitize_key((string) $origin_key)];
+        $hook = 'statpl_generic_view_snapshot_retry';
+        $requested_timestamp = time() + max(1, (int) $delay);
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $existing_timestamp = false;
+            if (function_exists('as_next_scheduled_action')) {
+                try {
+                    $existing_timestamp = as_next_scheduled_action($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_lookup', $exception->getMessage());
+                }
+            }
+
+            // A newly discovered transient failure may have a shorter backoff than
+            // an older snapshot retry. Keep the earliest deadline, not merely any
+            // existing action, so stale long delays cannot postpone recovery.
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp && function_exists('as_unschedule_all_actions')) {
+                try {
+                    as_unschedule_all_actions($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_unschedule', $exception->getMessage());
+                    return true;
+                }
+            } elseif ($existing_timestamp) {
+                return true;
+            } elseif (function_exists('as_has_scheduled_action')) {
+                try {
+                    if (as_has_scheduled_action($hook, $args, 'statpl-plus')) {
+                        // Without a reliable timestamp/removal API, retain the
+                        // existing action rather than creating an uncontrolled duplicate.
+                        return true;
+                    }
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_presence_check', $exception->getMessage());
+                }
+            }
+
+            try {
+                $action_id = as_schedule_single_action($requested_timestamp, $hook, $args, 'statpl-plus');
+                if ($action_id) {
+                    return true;
+                }
+            } catch (Throwable $exception) {
+                $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            }
+            // Action Scheduler can be unavailable or fail transiently. Fall back to WP-Cron.
+        }
+
+        // WP-Cron follows the same earliest-deadline rule. If replacing a later
+        // event fails, retain it rather than creating a duplicate with uncertain order.
+        try {
+            $existing_timestamp = wp_next_scheduled($hook, $args);
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp) {
+                $unscheduled = wp_unschedule_event((int) $existing_timestamp, $hook, $args);
+                if (!$unscheduled || is_wp_error($unscheduled)) {
+                    $this->log_generic_historical_scheduler_error(
+                        $hook . '_unschedule',
+                        is_wp_error($unscheduled) ? $unscheduled->get_error_message() : 'Could not replace the later WP-Cron event.'
+                    );
+                    return true;
+                }
+            }
+            $scheduled = wp_schedule_single_event($requested_timestamp, $hook, $args);
+            if (!$scheduled || is_wp_error($scheduled)) {
+                $this->log_generic_historical_scheduler_error($hook, is_wp_error($scheduled) ? $scheduled->get_error_message() : 'WP-Cron rejected the event.');
+                return false;
+            }
+            return true;
+        } catch (Throwable $exception) {
+            $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            return false;
+        }
+    }
+
+    /** Requeue persisted generic-import work after a previous scheduler outage. */
+    private function recover_unscheduled_generic_historical_work() {
+        global $wpdb;
+
+        $origins = statpl_db_get_results(
+            "SELECT source_id, origin_key, snapshot_data, status, detection_status
+             FROM {$this->view_source_origins_table}
+             WHERE detection_status = 'available'
+               AND status IN ('pending', 'snapshot_ready', 'importing', 'retry_wait')
+             ORDER BY updated_at ASC
+             LIMIT 50",
+            ARRAY_A
+        );
+        if (!is_array($origins) || !empty($wpdb->last_error)) {
+            $this->log_generic_historical_scheduler_error('recovery_scan', !empty($wpdb->last_error) ? $wpdb->last_error : 'Unable to read pending origins.');
+            return 0;
+        }
+
+        $requeued = 0;
+        foreach ($origins as $origin) {
+            $source_id = absint($origin['source_id'] ?? 0);
+            $origin_key = sanitize_key((string) ($origin['origin_key'] ?? ''));
+            if (!$source_id || $origin_key === '') {
+                continue;
+            }
+
+            if (empty($origin['snapshot_data'])) {
+                $scheduled = $this->schedule_generic_historical_snapshot_retry(300, $source_id, $origin_key);
+            } else {
+                $scheduled = $this->schedule_generic_historical_view_import_batch(300, $source_id, $origin_key);
+            }
+            if ($scheduled) {
+                $requeued++;
+            }
+        }
+
+        // Retry rows are durable in the failure ledger. Recreate their worker
+        // trigger independently of the main import cursor.
+        $retry_origins = statpl_db_get_results(
+            "SELECT source_id, origin_key, MIN(next_retry_at) AS next_retry_at
+             FROM {$this->view_source_failures_table}
+             WHERE status = 'retry'
+               AND retry_checkpoint IS NOT NULL
+               AND retry_checkpoint <> ''
+             GROUP BY source_id, origin_key
+             ORDER BY MIN(next_retry_at) ASC
+             LIMIT 50",
+            ARRAY_A
+        );
+        if (is_array($retry_origins) && empty($wpdb->last_error)) {
+            foreach ($retry_origins as $retry_origin) {
+                $source_id = absint($retry_origin['source_id'] ?? 0);
+                $origin_key = sanitize_key((string) ($retry_origin['origin_key'] ?? ''));
+                if (!$source_id || $origin_key === '') {
+                    continue;
+                }
+                $next_timestamp = !empty($retry_origin['next_retry_at']) ? strtotime((string) $retry_origin['next_retry_at']) : false;
+                $delay = $next_timestamp !== false ? max(1, $next_timestamp - current_time('timestamp')) : 300;
+                if ($this->schedule_generic_historical_failure_retry(min(86400, $delay), $source_id, $origin_key)) {
+                    $requeued++;
+                }
+            }
+        } elseif (!empty($wpdb->last_error)) {
+            $this->log_generic_historical_scheduler_error('retry_recovery_scan', $wpdb->last_error);
+        }
+
+        // Serialize the cursor read, bounded page, and cursor write. Per-source
+        // locks protect each aggregate update; this scan-level lock additionally
+        // prevents concurrent requests from moving the persistent cursor backwards.
+        // Use the shared lock helper so acquisition, ownership checks and release
+        // follow the same connection-identity contract as the other workers.
+        $scan_lock_name = 'statpl_srcscan_' . substr(md5((string) $wpdb->prefix), 0, 32);
+        $scan_lock = $this->acquire_generic_advisory_lock($scan_lock_name);
+        if (empty($scan_lock['acquired'])) {
+            $scan_status = sanitize_key((string) ($scan_lock['status'] ?? 'lock_unavailable'));
+            if ($scan_status !== 'lock_busy_or_unavailable') {
+                $this->log_generic_historical_scheduler_error(
+                    'source_status_scan_lock',
+                    (string) ($scan_lock['error'] ?? $scan_status)
+                );
+            }
+        } else {
+            try {
+                if (!$this->generic_advisory_lock_session_is_current($scan_lock)) {
+                    $this->log_generic_historical_scheduler_error(
+                        'source_status_scan_lock',
+                        'The MySQL connection changed immediately after acquiring the source-status scan lock; this scan was skipped.'
+                    );
+                } else {
+                    // Source-status reconciliation is durable work even when every
+                    // origin is already completed. A persistent keyset cursor ensures
+                    // that a busy or failing source cannot pin the first page and
+                    // starve later sources when more than 50 sources exist.
+                    $cursor_option = 'statpl_generic_status_recovery_cursor';
+                    // The cursor is written directly with SQL while proving lock
+                    // ownership. Read it directly too: get_option() may return a
+                    // stale object-cache value because direct SQL bypasses the
+                    // WordPress options cache.
+                    $cursor_value = statpl_db_get_var(statpl_db_prepare(
+                        "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                        $cursor_option
+                    ));
+                    if ($wpdb->last_error !== '') {
+                        $this->log_generic_historical_scheduler_error('source_status_recovery_cursor', $wpdb->last_error);
+                        $cursor_value = '0';
+                    }
+                    $source_cursor = absint($cursor_value);
+                    $sources = statpl_db_get_results(statpl_db_prepare(
+                        "SELECT sources.id FROM {$this->view_sources_table} AS sources
+                         WHERE sources.id > %d
+                           AND EXISTS (
+                               SELECT 1 FROM {$this->view_source_origins_table} AS origins
+                               WHERE origins.source_id = sources.id
+                           )
+                         ORDER BY sources.id ASC
+                         LIMIT 50",
+                        $source_cursor
+                    ), ARRAY_A);
+
+                    if (!is_array($sources) || !empty($wpdb->last_error)) {
+                        $this->log_generic_historical_scheduler_error(
+                            'source_status_recovery_scan',
+                            !empty($wpdb->last_error) ? $wpdb->last_error : 'Unable to read generic sources for status reconciliation.'
+                        );
+                    } elseif ($this->generic_advisory_lock_session_is_current($scan_lock)) {
+                        // Wrap to the beginning only after reaching the end of the source set.
+                        $wrapped_to_start = false;
+                        if (!$sources && $source_cursor > 0) {
+                            $source_cursor = 0;
+                            $wrapped_to_start = true;
+                            $sources = statpl_db_get_results(
+                                "SELECT sources.id FROM {$this->view_sources_table} AS sources
+                                 WHERE EXISTS (
+                                     SELECT 1 FROM {$this->view_source_origins_table} AS origins
+                                     WHERE origins.source_id = sources.id
+                                 )
+                                 ORDER BY sources.id ASC
+                                 LIMIT 50",
+                                ARRAY_A
+                            );
+                            if (!is_array($sources) || !empty($wpdb->last_error)) {
+                                $this->log_generic_historical_scheduler_error(
+                                    'source_status_recovery_scan',
+                                    !empty($wpdb->last_error) ? $wpdb->last_error : 'Unable to restart generic source status scan.'
+                                );
+                                $sources = false;
+                            }
+                        }
+
+                        if (is_array($sources) && $sources) {
+                            $last_scanned_source_id = $source_cursor;
+                            $scan_page_completed = true;
+                            foreach ($sources as $source) {
+                                // If wpdb transparently reconnects, the connection-scoped
+                                // scan lock is gone. Stop and leave the cursor unchanged;
+                                // already attempted rows are safe to revisit.
+                                if (!$this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                    $scan_page_completed = false;
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_scan_lock',
+                                        'The MySQL connection changed during source reconciliation; the cursor was not advanced.'
+                                    );
+                                    break;
+                                }
+
+                                $source_id = absint($source['id'] ?? 0);
+                                if (!$source_id) {
+                                    continue;
+                                }
+                                $last_scanned_source_id = max($last_scanned_source_id, $source_id);
+                                try {
+                                    $reconciliation = $this->refresh_generic_historical_source_status($source_id);
+                                    if (!in_array($reconciliation['status'] ?? '', ['updated', 'status_lock_busy', 'source_missing'], true)) {
+                                        $this->log_generic_historical_scheduler_error(
+                                            'source_status_recovery',
+                                            'Source ' . $source_id . ' status reconciliation did not verify: ' . sanitize_key((string) ($reconciliation['status'] ?? 'unknown'))
+                                        );
+                                    }
+                                } catch (Throwable $exception) {
+                                    // One corrupt or temporarily failing source must not prevent
+                                    // the cursor from reaching the remaining sources.
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_recovery',
+                                        'Source ' . $source_id . ' reconciliation threw: ' . $exception->getMessage()
+                                    );
+                                }
+                            }
+
+                            // Advance only after the complete bounded page was attempted
+                            // and the original scan-lock session is still alive. A source
+                            // failure or lock contention is attempted work, not a reason
+                            // to starve later IDs; a lost scan session is different.
+                            if ($scan_page_completed && $this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                // Persist the cursor only in a SQL statement that proves
+                                // this exact connection still owns the scan lock. A PHP-
+                                // level check followed by update_option() is insufficient:
+                                // wpdb may reconnect between those calls and a stale scan
+                                // could overwrite the cursor of a newer lock owner.
+                                $cursor_persisted = statpl_db_query(statpl_db_prepare(
+                                    "INSERT INTO {$wpdb->options} (option_name, option_value, autoload)
+                                     SELECT %s, %s, 'no'
+                                     WHERE IS_USED_LOCK(%s) = CONNECTION_ID()
+                                     ON DUPLICATE KEY UPDATE option_value = IF(
+                                         IS_USED_LOCK(%s) = CONNECTION_ID(),
+                                         VALUES(option_value),
+                                         option_value
+                                     )",
+                                    $cursor_option,
+                                    (string) $last_scanned_source_id,
+                                    $scan_lock_name,
+                                    $scan_lock_name
+                                ));
+                                if (!in_array($cursor_persisted, [0, 1, 2], true)) {
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_recovery_cursor',
+                                        !empty($wpdb->last_error) ? $wpdb->last_error : 'Could not persist the source-status recovery cursor while owning the scan lock.'
+                                    );
+                                }
+                                if (!$this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_recovery_cursor',
+                                        'The MySQL connection changed while persisting the cursor; the next scan will safely re-evaluate the cursor.'
+                                    );
+                                } else {
+                                    $persisted_cursor_value = statpl_db_get_var(statpl_db_prepare(
+                                        "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                                        $cursor_option
+                                    ));
+                                    $persisted_cursor = absint($persisted_cursor_value);
+                                    if (!empty($wpdb->last_error) || $persisted_cursor !== $last_scanned_source_id) {
+                                        $this->log_generic_historical_scheduler_error('source_status_recovery_cursor', 'Could not verify the source-status recovery cursor.');
+                                    }
+                                }
+                            }
+                        } elseif (is_array($sources) && !$sources && $wrapped_to_start) {
+                            if ($this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                // Reset only while the current session still owns the
+                                // scan lock; the predicate is checked atomically by SQL.
+                                $reset_result = statpl_db_query(statpl_db_prepare(
+                                    "INSERT INTO {$wpdb->options} (option_name, option_value, autoload)
+                                     SELECT %s, '0', 'no'
+                                     WHERE IS_USED_LOCK(%s) = CONNECTION_ID()
+                                     ON DUPLICATE KEY UPDATE option_value = IF(
+                                         IS_USED_LOCK(%s) = CONNECTION_ID(), '0', option_value
+                                     )",
+                                    $cursor_option,
+                                    $scan_lock_name,
+                                    $scan_lock_name
+                                ));
+                                if ($reset_result === false || !empty($wpdb->last_error)) {
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_recovery_cursor',
+                                        !empty($wpdb->last_error) ? $wpdb->last_error : 'Could not reset the source-status recovery cursor.'
+                                    );
+                                } elseif ($this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                    $reset_cursor = statpl_db_get_var(statpl_db_prepare(
+                                        "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                                        $cursor_option
+                                    ));
+                                    if (!empty($wpdb->last_error) || absint($reset_cursor) !== 0) {
+                                        $this->log_generic_historical_scheduler_error(
+                                            'source_status_recovery_cursor',
+                                            'Could not verify the reset source-status recovery cursor.'
+                                        );
+                                    }
+                                }
+                            }
+                        }
+                    } else {
+                        $this->log_generic_historical_scheduler_error(
+                            'source_status_scan_lock',
+                            'The MySQL connection changed while reading the source-status page; this page was discarded.'
+                        );
+                    }
+                }
+            } catch (Throwable $exception) {
+                $this->log_generic_historical_scheduler_error('source_status_recovery_scan', $exception->getMessage());
+            } finally {
+                $this->release_generic_advisory_lock($scan_lock, 'source_status_recovery_scan');
+            }
+        }
+
+        return $requeued;
+    }
+
+    /** Write diagnostic messages only when WordPress debugging is enabled. */
+    private function debug_log($message) {
+        if (defined('WP_DEBUG') && WP_DEBUG) {
+            // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- This diagnostic logger writes only when the site owner explicitly enables WP_DEBUG.
+            error_log((string) $message);
+        }
+    }
+
+    /** Log scheduler failures without allowing diagnostics to interrupt tracking. */
+    private function log_generic_historical_scheduler_error($hook, $message) {
+        $this->debug_log('[Statora Plus] Historical scheduler failure for ' . sanitize_key((string) $hook) . ': ' . sanitize_text_field((string) $message));
+    }
+
+    /** Schedule retries for deferred records independently from the main import cursor. */
+    private function schedule_generic_historical_failure_retry($delay, $source_id, $origin_key) {
+        $args = [absint($source_id), sanitize_key((string) $origin_key)];
+        $hook = 'statpl_generic_view_retry_failed_records';
+        $requested_timestamp = time() + max(1, (int) $delay);
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $existing_timestamp = false;
+            if (function_exists('as_next_scheduled_action')) {
+                try {
+                    $existing_timestamp = as_next_scheduled_action($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_lookup', $exception->getMessage());
+                }
+            }
+
+            // Keep an earlier/equal action, but replace a later one. Otherwise a
+            // newly-created short-backoff failure could wait behind an older,
+            // long-backoff retry for the same source-origin.
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp && function_exists('as_unschedule_all_actions')) {
+                try {
+                    as_unschedule_all_actions($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    // The existing action may still be queued. Retain it rather
+                    // than create a duplicate whose execution order is unknown.
+                    $this->log_generic_historical_scheduler_error($hook . '_unschedule', $exception->getMessage());
+                    return true;
+                }
+            } elseif (function_exists('as_has_scheduled_action')) {
+                try {
+                    if (as_has_scheduled_action($hook, $args, 'statpl-plus')) {
+                        // Without reliable timestamp/removal APIs, retain the
+                        // existing action rather than duplicate the worker.
+                        return true;
+                    }
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_presence_check', $exception->getMessage());
+                }
+            }
+            try {
+                $action_id = as_schedule_single_action($requested_timestamp, $hook, $args, 'statpl-plus');
+                if ($action_id) {
+                    return true;
+                }
+            } catch (Throwable $exception) {
+                $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            }
+            // Fall through to WP-Cron if Action Scheduler did not accept the action.
+        }
+
+        try {
+            $existing_timestamp = wp_next_scheduled($hook, $args);
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp) {
+                wp_unschedule_event((int) $existing_timestamp, $hook, $args);
+            }
+            $scheduled = wp_schedule_single_event($requested_timestamp, $hook, $args);
+            if (!$scheduled || is_wp_error($scheduled)) {
+                $this->log_generic_historical_scheduler_error($hook, is_wp_error($scheduled) ? $scheduled->get_error_message() : 'WP-Cron rejected the event.');
+                return false;
+            }
+            return true;
+        } catch (Throwable $exception) {
+            $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            return false;
+        }
+    }
+
+    /** Acquire a connection-scoped advisory lock and capture its owning session. */
+    private function acquire_generic_advisory_lock($lock_name) {
+        global $wpdb;
+        try {
+            $row = statpl_db_get_row(statpl_db_prepare(
+                'SELECT CONNECTION_ID() AS connection_id, GET_LOCK(%s, 0) AS lock_acquired',
+                (string) $lock_name
+            ), ARRAY_A);
+        } catch (Throwable $exception) {
+            return ['acquired' => false, 'status' => 'lock_error', 'error' => $exception->getMessage()];
+        }
+        if (!is_array($row) || !empty($wpdb->last_error) || (string) ($row['lock_acquired'] ?? '') !== '1' || empty($row['connection_id'])) {
+            return ['acquired' => false, 'status' => 'lock_busy_or_unavailable', 'error' => (string) $wpdb->last_error];
+        }
+        return ['acquired' => true, 'connection_id' => (string) $row['connection_id'], 'lock_name' => (string) $lock_name];
+    }
+
+    /** Roll back an open import transaction only on its original DB session. */
+    private function rollback_generic_import_transaction(&$transaction_open, $origin_lock) {
+        global $wpdb;
+        if (!$transaction_open) {
+            return true;
+        }
+        // Never issue transaction control on a transparently reconnected session.
+        // The caller may retry once from finally if this attempt fails.
+        for ($attempt = 0; $attempt < 1; $attempt++) {
+            if (!$this->generic_db_session_matches_lock($origin_lock)) {
+                return false;
+            }
+            $result = statpl_db_query('ROLLBACK');
+            if ($result !== false) {
+                $transaction_open = false;
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** Confirm the current wpdb connection is the session that acquired a lock, regardless of lock ownership. */
+    private function generic_db_session_matches_lock($lock) {
+        global $wpdb;
+        if (!is_array($lock) || empty($lock['acquired']) || empty($lock['connection_id'])) {
+            return false;
+        }
+        try {
+            $connection_id = statpl_db_get_var('SELECT CONNECTION_ID()');
+        } catch (Throwable $exception) {
+            return false;
+        }
+        return $connection_id !== null
+            && empty($wpdb->last_error)
+            && (string) $connection_id === (string) $lock['connection_id'];
+    }
+
+    /** Confirm the current wpdb session still owns the lock-acquiring connection. */
+    private function generic_advisory_lock_session_is_current($lock) {
+        global $wpdb;
+        if (!is_array($lock) || empty($lock['acquired']) || empty($lock['connection_id'])) {
+            return false;
+        }
+        try {
+            // Session identity alone is insufficient: code running on the same
+            // connection could have released or replaced the named lock. Verify
+            // both the connection and the actual lock owner in one SQL read.
+            $row = statpl_db_get_row(statpl_db_prepare(
+                'SELECT CONNECTION_ID() AS connection_id, IS_USED_LOCK(%s) AS lock_owner',
+                (string) $lock['lock_name']
+            ), ARRAY_A);
+        } catch (Throwable $exception) {
+            return false;
+        }
+        return is_array($row)
+            && empty($wpdb->last_error)
+            && (string) ($row['connection_id'] ?? '') === (string) $lock['connection_id']
+            && (string) ($row['lock_owner'] ?? '') === (string) $lock['connection_id'];
+    }
+
+    /** Release only on the original session; a lost session releases its own locks server-side. */
+    private function release_generic_advisory_lock($lock, $context = '') {
+        global $wpdb;
+        if (!$this->generic_advisory_lock_session_is_current($lock)) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: advisory lock session changed before release' . ($context !== '' ? ' (' . sanitize_key($context) . ')' : '') . '.');
+            }
+            return false;
+        }
+        try {
+            $released = statpl_db_get_var(statpl_db_prepare('SELECT RELEASE_LOCK(%s)', (string) $lock['lock_name']));
+            if ((string) $released === '1' && empty($wpdb->last_error)) {
+                return true;
+            }
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: advisory lock release failed' . ($context !== '' ? ' (' . sanitize_key($context) . ')' : '') . ': ' . $exception->getMessage());
+            }
+            return false;
+        }
+        if (defined('WP_DEBUG') && WP_DEBUG) {
+            $this->debug_log('Statora Plus: advisory lock release was not confirmed' . ($context !== '' ? ' (' . sanitize_key($context) . ')' : '') . '.');
+        }
+        return false;
+    }
+
+    /** Replay due failed records from their saved immutable batch checkpoint. */
+    public function retry_generic_historical_view_failures($source_id = 0, $origin_key = '') {
+        global $wpdb;
+        $source_id = absint($source_id);
+        $origin_key = sanitize_key((string) $origin_key);
+        if (!$source_id || $origin_key === '') {
+            return ['status' => 'invalid_input'];
+        }
+
+        $now = current_time('mysql');
+        $failure = statpl_db_get_row(statpl_db_prepare(
+            "SELECT retry_checkpoint, next_retry_at FROM {$this->view_source_failures_table}
+             WHERE source_id = %d AND origin_key = %s AND status = 'retry' AND next_retry_at <= %s
+               AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''
+             ORDER BY next_retry_at ASC, id ASC LIMIT 1",
+            $source_id,
+            $origin_key,
+            $now
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error)) {
+            $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+            return ['status' => 'failure_lookup_error'];
+        }
+        if (!$failure) {
+            $next = statpl_db_get_var(statpl_db_prepare(
+                "SELECT MIN(next_retry_at) FROM {$this->view_source_failures_table}
+                 WHERE source_id = %d AND origin_key = %s AND status = 'retry'
+                   AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''",
+                $source_id,
+                $origin_key
+            ));
+            if (!empty($wpdb->last_error)) {
+                // A failed deadline lookup is not evidence that the retry queue is
+                // empty. Preserve the worker trigger and avoid status aggregation
+                // from an incomplete view of the durable failure ledger.
+                $this->log_generic_historical_scheduler_error('retry_ledger_next_deadline', $wpdb->last_error);
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'failure_ledger_deadline_failed'];
+            }
+            if ($next) {
+                $next_timestamp = strtotime((string) $next);
+                $delay = ($next_timestamp !== false) ? max(1, $next_timestamp - current_time('timestamp')) : 300;
+                $this->schedule_generic_historical_failure_retry(min(86400, $delay), $source_id, $origin_key);
+            }
+            $this->refresh_generic_historical_source_status($source_id);
+            return ['status' => 'no_due_failures'];
+        }
+
+        $lock_name = 'statpl_generic_' . substr(hash('sha256', $wpdb->prefix . ':' . $source_id . ':' . $origin_key), 0, 40);
+        $origin_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($origin_lock['acquired'])) {
+            $this->schedule_generic_historical_failure_retry(30, $source_id, $origin_key);
+            return ['status' => 'worker_already_running'];
+        }
+
+        try {
+            // The initial lookup above only determines whether this worker appears
+            // eligible. Re-read the durable row after acquiring the same origin lock
+            // used by the main importer: another worker may have resolved or changed
+            // this retry while we were waiting. Never replay a stale checkpoint.
+            if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+                $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+                return ['status' => 'origin_lock_session_lost'];
+            }
+            $locked_failure = statpl_db_get_row(statpl_db_prepare(
+                "SELECT retry_checkpoint, next_retry_at FROM {$this->view_source_failures_table}
+                 WHERE source_id = %d AND origin_key = %s AND status = 'retry'
+                   AND next_retry_at <= %s AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''
+                 ORDER BY next_retry_at ASC, id ASC LIMIT 1",
+                $source_id,
+                $origin_key,
+                current_time('mysql')
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error)) {
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'failure_lookup_error'];
+            }
+            if (!$locked_failure) {
+                return ['status' => 'retry_no_longer_due'];
+            }
+
+            $retry_checkpoint = json_decode($locked_failure['retry_checkpoint'], true);
+            if (!is_array($retry_checkpoint) || !$retry_checkpoint) {
+                // Corrupt replay metadata is not silently discarded or counted as a view.
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'invalid_retry_checkpoint'];
+            }
+
+            if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+                $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+                return ['status' => 'origin_lock_session_lost'];
+            }
+            $result = $this->process_generic_historical_view_import_batch($source_id, $origin_key, $retry_checkpoint, $origin_lock);
+        } finally {
+            $this->release_generic_advisory_lock($origin_lock, 'retry_origin');
+        }
+
+        // The processing lock above protects replay itself. Reacquire the same
+        // origin lock before reconciling ledger counts and origin status: the main
+        // importer may have started immediately after the replay lock was released.
+        // Re-reading under the lock prevents this worker from applying stale status
+        // decisions over a newer main-import checkpoint/state transition.
+        $post_origin_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($post_origin_lock['acquired'])) {
+            $this->schedule_generic_historical_failure_retry(30, $source_id, $origin_key);
+            return ['status' => 'post_processing_lock_busy'];
+        }
+
+        try {
+        if (!$this->generic_advisory_lock_session_is_current($post_origin_lock)) {
+            $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+            return ['status' => 'post_processing_lock_session_lost'];
+        }
+        $remaining_value = statpl_db_get_var(statpl_db_prepare(
+            "SELECT COUNT(*) FROM {$this->view_source_failures_table}
+             WHERE source_id = %d AND origin_key = %s AND status = 'retry'
+               AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''",
+            $source_id,
+            $origin_key
+        ));
+        if (!empty($wpdb->last_error) || $remaining_value === null) {
+            // A failed count must never be interpreted as an empty ledger. Keep
+            // the worker alive and let the next pass re-read durable retry rows.
+            $this->log_generic_historical_scheduler_error('retry_ledger_count', $wpdb->last_error ?: 'Retry ledger count returned NULL.');
+            $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+            return ['status' => 'failure_ledger_count_failed'];
+        }
+        $remaining = (int) $remaining_value;
+        if ($remaining > 0) {
+            $next = statpl_db_get_var(statpl_db_prepare(
+                "SELECT MIN(next_retry_at) FROM {$this->view_source_failures_table}
+                 WHERE source_id = %d AND origin_key = %s AND status = 'retry'
+                   AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''",
+                $source_id,
+                $origin_key
+            ));
+            if (!empty($wpdb->last_error)) {
+                $this->log_generic_historical_scheduler_error('retry_ledger_deadline', $wpdb->last_error);
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'failure_ledger_deadline_failed', 'remaining' => $remaining];
+            }
+            $next_timestamp = $next ? strtotime((string) $next) : false;
+            $delay = ($next_timestamp !== false) ? max(1, $next_timestamp - current_time('timestamp')) : 300;
+            $this->schedule_generic_historical_failure_retry(min(86400, $delay), $source_id, $origin_key);
+        } else {
+            $blocked_value = statpl_db_get_var(statpl_db_prepare(
+                "SELECT COUNT(*) FROM {$this->view_source_failures_table}
+                 WHERE source_id = %d AND origin_key = %s AND status = 'blocked'",
+                $source_id,
+                $origin_key
+            ));
+            if (!empty($wpdb->last_error) || $blocked_value === null) {
+                $this->log_generic_historical_scheduler_error('blocked_ledger_count', $wpdb->last_error ?: 'Blocked ledger count returned NULL.');
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'failure_ledger_count_failed'];
+            }
+            $blocked = (int) $blocked_value;
+            $current_state = $this->get_view_source_origin_state($source_id, $origin_key);
+            $origin_status = $current_state['origin_status'] ?? '';
+            if (in_array($origin_status, ['pending', 'snapshot_ready', 'importing', 'retry_wait'], true)) {
+                // The retry worker cannot infer whether the main scan has reached
+                // the immutable snapshot boundary. This remains true when some
+                // records are already blocked: the main cursor may still have
+                // later batches to import. Resume the main scan and let its own
+                // has_more result, together with the durable ledger counts, decide
+                // whether the final state is completed or needs_attention.
+                $updates = [
+                    'status' => 'importing',
+                    'completed_at' => null,
+                ];
+                if ($blocked === 0) {
+                    $updates['last_error'] = null;
+                }
+                $origin_state_result = $this->update_view_source_origin_state($source_id, $origin_key, $updates, $post_origin_lock);
+                if (!in_array($origin_state_result['status'] ?? '', ['updated'], true)) {
+                    // Do not treat a failed/ambiguous state transition as a
+                    // successful retry finalization. Keep recovery scheduled.
+                    $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+                    return [
+                        'status' => 'origin_state_recovery_failed',
+                        'origin_state' => $origin_state_result,
+                        'result' => $result,
+                        'remaining' => $remaining,
+                    ];
+                }
+                $this->schedule_generic_historical_view_import_batch(5, $source_id, $origin_key);
+            } elseif ($blocked > 0 && $origin_status !== 'needs_attention') {
+                // Only a non-progressing, nonterminal origin may be finalized here.
+                // Never downgrade an already-finalized attention state.
+                $origin_state_result = $this->update_view_source_origin_state($source_id, $origin_key, [
+                    'status' => 'needs_attention',
+                    'last_error' => 'Some historical records could not be recovered after three total attempts.',
+                ], $post_origin_lock);
+                if (!in_array($origin_state_result['status'] ?? '', ['updated'], true)) {
+                    $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+                    return [
+                        'status' => 'origin_state_recovery_failed',
+                        'origin_state' => $origin_state_result,
+                        'result' => $result,
+                        'remaining' => $remaining,
+                    ];
+                }
+            }
+        }
+
+        // Ledger reconciliation may itself encounter a reconnect after the
+        // post-processing lock was acquired. Never aggregate source status unless
+        // this request still owns that exact MySQL lock session.
+        if ($this->generic_advisory_lock_session_is_current($post_origin_lock)) {
+            $this->refresh_generic_historical_source_status($source_id);
+        } else {
+            $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+            return ['status' => 'post_processing_session_lost', 'result' => $result, 'remaining' => $remaining];
+        }
+        return ['status' => 'retry_processed', 'result' => $result, 'remaining' => $remaining];
+        } finally {
+            $this->release_generic_advisory_lock($post_origin_lock, 'retry_post_processing');
+        }
+    }
+
+    /** Return a discovered adapter instance for later snapshot/import workers. */
+    private function get_historical_view_adapter($adapter_key) {
+        $adapter_key = sanitize_key((string) $adapter_key);
+        return isset($this->historical_view_adapters[$adapter_key])
+            ? $this->historical_view_adapters[$adapter_key]
+            : null;
+    }
+
+    /** Schedule the generic historical importer without overlapping scheduled runs. */
+    private function schedule_generic_historical_view_import_batch($delay = 10, $source_id = 0, $origin_key = '') {
+        $args = [(int) $source_id, (string) $origin_key];
+        $hook = 'statpl_generic_view_import_batch';
+        $requested_timestamp = time() + max(1, (int) $delay);
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $existing_timestamp = false;
+            if (function_exists('as_next_scheduled_action')) {
+                try {
+                    $existing_timestamp = as_next_scheduled_action($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_lookup', $exception->getMessage());
+                }
+            }
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp && function_exists('as_unschedule_all_actions')) {
+                try {
+                    as_unschedule_all_actions($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_unschedule', $exception->getMessage());
+                    return true;
+                }
+            } elseif ($existing_timestamp) {
+                return true;
+            } elseif (function_exists('as_has_scheduled_action')) {
+                try {
+                    if (as_has_scheduled_action($hook, $args, 'statpl-plus')) {
+                        // Without reliable timing/removal APIs, retain the existing action.
+                        return true;
+                    }
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_presence_check', $exception->getMessage());
+                }
+            }
+            try {
+                $action_id = as_schedule_single_action($requested_timestamp, $hook, $args, 'statpl-plus');
+                if ($action_id) {
+                    return true;
+                }
+            } catch (Throwable $exception) {
+                $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            }
+            // Fall through to WP-Cron if Action Scheduler did not accept the action.
+        }
+
+        try {
+            $existing_timestamp = wp_next_scheduled($hook, $args);
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp) {
+                wp_unschedule_event((int) $existing_timestamp, $hook, $args);
+            }
+            $scheduled = wp_schedule_single_event($requested_timestamp, $hook, $args);
+            if (!$scheduled || is_wp_error($scheduled)) {
+                $this->log_generic_historical_scheduler_error($hook, is_wp_error($scheduled) ? $scheduled->get_error_message() : 'WP-Cron rejected the event.');
+                return false;
+            }
+            return true;
+        } catch (Throwable $exception) {
+            $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            return false;
+        }
+    }
+
+    /** Persist a generic-source failure with bounded exponential retry metadata. */
+    private function record_generic_historical_view_failure($source_id, $origin_key, $record_key, $product_id, $error, $retry_checkpoint = null, $max_attempts = 8, $lock_context = null) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        if (!$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return ['attempts' => 0, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'lock_session_lost'];
+        }
+        $record_key = substr((string) $record_key, 0, 191);
+        if ($record_key === '') {
+            $record_key = 'batch:' . substr(hash('sha256', (string) $origin_key), 0, 32);
+        }
+        $record_hash = hash('sha256', (string) $origin_key . "\0" . $record_key);
+        $existing = statpl_db_get_row(statpl_db_prepare(
+            "SELECT id, attempts, status, next_retry_at, retry_checkpoint, last_error FROM {$this->view_source_failures_table} WHERE source_id = %d AND source_record_hash = %s LIMIT 1",
+            $source_id,
+            $record_hash
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error)) {
+            $this->log_generic_historical_scheduler_error('failure_ledger_lookup', $wpdb->last_error);
+            return ['attempts' => 0, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'ledger_lookup_failed'];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return ['attempts' => 0, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'lock_session_lost'];
+        }
+        $now = current_time('mysql');
+        if ($existing && isset($existing['status']) && $existing['status'] === 'blocked') {
+            // The ledger row may have been committed even if the corresponding
+            // origin-state update failed on the previous pass. Repair that
+            // derived state on every subsequent locked observation without
+            // incrementing attempts or rewriting the durable failure record.
+            $existing_origin_status = empty($existing['retry_checkpoint']) ? 'needs_attention' : 'retry_wait';
+            $origin_state_saved = $this->update_view_source_origin_state($source_id, $origin_key, [
+                'last_error' => substr((string) ($existing['last_error'] ?? ''), 0, 2000),
+                'status' => $existing_origin_status,
+            ], $lock_context);
+            if (empty($origin_state_saved['status']) || $origin_state_saved['status'] !== 'updated') {
+                $this->log_generic_historical_scheduler_error('failure_origin_state_recovery', $origin_state_saved['error'] ?? ($origin_state_saved['status'] ?? 'Unable to recover origin state from the existing blocked failure record.'));
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                return ['attempts' => (int) $existing['attempts'], 'blocked' => true, 'persisted' => true, 'retry_delay' => 0, 'status' => 'origin_state_recovery_failed'];
+            }
+            return ['attempts' => (int) $existing['attempts'], 'blocked' => true, 'persisted' => true, 'retry_delay' => 0, 'status' => 'already_blocked'];
+        }
+        if ($existing && !empty($existing['next_retry_at']) && $existing['next_retry_at'] > $now) {
+            $retry_at = strtotime((string) $existing['next_retry_at']);
+            $now_at = strtotime((string) $now);
+            $remaining = ($retry_at !== false && $now_at !== false) ? max(1, $retry_at - $now_at) : 60;
+            $origin_state_saved = $this->update_view_source_origin_state($source_id, $origin_key, [
+                'last_error' => substr((string) ($existing['last_error'] ?? ''), 0, 2000),
+                'status' => 'retry_wait',
+            ], $lock_context);
+            if (empty($origin_state_saved['status']) || $origin_state_saved['status'] !== 'updated') {
+                $this->log_generic_historical_scheduler_error('failure_origin_state_recovery', $origin_state_saved['error'] ?? ($origin_state_saved['status'] ?? 'Unable to recover origin state from the existing retry failure record.'));
+                $this->schedule_generic_historical_failure_retry(min(86400, $remaining), $source_id, $origin_key);
+                return ['attempts' => (int) $existing['attempts'], 'blocked' => true, 'persisted' => true, 'retry_delay' => 0, 'status' => 'origin_state_recovery_failed'];
+            }
+            return ['attempts' => (int) $existing['attempts'], 'blocked' => false, 'persisted' => true, 'retry_delay' => min(86400, $remaining), 'status' => 'retry_already_scheduled'];
+        }
+
+        $attempts = $existing ? ((int) $existing['attempts'] + 1) : 1;
+        $max_attempts = max(1, absint($max_attempts));
+        $blocked = $attempts >= $max_attempts;
+        $delay = min(86400, 60 * (2 ** min(10, max(0, $attempts - 1))));
+        $next_retry = $blocked ? null : current_datetime()->modify('+' . $delay . ' seconds')->format('Y-m-d H:i:s');
+        $data = [
+            'source_id' => $source_id,
+            'origin_key' => sanitize_key((string) $origin_key),
+            'source_record_key' => $record_key,
+            'source_record_hash' => $record_hash,
+            'product_id' => absint($product_id),
+            'attempts' => $attempts,
+            'last_error' => substr(sanitize_textarea_field((string) $error), 0, 60000),
+            'status' => $blocked ? 'blocked' : 'retry',
+            'next_retry_at' => $next_retry,
+            'retry_checkpoint' => is_array($retry_checkpoint) ? wp_json_encode($retry_checkpoint) : null,
+            'updated_at' => $now,
+        ];
+        $allowed_columns = [
+            'source_id', 'origin_key', 'source_record_key', 'source_record_hash',
+            'product_id', 'attempts', 'last_error', 'status', 'next_retry_at',
+            'retry_checkpoint', 'updated_at',
+        ];
+        $columns = array_keys($data);
+        if (array_diff($columns, $allowed_columns) || array_diff($allowed_columns, $columns)) {
+            $this->log_generic_historical_scheduler_error('failure_ledger_schema', 'Failure ledger data did not match the fixed column allowlist.');
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'ledger_schema_mismatch'];
+        }
+        $placeholders = [];
+        $values = [];
+        foreach ($allowed_columns as $column) {
+            $value = $data[$column];
+            $placeholders[] = is_int($value) ? '%d' : '%s';
+            $values[] = $value;
+        }
+        $lock_name = (string) ($lock_context['lock_name'] ?? '');
+        if ($lock_name === '' || !$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'lock_session_lost'];
+        }
+
+        if ($existing) {
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- The SET placeholders are generated from the fixed allowlist; update_values is generated from the same allowlist with the same immutable key columns excluded, followed by id and lock_name.
+            $set = [];
+            foreach ($allowed_columns as $column) {
+                if (in_array($column, ['source_id', 'source_record_hash'], true)) {
+                    continue;
+                }
+                $value = $data[$column];
+                $set[] = "`{$column}` = " . (is_int($value) ? '%d' : '%s');
+            }
+            $update_values = [];
+            foreach ($allowed_columns as $column) {
+                if (!in_array($column, ['source_id', 'source_record_hash'], true)) {
+                    $update_values[] = $data[$column];
+                }
+            }
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- The SET placeholder list and update_values are built in the same pass over the fixed 11-column allowlist, excluding the same two immutable key columns; the two trailing placeholders are always id and lock_name.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $query = /* phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- Placeholder fragments and their values are assembled together from the same fixed allowlists; optional lock predicates and matching values are added together. */ statpl_db_prepare(
+                "UPDATE {$this->view_source_failures_table} SET " . implode(', ', /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $set) . " WHERE id = %d AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+                array_merge($update_values, [(int) $existing['id'], $lock_name])
+            );
+        } else {
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $query = statpl_db_prepare(
+                "INSERT INTO {$this->view_source_failures_table} (" . implode(', ', /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ array_map(function ($column) { return "`{$column}`"; }, $columns)) . ") SELECT " . implode(', ', $placeholders) . " WHERE IS_USED_LOCK(%s) = CONNECTION_ID()",
+                array_merge($values, [$lock_name])
+            );
+        }
+        // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $query is assigned exclusively from statpl_db_prepare() in both branches; dynamic identifiers and column names come from fixed allowlists, and all data values use placeholders.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+        $persisted = statpl_db_query($query);
+        if ($persisted === false || $wpdb->last_error !== '') {
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'ledger_write_failed', 'error' => $wpdb->last_error];
+        }
+        if ($persisted !== 1) {
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'lock_session_lost'];
+        }
+        if (strpos($record_key, 'batch:') !== 0 && $record_key !== 'snapshot_initialization') {
+            $this->save_generic_historical_report_record($source_id, $origin_key, $record_hash, $blocked ? 'failed' : 'retry', $attempts, 'record_import_failed');
+        }
+
+        $origin_status = ($blocked && !is_array($retry_checkpoint)) ? 'needs_attention' : 'retry_wait';
+        $origin_state_saved = $this->update_view_source_origin_state($source_id, $origin_key, [
+            'last_error' => substr((string) $error, 0, 2000),
+            'status' => $origin_status,
+        ], $lock_context);
+        if (empty($origin_state_saved['status']) || !in_array($origin_state_saved['status'], ['updated'], true)) {
+            $this->log_generic_historical_scheduler_error('failure_origin_state', $origin_state_saved['error'] ?? ($origin_state_saved['status'] ?? 'Unable to update origin state after recording a failure.'));
+            // The failure row is durable, but its derived origin status may be
+            // stale. Ensure another locked pass is scheduled to repair the
+            // origin state; do not rely on callers, which correctly stop when
+            // this operation reports blocked=true.
+            if (is_array($retry_checkpoint)) {
+                $this->schedule_generic_historical_failure_retry(max(60, $delay), $source_id, $origin_key);
+            } else {
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            }
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => true, 'retry_delay' => 0, 'status' => 'origin_state_update_failed'];
+        }
+
+        return ['attempts' => $attempts, 'blocked' => $blocked, 'persisted' => true, 'retry_delay' => $blocked ? 0 : $delay];
+    }
+
+    /** Clear a previously recorded failure after its record is safely handled. */
+    private function clear_generic_historical_view_failure($source_id, $origin_key, $record_key, $lock_context = null, $report_outcome = 'imported') {
+        global $wpdb;
+        if (!$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return false;
+        }
+        $record_key = substr((string) $record_key, 0, 191);
+        if ($record_key === '') {
+            return false;
+        }
+        $record_hash = hash('sha256', (string) $origin_key . "\0" . $record_key);
+        $existing_failure = statpl_db_get_row(statpl_db_prepare(
+            "SELECT attempts FROM {$this->view_source_failures_table} WHERE source_id = %d AND source_record_hash = %s LIMIT 1",
+            absint($source_id), $record_hash
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error)) { return false; }
+        if ($report_outcome === 'imported' && strpos($record_key, 'batch:') !== 0 && $record_key !== 'snapshot_initialization') {
+            $attempts = is_array($existing_failure) ? (int) ($existing_failure['attempts'] ?? 0) : 0;
+            if (!$this->save_generic_historical_report_record($source_id, $origin_key, $record_hash, 'imported', $attempts, '')) { return false; }
+        }
+        $lock_name = (string) ($lock_context['lock_name'] ?? '');
+        if ($lock_name === '' || !$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return false;
+        }
+        $deleted = statpl_db_query(statpl_db_prepare(
+            "DELETE FROM {$this->view_source_failures_table} WHERE source_id = %d AND source_record_hash = %s AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+            absint($source_id),
+            $record_hash,
+            $lock_name
+        ));
+        if ($deleted === false || $wpdb->last_error !== '') {
+            $this->log_generic_historical_scheduler_error('failure_ledger_clear', $wpdb->last_error ?: 'Unable to clear a resolved failure record.');
+            return false;
+        }
+        // A zero-row DELETE is ambiguous: the failure row may already be absent,
+        // or the SQL ownership predicate may have rejected the operation after a
+        // reconnect/lock loss. Only treat the former as successful, and confirm
+        // that this worker still owns the original lock session after the query.
+        if (!$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Process one generic source-origin batch. Each accepted record is committed
+     * atomically with its source event and product total; the checkpoint advances
+     * only after the record is safely applied or recognized as an exact duplicate.
+     */
+    public function run_generic_historical_view_import_batch($source_id = 0, $origin_key = '') {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = sanitize_key((string) $origin_key);
+        if (!$source_id || $origin_key === '') {
+            return ['status' => 'invalid_input'];
+        }
+
+        // A connection-scoped MySQL advisory lock prevents two cron/Action
+        // Scheduler workers from advancing the same source-origin checkpoint.
+        // The lock is released automatically if PHP or the DB connection dies.
+        $lock_name = 'statpl_generic_' . substr(hash('sha256', $wpdb->prefix . ':' . $source_id . ':' . $origin_key), 0, 40);
+        $origin_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($origin_lock['acquired'])) {
+            $this->schedule_generic_historical_view_import_batch(30, $source_id, $origin_key);
+            return ['status' => 'worker_already_running'];
+        }
+
+        try {
+            if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                return ['status' => 'origin_lock_session_lost'];
+            }
+            $result = $this->process_generic_historical_view_import_batch($source_id, $origin_key, null, $origin_lock);
+            // The processing method can return after detecting a lost MySQL session.
+            // Do not start a new source-status write on a transparently reconnected
+            // session: it would run outside the origin lock that serialized this worker.
+            if ($this->generic_advisory_lock_session_is_current($origin_lock)) {
+                $this->refresh_generic_historical_source_status($source_id);
+            } else {
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            }
+            return $result;
+        } finally {
+            $this->release_generic_advisory_lock($origin_lock, 'main_importer');
+        }
+    }
+
+    /** Validate a normalized source datetime without allowing silent MySQL coercion. */
+    private function is_valid_generic_historical_datetime($value) {
+        if ($value === null || $value === '') {
+            return true;
+        }
+        if (!is_string($value) || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $value)) {
+            return false;
+        }
+        $date = DateTime::createFromFormat('!Y-m-d H:i:s', $value);
+        $errors = DateTime::getLastErrors();
+        return $date instanceof DateTime
+            && ($errors === false || (empty($errors['warning_count']) && empty($errors['error_count'])))
+            && $date->format('Y-m-d H:i:s') === $value;
+    }
+
+    /** Accept only a JSON-safe scalar/array cursor that can be persisted and resumed. */
+    private function is_valid_generic_historical_cursor($cursor) {
+        if ($cursor === null || is_resource($cursor) || is_object($cursor)) {
+            return false;
+        }
+        $encoded = wp_json_encode($cursor);
+        return is_string($encoded) && strlen($encoded) <= 60000;
+    }
+
+    /**
+     * Discover overlap candidates fairly across source IDs. A global LIMIT can let
+     * a high-volume source crowd every other adapter out of the reconciliation set.
+     * The per-source fetch is bounded, then candidates are interleaved round-robin.
+     */
+    private function get_generic_reconciliation_candidates_by_source($mode, $criteria, $limit = 25) {
+        global $wpdb;
+
+        if (!is_array($criteria)) {
+            return ['status' => 'error', 'error' => 'Invalid reconciliation criteria.', 'events' => [], 'observed' => 0, 'truncated' => false];
+        }
+        if ($mode === 'fingerprint') {
+            $fingerprint = isset($criteria['fingerprint']) ? (string) $criteria['fingerprint'] : '';
+            $source_id = isset($criteria['source_id']) ? absint($criteria['source_id']) : 0;
+            if ($fingerprint === '' || !$source_id) {
+                return ['status' => 'error', 'error' => 'Invalid fingerprint reconciliation criteria.', 'events' => [], 'observed' => 0, 'truncated' => false];
+            }
+            $where_sql = 'events.source_fingerprint = %s AND events.source_id <> %d';
+            $where_args = [$fingerprint, $source_id];
+        } elseif ($mode === 'temporal') {
+            $source_id = isset($criteria['source_id']) ? absint($criteria['source_id']) : 0;
+            $product_id = isset($criteria['product_id']) ? absint($criteria['product_id']) : 0;
+            $period_start = isset($criteria['period_start']) ? (string) $criteria['period_start'] : '';
+            $period_end = isset($criteria['period_end']) ? (string) $criteria['period_end'] : '';
+            if (!$source_id || !$product_id || $period_start === '' || $period_end === '') {
+                return ['status' => 'error', 'error' => 'Invalid temporal reconciliation criteria.', 'events' => [], 'observed' => 0, 'truncated' => false];
+            }
+            $where_sql = 'events.source_id <> %d AND events.product_id = %d AND events.period_start <= %s AND events.period_end >= %s';
+            $where_args = [$source_id, $product_id, $period_end, $period_start];
+        } else {
+            return ['status' => 'error', 'error' => 'Unsupported reconciliation mode.', 'events' => [], 'observed' => 0, 'truncated' => false];
+        }
+        $limit = max(1, min(25, absint($limit)));
+        $reconciliation_sql = "SELECT DISTINCT events.source_id
+             FROM {$this->view_source_events_table} AS events
+             WHERE {$where_sql}
+             ORDER BY events.source_id ASC";
+        // The criteria branches above define either four temporal placeholders
+        // or two exact-match placeholders; prepare receives the matching values.
+        if ($mode === 'temporal') {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_ids = statpl_db_get_col(statpl_db_prepare(
+                /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $reconciliation_sql,
+                $source_id,
+                $product_id,
+                $period_end,
+                $period_start
+            ));
+        } else {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_ids = statpl_db_get_col(statpl_db_prepare(
+                /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $reconciliation_sql,
+                $fingerprint,
+                $source_id
+            ));
+        }
+        if (!empty($wpdb->last_error)) {
+            return ['status' => 'error', 'error' => (string) $wpdb->last_error, 'events' => [], 'observed' => 0, 'truncated' => false];
+        }
+
+        $per_source = [];
+        $observed = 0;
+        $truncated = false;
+        foreach ((array) $source_ids as $candidate_source_id) {
+            $candidate_source_id = absint($candidate_source_id);
+            if (!$candidate_source_id) {
+                continue;
+            }
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                "SELECT events.id, events.source_id, events.source_record_key,
+                        sources.source_key AS candidate_source_key,
+                        sources.adapter_key AS candidate_adapter_key, events.product_id,
+                        events.record_type, events.observed_views, events.period_start,
+                        events.period_end, events.applied_views
+                 FROM {$this->view_source_events_table} AS events
+                 LEFT JOIN {$this->view_sources_table} AS sources ON sources.id = events.source_id
+                 WHERE ({$where_sql}) AND events.source_id = %d
+                 ORDER BY events.period_start ASC, events.period_end ASC, events.id ASC
+                 LIMIT 26 FOR UPDATE",
+                array_merge($where_args, [$candidate_source_id])
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error)) {
+                return ['status' => 'error', 'error' => (string) $wpdb->last_error, 'events' => [], 'observed' => $observed, 'truncated' => $truncated];
+            }
+            if (count($rows) > 25) {
+                $truncated = true;
+                $rows = array_slice($rows, 0, 25);
+            }
+            $observed += count($rows);
+            if ($rows) {
+                $per_source[$candidate_source_id] = array_values($rows);
+            }
+        }
+
+        $events = [];
+        $round = 0;
+        do {
+            $added_this_round = false;
+            foreach ($per_source as $source_rows) {
+                if (isset($source_rows[$round])) {
+                    $events[] = $source_rows[$round];
+                    $added_this_round = true;
+                    if (count($events) > $limit) {
+                        $truncated = true;
+                        break 2;
+                    }
+                }
+            }
+            $round++;
+        } while ($added_this_round);
+
+        if ($observed > count($events)) {
+            $truncated = true;
+        }
+        return [
+            'status' => 'ok',
+            'events' => array_slice($events, 0, $limit),
+            'observed' => $observed,
+            'truncated' => $truncated,
+        ];
+    }
+
+    /**
+     * Build a source-wide, deterministic overlap profile for the current record.
+     * This is deliberately descriptive: timestamps and aggregate periods are not
+     * proof that two providers observed the same pageview. The profile gives the
+     * later reconciliation pass comparable signals without changing applied_views.
+     */
+    /**
+     * Return declared source capabilities for reconciliation review.
+     * This is a descriptive capability inventory, not a numeric reliability score.
+     * Missing declarations remain unknown; they are never inferred from plugin names.
+     */
+    private function get_generic_source_capability_profiles($source_ids) {
+        global $wpdb;
+
+        $source_ids = array_values(array_unique(array_filter(array_map('absint', (array) $source_ids))));
+        if (!$source_ids) {
+            return ['status' => 'empty', 'sources' => [], 'requested_source_count' => 0];
+        }
+
+        // The list is built only from normalized positive integer source IDs.
+        // A fixed-size batch limit keeps the SQL placeholder count bounded.
+        $placeholders = implode(',', array_fill(0, count($source_ids), '%d'));
+        // Start from the source registry and LEFT JOIN origins. A persisted source
+        // with no origin row must remain visible as an unknown-capability source;
+        // an INNER JOIN would silently omit it from the reconciliation inventory.
+        $inventory_sql = "SELECT s.id AS source_id, s.source_key, s.display_name,
+                    s.adapter_key AS source_adapter_key, s.granularity AS source_granularity,
+                    o.origin_key, o.adapter_key, o.capabilities,
+                    o.detection_status
+             FROM {$this->view_sources_table} AS s
+             LEFT JOIN {$this->view_source_origins_table} AS o ON o.source_id = s.id
+             WHERE s.id IN ({$placeholders})
+             ORDER BY s.id ASC, o.origin_key ASC";
+        // prepare() accepts an argument array as its second parameter. This keeps
+        // the dynamically sized placeholder list paired with its normalized IDs.
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+        $rows = statpl_db_get_results(statpl_db_prepare($inventory_sql, $source_ids), ARRAY_A);
+        if (!empty($wpdb->last_error) || !is_array($rows)) {
+            return [
+                'status' => 'query_failed',
+                'sources' => [],
+                'requested_source_count' => count($source_ids),
+                'error' => (string) $wpdb->last_error,
+            ];
+        }
+
+        $profiles = [];
+        foreach ($rows as $row) {
+            $id = absint($row['source_id'] ?? 0);
+            if (!$id) { continue; }
+            $profiles[$id] = $profiles[$id] ?? [
+                'source_id' => $id,
+                'source_key' => sanitize_key((string) ($row['source_key'] ?? '')),
+                'display_name' => sanitize_text_field((string) ($row['display_name'] ?? '')),
+                'source_adapter_key' => sanitize_key((string) ($row['source_adapter_key'] ?? '')),
+                'source_granularity' => sanitize_key((string) ($row['source_granularity'] ?? 'unknown')),
+                'origin_profile_status' => 'available',
+                'origins' => [],
+            ];
+
+            // A NULL origin row is meaningful: the source exists, but no declared
+            // origin capabilities are available. Do not infer them from its name.
+            if ($row['origin_key'] === null || $row['origin_key'] === '') {
+                $profiles[$id]['origin_profile_status'] = 'no_origin_declarations';
+                continue;
+            }
+
+            $declared = json_decode((string) ($row['capabilities'] ?? ''), true);
+            if (!is_array($declared)) { $declared = []; }
+
+            $granularity = sanitize_key((string) ($declared['granularity'] ?? 'unknown'));
+            $precision = sanitize_key((string) ($declared['timestamp_precision'] ?? 'unknown'));
+            $storage_granularity = sanitize_key((string) ($declared['source_storage_granularity'] ?? 'unknown'));
+            $profiles[$id]['origins'][] = [
+                'origin_key' => sanitize_key((string) ($row['origin_key'] ?? '')),
+                'adapter_key' => sanitize_key((string) ($row['adapter_key'] ?? '')),
+                'detection_status' => sanitize_key((string) ($row['detection_status'] ?? 'unknown')),
+                'granularity' => $granularity,
+                'timestamp_precision' => $precision,
+                'source_storage_granularity' => $storage_granularity,
+                'product_id_direct' => array_key_exists('product_id_direct', $declared) ? (bool) $declared['product_id_direct'] : null,
+                'target_requires_product_resolution' => array_key_exists('target_requires_product_resolution', $declared) ? (bool) $declared['target_requires_product_resolution'] : null,
+                'stable_event_identity_declared' => array_key_exists('stable_event_identity', $declared) ? (bool) $declared['stable_event_identity'] : null,
+                'bot_filtered' => array_key_exists('bot_filtered', $declared) ? (bool) $declared['bot_filtered'] : null,
+                'immutable_past_days' => array_key_exists('immutable_past_days', $declared) ? (bool) $declared['immutable_past_days'] : null,
+                'capability_comparability' => [
+                    'event_level' => $granularity === 'event',
+                    'second_precision' => $precision === 'seconds',
+                    'direct_product_mapping' => !empty($declared['product_id_direct']),
+                    'aggregate_only_or_unknown' => in_array($granularity, ['daily_aggregate', 'hourly_aggregate', 'unknown'], true),
+                ],
+            ];
+        }
+
+        // Preserve requested IDs that have no matching source-registry row as
+        // explicit unresolved entries instead of silently shrinking the scope.
+        foreach ($source_ids as $requested_id) {
+            if (!isset($profiles[$requested_id])) {
+                $profiles[$requested_id] = [
+                    'source_id' => $requested_id,
+                    'source_key' => '',
+                    'display_name' => '',
+                    'source_adapter_key' => '',
+                    'source_granularity' => 'unknown',
+                    'origin_profile_status' => 'source_registry_row_missing',
+                    'origins' => [],
+                ];
+            }
+        }
+        ksort($profiles, SORT_NUMERIC);
+
+        $resolved_count = 0;
+        $without_origin_count = 0;
+        foreach ($profiles as $profile) {
+            if (($profile['origin_profile_status'] ?? '') === 'source_registry_row_missing') {
+                continue;
+            }
+            $resolved_count++;
+            if (($profile['origin_profile_status'] ?? '') === 'no_origin_declarations') {
+                $without_origin_count++;
+            }
+        }
+        $status = $resolved_count < count($source_ids)
+            ? 'partial'
+            : ($without_origin_count > 0 ? 'partial' : 'available');
+
+        return [
+            'status' => $status,
+            'sources' => array_values($profiles),
+            'requested_source_count' => count($source_ids),
+            'resolved_source_count' => $resolved_count,
+            'sources_without_origin_declarations' => $without_origin_count,
+        ];
+    }
+
+    private function build_generic_cross_source_overlap_assessment($product_id, $source_id, $adapter_key, $record_type, $period_start, $period_end, $candidates, $truncated = false, $observed_views = 0) {
+        $product_id = absint($product_id);
+        $record_type = sanitize_key((string) $record_type);
+        $period_start = $period_start !== null ? (string) $period_start : '';
+        $period_end = $period_end !== null ? (string) $period_end : '';
+        $sources = [];
+        $same_instant_event_candidates = 0;
+        $same_bounds_aggregate_candidates = 0;
+        $intersecting_aggregate_candidates = 0;
+        $different_type_candidates = 0;
+
+        foreach ((array) $candidates as $candidate) {
+            if (!is_array($candidate) || (int) ($candidate['product_id'] ?? 0) !== $product_id) {
+                continue;
+            }
+            $candidate_source_id = absint($candidate['source_id'] ?? 0);
+            if (!$candidate_source_id) {
+                continue;
+            }
+            $candidate_type = sanitize_key((string) ($candidate['record_type'] ?? ''));
+            $candidate_start = isset($candidate['period_start']) ? (string) $candidate['period_start'] : '';
+            $candidate_end = isset($candidate['period_end']) ? (string) $candidate['period_end'] : '';
+            $same_bounds = $period_start !== '' && $period_end !== ''
+                && $candidate_start === $period_start && $candidate_end === $period_end;
+            $intersects = $period_start !== '' && $period_end !== ''
+                && $candidate_start !== '' && $candidate_end !== ''
+                && $candidate_start <= $period_end && $candidate_end >= $period_start;
+
+            if (!isset($sources[$candidate_source_id])) {
+                $sources[$candidate_source_id] = [
+                    'source_id' => $candidate_source_id,
+                    'source_key' => isset($candidate['candidate_source_key']) ? (string) $candidate['candidate_source_key'] : null,
+                    'adapter_key' => isset($candidate['candidate_adapter_key']) ? (string) $candidate['candidate_adapter_key'] : null,
+                    'record_types' => [],
+                    'candidate_records' => 0,
+                ];
+            }
+            $sources[$candidate_source_id]['candidate_records']++;
+            if ($candidate_type !== '') {
+                $sources[$candidate_source_id]['record_types'][$candidate_type] = true;
+            }
+
+            if ($candidate_type !== $record_type) {
+                $different_type_candidates++;
+            }
+            if ($record_type === 'event' && $candidate_type === 'event' && $same_bounds) {
+                $same_instant_event_candidates++;
+            } elseif ($record_type === 'aggregate' && $candidate_type === 'aggregate' && $same_bounds) {
+                $same_bounds_aggregate_candidates++;
+            } elseif ($intersects && ($record_type === 'aggregate' || $candidate_type === 'aggregate')) {
+                $intersecting_aggregate_candidates++;
+            }
+        }
+
+        foreach ($sources as &$source) {
+            $source['record_types'] = array_keys($source['record_types']);
+            sort($source['record_types'], SORT_STRING);
+        }
+        unset($source);
+        ksort($sources, SORT_NUMERIC);
+
+        // Identical naive datetime labels cannot establish a shared temporal
+        // bucket without persisted source-timezone provenance; no count range is inferred.
+        $same_bucket_range = [
+            'status' => 'unavailable',
+            'reason' => 'timezone_basis_not_persisted',
+            'minimum_unique_views' => null,
+            'maximum_unique_views' => null,
+            'minimum_possible_duplicate_views' => null,
+            'maximum_possible_duplicate_views' => null,
+            'source_contributions' => [],
+        ];
+
+        $capability_source_ids = array_merge([absint($source_id)], array_keys($sources));
+        $capability_profiles = $this->get_generic_source_capability_profiles($capability_source_ids);
+
+        return [
+            'version' => '0.2.0',
+            'scope' => 'same_product_different_sources',
+            'incoming_source' => [
+                'source_id' => absint($source_id),
+                'adapter_key' => sanitize_key((string) $adapter_key),
+                'record_type' => $record_type,
+            ],
+            'candidate_sources' => array_values($sources),
+            'source_capability_profiles' => $capability_profiles,
+            'reliability_policy' => 'declared_capabilities_only_no_numeric_score_or_inferred_trust_rank',
+            'candidate_source_count' => count($sources),
+            'candidate_record_count' => array_sum(array_column(array_values($sources), 'candidate_records')),
+            'same_instant_event_candidates' => $same_instant_event_candidates,
+            'same_bounds_aggregate_candidates' => $same_bounds_aggregate_candidates,
+            'intersecting_aggregate_candidates' => $intersecting_aggregate_candidates,
+            'period_comparison_semantics' => 'raw_datetime_string_representation_only_timezone_unverified',
+            'different_record_type_candidates' => $different_type_candidates,
+            'candidate_set_truncated' => (bool) $truncated,
+            'identical_bucket_count_range' => $same_bucket_range,
+            'identity_confidence' => 'unproven_without_shared_event_identity',
+            'temporal_basis_status' => 'timezone_provenance_not_persisted',
+            'absolute_temporal_comparison_performed' => false,
+            'counting_decision' => 'preserve_contribution_pending_global_reconciliation',
+            'policy' => 'Stored datetime strings and identical period bounds are representation-level signals only because source timezone provenance is not persisted; no absolute-time overlap or unique-view range is asserted and no contribution is suppressed by this assessment.',
+        ];
+    }
+
+    /**
+     * Build a bounded product-wide inventory across every persisted generic source.
+     * This is a descriptive synthesis of recorded contributions, not a unique-view
+     * estimate: source totals are never added, ranked, or suppressed here.
+     */
+    private function build_generic_product_source_synthesis($product_id) {
+        global $wpdb;
+
+        $product_id = absint($product_id);
+        if (!$product_id) {
+            return ['status' => 'unavailable', 'reason' => 'invalid_product_id', 'sources' => []];
+        }
+
+        // Keep the source-ID inventory independent of the bounded record-group
+        // result so capability profiles cover every source, even when the
+        // descriptive record inventory reaches its output limit.
+        $source_id_rows = statpl_db_get_col(statpl_db_prepare(
+            "SELECT DISTINCT source_id
+             FROM {$this->view_source_events_table}
+             WHERE product_id = %d
+             ORDER BY source_id ASC",
+            $product_id
+        ));
+        if (!empty($wpdb->last_error) || !is_array($source_id_rows)) {
+            return ['status' => 'query_failed', 'reason' => 'product_source_id_inventory_query_failed', 'sources' => []];
+        }
+        $all_source_ids = array_values(array_unique(array_filter(array_map('absint', $source_id_rows))));
+
+        $rows = statpl_db_get_results(statpl_db_prepare(
+            "SELECT e.source_id, s.source_key, s.display_name, e.record_type,
+                    COUNT(*) AS record_count, SUM(e.observed_views) AS observed_views,
+                    SUM(e.applied_views) AS applied_views,
+                    MIN(e.period_start) AS first_period_start,
+                    MAX(e.period_end) AS last_period_end
+             FROM {$this->view_source_events_table} AS e
+             LEFT JOIN {$this->view_sources_table} AS s ON s.id = e.source_id
+             WHERE e.product_id = %d
+             GROUP BY e.source_id, s.source_key, s.display_name, e.record_type
+             ORDER BY e.source_id ASC, e.record_type ASC
+             LIMIT 101",
+            $product_id
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error) || !is_array($rows)) {
+            return ['status' => 'query_failed', 'reason' => 'product_source_inventory_query_failed', 'sources' => []];
+        }
+        $truncated = count($rows) > 100;
+        if ($truncated) {
+            $rows = array_slice($rows, 0, 100);
+        }
+        $sources = [];
+        foreach ($rows as $row) {
+            $source_id = absint($row['source_id'] ?? 0);
+            if (!$source_id) { continue; }
+            if (!isset($sources[$source_id])) {
+                $sources[$source_id] = [
+                    'source_id' => $source_id,
+                    'source_key' => sanitize_key((string) ($row['source_key'] ?? '')),
+                    'display_name' => sanitize_text_field((string) ($row['display_name'] ?? '')),
+                    'record_types' => [],
+                ];
+            }
+            $sources[$source_id]['record_types'][] = [
+                'record_type' => sanitize_key((string) ($row['record_type'] ?? 'unknown')),
+                'record_count' => max(0, (int) ($row['record_count'] ?? 0)),
+                'observed_views' => max(0, (int) ($row['observed_views'] ?? 0)),
+                'applied_views' => max(0, (int) ($row['applied_views'] ?? 0)),
+                'first_period_start' => $row['first_period_start'] !== null ? (string) $row['first_period_start'] : null,
+                'last_period_end' => $row['last_period_end'] !== null ? (string) $row['last_period_end'] : null,
+            ];
+        }
+        ksort($sources, SORT_NUMERIC);
+
+        $capability_profiles = $this->get_generic_source_capability_profiles($all_source_ids);
+        $capability_profiles_by_source = [];
+        // A partial capability lookup still contains useful, successfully
+        // resolved profiles plus explicit unresolved entries. Retain every
+        // returned profile; the status separately communicates incompleteness.
+        if (in_array(($capability_profiles['status'] ?? ''), ['available', 'partial'], true)) {
+            foreach ((array) ($capability_profiles['sources'] ?? []) as $profile) {
+                $profile_source_id = absint($profile['source_id'] ?? 0);
+                if ($profile_source_id) {
+                    $capability_profiles_by_source[$profile_source_id] = $profile;
+                }
+            }
+        }
+
+        return [
+            'status' => 'available',
+            'scope' => 'all_persisted_generic_sources_for_product',
+            'sources' => array_values($sources),
+            'source_ids_in_scope' => $all_source_ids,
+            'source_count_in_scope' => count($all_source_ids),
+            'source_capability_profiles' => array_values($capability_profiles_by_source),
+            'capability_profile_status' => sanitize_key((string) ($capability_profiles['status'] ?? 'unknown')),
+            'capability_profile_source_count' => count($capability_profiles_by_source),
+            'source_record_groups_truncated' => $truncated,
+            'unique_view_total' => null,
+            'counting_decision' => 'no_cross_source_sum_or_suppression',
+            'policy' => 'Observed and applied contributions are reported separately by source and record type; declared capabilities are attached for every source in scope where available, without numeric reliability ranking or a deduplicated product-view total.',
+        ];
+    }
+
+    /**
+     * Combine the independently collected reconciliation evidence into one
+     * product-level audit summary. This is classification only: it never
+     * estimates unique views, changes applied_views, or authorizes suppression.
+     */
+    /**
+     * Classify the completeness and ambiguity of the retained cross-source candidate set.
+     * Candidate ordering identifies an audit primary only; it never establishes identity.
+     */
+    private function build_generic_candidate_set_assessment($candidates, $candidates_truncated = false, $observed_count = null) {
+        $candidates = is_array($candidates) ? $candidates : [];
+        $by_id = [];
+        $source_ids = [];
+        foreach ($candidates as $candidate) {
+            if (!is_array($candidate)) {
+                continue;
+            }
+            $event_id = isset($candidate['id']) ? (int) $candidate['id'] : 0;
+            $source_id = isset($candidate['source_id']) ? (int) $candidate['source_id'] : 0;
+            if ($event_id > 0) {
+                $by_id[$event_id] = true;
+            }
+            if ($source_id > 0) {
+                $source_ids[$source_id] = true;
+            }
+        }
+        $candidate_count = count($by_id);
+        $source_count = count($source_ids);
+        $observed_count = $observed_count === null ? $candidate_count : max($candidate_count, (int) $observed_count);
+        $truncated = (bool) $candidates_truncated;
+
+        if ($candidate_count > 1 || $truncated || $observed_count > $candidate_count) {
+            $classification = 'multiple_or_truncated_candidates_require_review';
+        } elseif ($candidate_count === 1) {
+            $classification = 'single_candidate_requires_review';
+        } else {
+            $classification = 'no_candidate_available';
+        }
+
+        return [
+            'classification' => $classification,
+            'candidate_count_retained' => $candidate_count,
+            'candidate_event_ids' => array_map('intval', array_keys($by_id)),
+            'candidate_source_ids_by_event_id' => array_intersect_key(array_reduce($candidates, static function ($carry, $candidate) {
+                if (is_array($candidate) && !empty($candidate['id']) && !empty($candidate['source_id'])) {
+                    $carry[(int) $candidate['id']] = (int) $candidate['source_id'];
+                }
+                return $carry;
+            }, []), $by_id),
+            'candidate_count_observed' => $observed_count,
+            'candidate_source_count_retained' => $source_count,
+            'multiple_candidate_ambiguity' => $candidate_count > 1 || $observed_count > 1,
+            'multiple_source_ambiguity' => $source_count > 1,
+            'candidate_set_truncated' => $truncated,
+            'candidate_count_is_lower_bound' => $truncated,
+            'primary_candidate_is_identity_proof' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'All retained candidates remain evidence. Primary ordering is for audit navigation only and does not resolve identity or authorize count suppression.',
+        ];
+    }
+
+    /**
+     * Describe conflicting or heterogeneous dimensions across retained candidates.
+     * Differences are classified as evidence only; this method never resolves identity
+     * or changes the contribution applied to product totals.
+     */
+    /**
+     * Validate the integrity of the per-candidate audit records. Missing or duplicate
+     * identifiers and malformed classifications are retained as audit errors; this
+     * method never infers identity or authorizes suppression.
+     */
+    private function build_generic_candidate_record_integrity_assessment($candidate_details, $expected_unique_candidate_count) {
+        $candidate_details = is_array($candidate_details) ? $candidate_details : [];
+        $expected_unique_candidate_count = max(0, (int) $expected_unique_candidate_count);
+        $errors = [];
+        $seen_ids = [];
+        $missing_id_count = 0;
+        $duplicate_id_count = 0;
+        $invalid_classification_count = 0;
+        $invalid_dimension_check_count = 0;
+        $allowed_classifications = [
+            'fingerprint_dimension_mismatch',
+            'temporal_candidate_different_record_shape',
+            'candidate_dimensions_match_without_identity_proof',
+            'insufficient_candidate_dimensions',
+        ];
+        $required_dimensions = ['product_id', 'record_type', 'observed_views', 'period_start', 'period_end'];
+
+        foreach ($candidate_details as $detail) {
+            if (!is_array($detail)) {
+                $missing_id_count++;
+                $invalid_classification_count++;
+                $invalid_dimension_check_count++;
+                continue;
+            }
+            $candidate_id = absint($detail['candidate_event_id'] ?? 0);
+            if (!$candidate_id) {
+                $missing_id_count++;
+            } elseif (isset($seen_ids[$candidate_id])) {
+                $duplicate_id_count++;
+            } else {
+                $seen_ids[$candidate_id] = true;
+            }
+            if (!in_array($detail['classification'] ?? null, $allowed_classifications, true)) {
+                $invalid_classification_count++;
+            }
+            $checks = $detail['dimension_checks'] ?? null;
+            $checks_valid = is_array($checks);
+            if ($checks_valid) {
+                foreach ($required_dimensions as $dimension) {
+                    if (!array_key_exists($dimension, $checks)
+                        || !in_array($checks[$dimension], [true, false, null], true)) {
+                        $checks_valid = false;
+                        break;
+                    }
+                }
+            }
+            if (!$checks_valid) {
+                $invalid_dimension_check_count++;
+            }
+        }
+
+        $detail_count = count($candidate_details);
+        $unique_id_count = count($seen_ids);
+        if ($missing_id_count > 0) {
+            $errors[] = 'candidate_audit_record_missing_valid_event_id';
+        }
+        if ($duplicate_id_count > 0) {
+            $errors[] = 'candidate_audit_records_contain_duplicate_event_ids';
+        }
+        if ($invalid_classification_count > 0) {
+            $errors[] = 'candidate_audit_record_has_invalid_classification';
+        }
+        if ($invalid_dimension_check_count > 0) {
+            $errors[] = 'candidate_audit_record_has_invalid_dimension_checks';
+        }
+        if ($detail_count !== $expected_unique_candidate_count || $unique_id_count !== $expected_unique_candidate_count) {
+            $errors[] = 'candidate_audit_record_count_does_not_match_unique_candidate_inventory';
+        }
+
+        return [
+            'status' => $errors ? 'candidate_records_require_review' : 'candidate_records_valid',
+            'consistent' => !$errors,
+            'errors' => array_values(array_unique($errors)),
+            'candidate_detail_count' => $detail_count,
+            'unique_valid_candidate_id_count' => $unique_id_count,
+            'expected_unique_candidate_count' => $expected_unique_candidate_count,
+            'missing_id_count' => $missing_id_count,
+            'duplicate_id_count' => $duplicate_id_count,
+            'invalid_classification_count' => $invalid_classification_count,
+            'invalid_dimension_check_count' => $invalid_dimension_check_count,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Record validation is audit-only. Invalid records remain visible for review and cannot establish identity or authorize suppression.',
+        ];
+    }
+
+    private function build_generic_candidate_conflict_assessment($incoming, $candidates) {
+        $incoming = is_array($incoming) ? $incoming : [];
+        $candidates = is_array($candidates) ? $candidates : [];
+        $counts = [
+            'fingerprint_dimension_mismatch' => 0,
+            'temporal_candidate_different_record_shape' => 0,
+            'candidate_dimensions_match_without_identity_proof' => 0,
+            'insufficient_candidate_dimensions' => 0,
+        ];
+        $candidate_ids = [];
+        $dimension_signatures = [];
+        $details = [];
+        foreach ($candidates as $candidate) {
+            if (!is_array($candidate)) {
+                continue;
+            }
+            $candidate_id = absint($candidate['id'] ?? 0);
+            if ($candidate_id) {
+                $candidate_ids[$candidate_id] = true;
+            }
+            $discovered_by = array_values((array) ($candidate['_discovered_by'] ?? []));
+            $has_fingerprint_signal = in_array('fingerprint', $discovered_by, true);
+            $has_temporal_signal = in_array('temporal', $discovered_by, true);
+            $checks = [
+                'product_id' => isset($incoming['product_id'], $candidate['product_id'])
+                    ? (int) $incoming['product_id'] === (int) $candidate['product_id'] : null,
+                'record_type' => isset($incoming['record_type'], $candidate['record_type'])
+                    ? (string) $incoming['record_type'] === (string) $candidate['record_type'] : null,
+                'observed_views' => isset($incoming['observed_views'], $candidate['observed_views'])
+                    ? (int) $incoming['observed_views'] === (int) $candidate['observed_views'] : null,
+                'period_start' => !empty($incoming['period_start']) && !empty($candidate['period_start'])
+                    ? (string) $incoming['period_start'] === (string) $candidate['period_start'] : null,
+                'period_end' => !empty($incoming['period_end']) && !empty($candidate['period_end'])
+                    ? (string) $incoming['period_end'] === (string) $candidate['period_end'] : null,
+            ];
+            $known_checks = array_filter($checks, static function ($value) { return $value !== null; });
+            $all_known_dimensions_match = count($known_checks) === count($checks)
+                && !in_array(false, $known_checks, true);
+            $has_dimension_difference = in_array(false, $known_checks, true);
+            if ($has_fingerprint_signal && $has_dimension_difference) {
+                $classification = 'fingerprint_dimension_mismatch';
+            } elseif ($has_temporal_signal && (
+                $checks['record_type'] === false || $checks['observed_views'] === false
+            )) {
+                $classification = 'temporal_candidate_different_record_shape';
+            } elseif ($all_known_dimensions_match) {
+                $classification = 'candidate_dimensions_match_without_identity_proof';
+            } else {
+                $classification = 'insufficient_candidate_dimensions';
+            }
+            $counts[$classification]++;
+            $signature = implode('|', [
+                (string) ($candidate['product_id'] ?? 'unknown'),
+                (string) ($candidate['record_type'] ?? 'unknown'),
+                (string) ($candidate['observed_views'] ?? 'unknown'),
+                (string) ($candidate['period_start'] ?? ''),
+                (string) ($candidate['period_end'] ?? ''),
+            ]);
+            $dimension_signatures[$signature] = true;
+            $details[] = [
+                'candidate_event_id' => $candidate_id ?: null,
+                'candidate_source_id' => !empty($candidate['source_id']) ? (int) $candidate['source_id'] : null,
+                'discovered_by' => $discovered_by,
+                'classification' => $classification,
+                'dimension_checks' => $checks,
+                'identity_proven' => false,
+                'automatic_suppression_authorized' => false,
+            ];
+        }
+        $candidate_count = count($candidate_ids);
+        $record_integrity = $this->build_generic_candidate_record_integrity_assessment($details, $candidate_count);
+        $heterogeneous = count($dimension_signatures) > 1;
+        $has_conflict = $counts['fingerprint_dimension_mismatch'] > 0
+            || $counts['temporal_candidate_different_record_shape'] > 0;
+        return [
+            'status' => $candidate_count ? 'available' : 'no_candidates',
+            'candidate_count' => $candidate_count,
+            'candidate_dimension_signature_count' => count($dimension_signatures),
+            'candidate_set_is_heterogeneous' => $heterogeneous,
+            'conflicting_evidence_present' => $has_conflict,
+            'classification_counts' => $counts,
+            'candidate_record_integrity' => $record_integrity,
+            'candidates' => $details,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Dimension differences and heterogeneous candidates are retained as review evidence only; they do not establish identity, select a winning candidate, or authorize count suppression.',
+        ];
+    }
+
+    /**
+     * Make an explicit audit decision from candidate support and contradiction evidence.
+     * Absence of candidates is not evidence that sources do not overlap. A clean dimensional
+     * comparison is not identity proof, and truncation always limits the conclusion.
+     */
+    private function build_generic_candidate_evidence_decision($conflict_assessment, $candidate_set_assessment = [], $candidate_search_truncated = false) {
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $counts = (array) ($conflict_assessment['classification_counts'] ?? []);
+        $fingerprint_conflicts = max(0, (int) ($counts['fingerprint_dimension_mismatch'] ?? 0));
+        $temporal_shape_conflicts = max(0, (int) ($counts['temporal_candidate_different_record_shape'] ?? 0));
+        $matching_dimensions = max(0, (int) ($counts['candidate_dimensions_match_without_identity_proof'] ?? 0));
+        $insufficient_dimensions = max(0, (int) ($counts['insufficient_candidate_dimensions'] ?? 0));
+        $candidate_count = max(0, (int) ($conflict_assessment['candidate_count'] ?? 0));
+        $truncated = (bool) $candidate_search_truncated
+            || !empty($candidate_set_assessment['candidate_set_truncated'])
+            || !empty($candidate_set_assessment['candidate_count_is_lower_bound']);
+
+        $support = [];
+        $contradictions = [];
+        $limitations = [];
+        if ($matching_dimensions > 0) {
+            $support[] = 'candidate_dimensions_match_but_do_not_prove_shared_identity';
+        }
+        if ($fingerprint_conflicts > 0) {
+            $contradictions[] = 'fingerprint_discovery_signal_has_dimension_mismatches';
+        }
+        if ($temporal_shape_conflicts > 0) {
+            $contradictions[] = 'temporal_candidates_have_different_record_shapes';
+        }
+        if ($insufficient_dimensions > 0) {
+            $limitations[] = 'candidate_dimensions_are_incomplete';
+        }
+        if ($truncated) {
+            $limitations[] = 'candidate_search_truncated_conclusion_is_incomplete';
+        }
+
+        if ($candidate_count === 0) {
+            $classification = $truncated
+                ? 'candidate_search_incomplete_no_retained_candidate_no_overlap_conclusion'
+                : 'no_candidate_found_within_search_bounds_overlap_remains_unknown';
+        } elseif ($fingerprint_conflicts > 0 || $temporal_shape_conflicts > 0) {
+            $classification = ($matching_dimensions > 0)
+                ? 'supporting_and_contradictory_evidence_require_review'
+                : 'contradictory_candidate_evidence_requires_review';
+        } elseif ($matching_dimensions > 0) {
+            $classification = 'supportive_dimensions_without_identity_proof';
+        } else {
+            $classification = 'insufficient_candidate_evidence_requires_review';
+        }
+        if ($truncated && $candidate_count > 0) {
+            $limitations[] = 'retained_candidates_are_not_the_complete_observed_set';
+        }
+
+        return [
+            'classification' => $classification,
+            'supporting_evidence' => array_values(array_unique($support)),
+            'contradictory_evidence' => array_values(array_unique($contradictions)),
+            'limitations' => array_values(array_unique($limitations)),
+            'supporting_candidate_count' => $matching_dimensions,
+            'fingerprint_dimension_conflict_count' => $fingerprint_conflicts,
+            'temporal_record_shape_conflict_count' => $temporal_shape_conflicts,
+            'insufficient_dimension_candidate_count' => $insufficient_dimensions,
+            'candidate_count' => $candidate_count,
+            'candidate_search_truncated' => $truncated,
+            'absence_of_candidates_proves_no_overlap' => false,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Support, contradiction, and missing evidence are reported separately. No candidate is not proof of no overlap; matching dimensions are not proof of identity; no evidence classification changes applied_views or authorizes suppression.',
+        ];
+    }
+
+    /**
+     * Validate that candidate inventory, conflict assessment, and evidence decision
+     * describe the same retained evidence and preserve the non-suppression policy.
+     * This is an audit integrity check only; it never changes reconciliation outcomes.
+     */
+    private function build_generic_candidate_audit_consistency($candidate_set_assessment, $conflict_assessment, $evidence_decision) {
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $evidence_decision = is_array($evidence_decision) ? $evidence_decision : [];
+        $errors = [];
+        $candidate_count = max(0, (int) ($conflict_assessment['candidate_count'] ?? 0));
+        $retained_count = max(0, (int) ($candidate_set_assessment['candidate_count_retained'] ?? 0));
+        $decision_count = max(0, (int) ($evidence_decision['candidate_count'] ?? 0));
+        $counts = (array) ($conflict_assessment['classification_counts'] ?? []);
+        $record_integrity = $conflict_assessment['candidate_record_integrity'] ?? null;
+        $record_integrity = is_array($record_integrity) ? $record_integrity : [];
+        $classified_count = 0;
+        foreach ([
+            'fingerprint_dimension_mismatch',
+            'temporal_candidate_different_record_shape',
+            'candidate_dimensions_match_without_identity_proof',
+            'insufficient_candidate_dimensions',
+        ] as $key) {
+            $classified_count += max(0, (int) ($counts[$key] ?? 0));
+        }
+        if ($candidate_count !== $retained_count || $candidate_count !== $decision_count) {
+            $errors[] = 'candidate_counts_disagree_across_audit_layers';
+        }
+        if (empty($conflict_assessment['candidate_record_integrity']) || !is_array($conflict_assessment['candidate_record_integrity'])) {
+            $errors[] = 'candidate_record_integrity_assessment_missing_from_conflict_audit';
+        } elseif (empty($record_integrity['consistent'])) {
+            $errors[] = 'candidate_record_integrity_validation_failed';
+        }
+        if (isset($record_integrity['expected_unique_candidate_count'])
+            && (int) $record_integrity['expected_unique_candidate_count'] !== $candidate_count) {
+            $errors[] = 'candidate_record_integrity_expected_count_disagrees_with_conflict_inventory';
+        }
+        if ($classified_count > $candidate_count) {
+            $errors[] = 'candidate_classification_count_exceeds_candidate_inventory';
+        } elseif ($classified_count < $candidate_count) {
+            $errors[] = 'candidate_classification_coverage_incomplete';
+        }
+        $classification_coverage_complete = $classified_count === $candidate_count;
+        foreach ([
+            'supporting_candidate_count' => 'candidate_dimensions_match_without_identity_proof',
+            'fingerprint_dimension_conflict_count' => 'fingerprint_dimension_mismatch',
+            'temporal_record_shape_conflict_count' => 'temporal_candidate_different_record_shape',
+            'insufficient_dimension_candidate_count' => 'insufficient_candidate_dimensions',
+        ] as $decision_key => $conflict_key) {
+            if (max(0, (int) ($evidence_decision[$decision_key] ?? 0)) !== max(0, (int) ($counts[$conflict_key] ?? 0))) {
+                $errors[] = 'evidence_decision_count_mismatch_' . $decision_key;
+            }
+        }
+        $set_truncated = !empty($candidate_set_assessment['candidate_set_truncated']);
+        $decision_truncated = !empty($evidence_decision['candidate_search_truncated']);
+        if ($set_truncated && !$decision_truncated) {
+            $errors[] = 'candidate_truncation_not_propagated_to_evidence_decision';
+        }
+        if (!empty($conflict_assessment['identity_proven']) || !empty($evidence_decision['identity_proven'])) {
+            $errors[] = 'candidate_evidence_layer_claims_identity_proof';
+        }
+        if (!empty($candidate_set_assessment['automatic_suppression_authorized'])
+            || !empty($conflict_assessment['automatic_suppression_authorized'])
+            || !empty($evidence_decision['automatic_suppression_authorized'])) {
+            $errors[] = 'candidate_evidence_layer_authorizes_automatic_suppression';
+        }
+        if ($candidate_count === 0 && !empty($evidence_decision['absence_of_candidates_proves_no_overlap'])) {
+            $errors[] = 'absence_of_candidates_misrepresented_as_no_overlap_proof';
+        }
+        return [
+            'status' => $errors ? 'inconsistent_audit_evidence_requires_review' : 'candidate_audit_layers_consistent',
+            'consistent' => !$errors,
+            'errors' => array_values(array_unique($errors)),
+            'candidate_count_conflict_assessment' => $candidate_count,
+            'candidate_count_inventory' => $retained_count,
+            'candidate_count_evidence_decision' => $decision_count,
+            'classified_candidate_count' => $classified_count,
+            'unclassified_candidate_count' => max(0, $candidate_count - $classified_count),
+            'classification_coverage_complete' => $classification_coverage_complete,
+            'candidate_record_integrity' => [
+                'present' => !empty($conflict_assessment['candidate_record_integrity']) && is_array($conflict_assessment['candidate_record_integrity']),
+                'consistent' => !empty($record_integrity['consistent']),
+                'errors' => array_values((array) ($record_integrity['errors'] ?? [])),
+                'candidate_detail_count' => max(0, (int) ($record_integrity['candidate_detail_count'] ?? 0)),
+                'unique_valid_candidate_id_count' => max(0, (int) ($record_integrity['unique_valid_candidate_id_count'] ?? 0)),
+                'expected_unique_candidate_count' => max(0, (int) ($record_integrity['expected_unique_candidate_count'] ?? 0)),
+            ],
+            'candidate_search_truncated' => $decision_truncated,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Consistency validation is audit-only. A failed validation requires review and never changes applied_views or authorizes count suppression.',
+        ];
+    }
+
+    /**
+     * Compare the event/source references retained by candidate inventory and
+     * per-candidate conflict records. Reference mismatches require review only.
+     */
+    private function build_generic_candidate_reference_consistency($candidate_set_assessment, $conflict_assessment) {
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $inventory_ids = array_values(array_unique(array_filter(array_map('absint', (array) ($candidate_set_assessment['candidate_event_ids'] ?? [])))));
+        $detail_ids = [];
+        $detail_sources = [];
+        $duplicate_detail_ids = [];
+        foreach ((array) ($conflict_assessment['candidates'] ?? []) as $detail) {
+            if (!is_array($detail) || empty($detail['candidate_event_id'])) {
+                continue;
+            }
+            $id = absint($detail['candidate_event_id']);
+            if (isset($detail_ids[$id])) {
+                $duplicate_detail_ids[] = $id;
+            }
+            $detail_ids[$id] = true;
+            $detail_sources[$id] = isset($detail['candidate_source_id']) ? absint($detail['candidate_source_id']) : 0;
+        }
+        $inventory_set = array_fill_keys($inventory_ids, true);
+        $detail_set = $detail_ids;
+        $missing_details = array_values(array_diff($inventory_ids, array_keys($detail_set)));
+        $unexpected_details = array_values(array_diff(array_keys($detail_set), $inventory_ids));
+        $source_mismatches = [];
+        $inventory_sources = (array) ($candidate_set_assessment['candidate_source_ids_by_event_id'] ?? []);
+        foreach ($inventory_sources as $event_id => $source_id) {
+            $event_id = absint($event_id);
+            $source_id = absint($source_id);
+            if (isset($detail_sources[$event_id]) && $detail_sources[$event_id] !== $source_id) {
+                $source_mismatches[] = $event_id;
+            }
+        }
+        $errors = [];
+        if ($missing_details) { $errors[] = 'candidate_inventory_event_missing_conflict_detail'; }
+        if ($unexpected_details) { $errors[] = 'conflict_detail_event_missing_from_candidate_inventory'; }
+        if ($duplicate_detail_ids) { $errors[] = 'conflict_details_contain_duplicate_event_references'; }
+        if ($source_mismatches) { $errors[] = 'candidate_source_reference_mismatch'; }
+        return [
+            'status' => $errors ? 'candidate_references_require_review' : 'candidate_references_consistent',
+            'consistent' => !$errors,
+            'errors' => $errors,
+            'inventory_event_ids' => $inventory_ids,
+            'conflict_detail_event_ids' => array_map('intval', array_keys($detail_set)),
+            'missing_conflict_detail_event_ids' => $missing_details,
+            'unexpected_conflict_detail_event_ids' => $unexpected_details,
+            'duplicate_conflict_detail_event_ids' => array_values(array_unique($duplicate_detail_ids)),
+            'source_reference_mismatch_event_ids' => array_values(array_unique($source_mismatches)),
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Reference consistency validates audit traceability only; it does not establish shared event identity or authorize suppression.',
+        ];
+    }
+
+    /**
+     * Validate discovery-signal provenance for every retained candidate. Signals
+     * explain why a candidate was found; they are never treated as identity proof.
+     */
+    private function build_generic_candidate_discovery_signal_consistency($candidate_set_assessment, $conflict_assessment) {
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $inventory_ids = array_values(array_unique(array_filter(array_map('absint', (array) ($candidate_set_assessment['candidate_event_ids'] ?? [])))));
+        $allowed_signals = ['fingerprint', 'temporal'];
+        $candidate_signals = [];
+        $missing_signal_ids = [];
+        $unknown_signals = [];
+        $duplicate_signals = [];
+        $unexpected_ids = [];
+        $inventory_set = array_fill_keys($inventory_ids, true);
+        foreach ((array) ($conflict_assessment['candidates'] ?? []) as $detail) {
+            if (!is_array($detail) || empty($detail['candidate_event_id'])) {
+                continue;
+            }
+            $event_id = absint($detail['candidate_event_id']);
+            if (!isset($inventory_set[$event_id])) {
+                $unexpected_ids[] = $event_id;
+            }
+            $signals = $detail['discovered_by'] ?? null;
+            if (!is_array($signals) || !$signals) {
+                $missing_signal_ids[] = $event_id;
+                $candidate_signals[$event_id] = [];
+                continue;
+            }
+            $normalized = [];
+            foreach ($signals as $signal) {
+                if (!is_string($signal) || !in_array($signal, $allowed_signals, true)) {
+                    $unknown_signals[] = ['candidate_event_id' => $event_id, 'signal' => is_scalar($signal) ? (string) $signal : gettype($signal)];
+                    continue;
+                }
+                if (in_array($signal, $normalized, true)) {
+                    $duplicate_signals[] = ['candidate_event_id' => $event_id, 'signal' => $signal];
+                }
+                $normalized[] = $signal;
+            }
+            $candidate_signals[$event_id] = array_values(array_unique($normalized));
+        }
+        $missing_candidate_ids = array_values(array_diff($inventory_ids, array_keys($candidate_signals)));
+        $errors = [];
+        if ($missing_signal_ids) { $errors[] = 'candidate_discovery_signal_missing'; }
+        if ($missing_candidate_ids) { $errors[] = 'candidate_discovery_record_missing'; }
+        if ($unexpected_ids) { $errors[] = 'discovery_signal_candidate_outside_inventory'; }
+        if ($unknown_signals) { $errors[] = 'unknown_candidate_discovery_signal'; }
+        if ($duplicate_signals) { $errors[] = 'duplicate_candidate_discovery_signal'; }
+        return [
+            'status' => $errors ? 'candidate_discovery_signals_require_review' : 'candidate_discovery_signals_consistent',
+            'consistent' => !$errors,
+            'errors' => $errors,
+            'allowed_signal_types' => $allowed_signals,
+            'candidate_signals_by_event_id' => $candidate_signals,
+            'missing_signal_event_ids' => array_values(array_unique($missing_signal_ids)),
+            'missing_candidate_record_event_ids' => $missing_candidate_ids,
+            'unexpected_candidate_event_ids' => array_values(array_unique($unexpected_ids)),
+            'unknown_signals' => $unknown_signals,
+            'duplicate_signals' => $duplicate_signals,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Fingerprint and temporal signals describe discovery provenance only; neither signal establishes shared event identity or authorizes suppression.',
+        ];
+    }
+
+    /**
+     * Verify that adapter evidence preserves the discovery signals recorded for
+     * each candidate. Discovery provenance remains advisory and is never identity proof.
+     */
+    private function build_generic_adapter_discovery_evidence_consistency($conflict_assessment, $adapter_overlap_evidence) {
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $adapter_overlap_evidence = is_array($adapter_overlap_evidence) ? $adapter_overlap_evidence : [];
+        $expected = [];
+        foreach ((array) ($conflict_assessment['candidates'] ?? []) as $candidate) {
+            if (!is_array($candidate) || empty($candidate['candidate_event_id'])) { continue; }
+            $id = absint($candidate['candidate_event_id']);
+            $expected[$id] = array_values(array_unique(array_filter((array) ($candidate['discovered_by'] ?? []), 'is_string')));
+        }
+        $seen = [];
+        $missing = [];
+        $unexpected = [];
+        $mismatched = [];
+        $duplicate = [];
+        $invalid = [];
+        $allowed = ['fingerprint', 'temporal'];
+        foreach ($adapter_overlap_evidence as $entry) {
+            if (!is_array($entry) || empty($entry['candidate_event_id'])) { $invalid[] = 'missing_candidate_event_id'; continue; }
+            $id = absint($entry['candidate_event_id']);
+            if (isset($seen[$id])) { $duplicate[] = $id; }
+            $seen[$id] = true;
+            if (!array_key_exists($id, $expected)) { $unexpected[] = $id; continue; }
+            $signals = $entry['discovered_by'] ?? null;
+            if (!is_array($signals)) { $invalid[] = $id; continue; }
+            foreach ($signals as $signal) {
+                if (!is_string($signal) || !in_array($signal, $allowed, true)) { $invalid[] = $id; }
+            }
+            $normalized = array_values(array_unique(array_filter($signals, 'is_string')));
+            sort($normalized);
+            $expected_normalized = $expected[$id];
+            sort($expected_normalized);
+            $comparison_signals = $entry['comparison']['identity_assessment']['candidate_discovery_signals'] ?? null;
+            if (!is_array($comparison_signals)) {
+                $mismatched[] = $id;
+            } else {
+                $comparison_normalized = array_values(array_unique(array_filter($comparison_signals, 'is_string')));
+                sort($comparison_normalized);
+                if ($comparison_normalized !== $normalized) { $mismatched[] = $id; }
+            }
+            if ($normalized !== $expected_normalized) { $mismatched[] = $id; }
+        }
+        $missing = array_values(array_diff(array_keys($expected), array_keys($seen)));
+        $errors = [];
+        if ($missing) { $errors[] = 'adapter_discovery_evidence_missing_candidates'; }
+        if ($unexpected) { $errors[] = 'adapter_discovery_evidence_has_unexpected_candidates'; }
+        if ($mismatched) { $errors[] = 'adapter_discovery_signals_disagree_with_candidate_inventory'; }
+        if ($duplicate) { $errors[] = 'adapter_discovery_evidence_has_duplicate_candidates'; }
+        if ($invalid) { $errors[] = 'adapter_discovery_evidence_has_invalid_signals_or_records'; }
+        return [
+            'status' => $errors ? 'adapter_discovery_evidence_requires_review' : 'adapter_discovery_evidence_consistent',
+            'consistent' => !$errors,
+            'errors' => $errors,
+            'candidate_count_expected' => count($expected),
+            'candidate_count_observed' => count($seen),
+            'missing_candidate_event_ids' => $missing,
+            'unexpected_candidate_event_ids' => array_values(array_unique($unexpected)),
+            'mismatched_candidate_event_ids' => array_values(array_unique($mismatched)),
+            'duplicate_candidate_event_ids' => array_values(array_unique($duplicate)),
+            'invalid_candidate_records' => array_values(array_unique($invalid, SORT_REGULAR)),
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Adapter evidence must preserve discovery provenance; matching signals remain discovery evidence only and never establish shared event identity.',
+        ];
+    }
+
+    /**
+     * Compare the normalized dimensions in adapter evidence with the dimensions
+     * independently classified for each candidate. This validates audit transport,
+     * not shared identity; missing values remain unknown rather than matching.
+     */
+    /**
+     * Classify temporal granularity without treating interval overlap as identity.
+     * Daily windows, aggregate periods and point timestamps are distinct evidence shapes.
+     */
+    /**
+     * Describe the temporal basis that can actually be established from the
+     * adapter contract. The current event table does not persist a timezone or
+     * timezone-version fingerprint, so even WordPress-local values produced by
+     * two adapters cannot safely be compared as absolute instants across imports.
+     * Calendar aggregates retain date-label semantics and are not converted to
+     * timestamps. This helper is descriptive and never authorizes suppression.
+     */
+    private function classify_reconciliation_temporal_basis($adapter_key, $origin_key, $record_type) {
+        $adapter_key = sanitize_key((string) $adapter_key);
+        $origin_key = sanitize_key((string) $origin_key);
+        $record_type = sanitize_key((string) $record_type);
+
+        if ($record_type === 'aggregate') {
+            return [
+                'basis' => 'aggregate_period_timezone_unverified',
+                'source_representation' => 'date_bounded_aggregate_or_period',
+                'absolute_time_comparable' => false,
+                'reason' => 'The adapter imports an aggregate period, but its exact calendar semantics, source timezone, and historical site-timezone setting are not persisted here.',
+            ];
+        }
+
+        if ($record_type === 'event' && $adapter_key === 'burst_statistics') {
+            return [
+                'basis' => 'wordpress_site_local_timezone_unrecorded',
+                'source_representation' => 'unix_timestamp_converted_with_wp_date',
+                'absolute_time_comparable' => false,
+                'reason' => 'The source instant is known, but the WordPress timezone identifier/offset at import time is not persisted with the event.',
+            ];
+        }
+
+        if ($record_type === 'event' && $adapter_key === 'independent_analytics') {
+            return [
+                'basis' => 'wordpress_site_local_timezone_unrecorded',
+                'source_representation' => 'utc_timestamp_converted_to_wp_local_with_wp_date',
+                'absolute_time_comparable' => false,
+                'reason' => 'The source is UTC and is converted to WordPress local time, but the conversion timezone identifier/offset is not persisted with the event.',
+            ];
+        }
+
+        if ($record_type === 'event' && $adapter_key === 'pulseviews' && $origin_key === 'recent_raw_views') {
+            return [
+                'basis' => 'source_local_timezone_unknown',
+                'source_representation' => 'naive_sql_datetime',
+                'absolute_time_comparable' => false,
+                'reason' => 'The raw source datetime has no documented timezone or UTC offset.',
+            ];
+        }
+
+        return [
+            'basis' => 'unknown',
+            'source_representation' => 'unverified',
+            'absolute_time_comparable' => false,
+            'reason' => 'The adapter does not provide sufficient persisted timezone provenance for absolute-time comparison.',
+        ];
+    }
+
+    private function classify_reconciliation_temporal_granularity($record_type, $period_start, $period_end, $precision_hint = 'unknown') {
+        if (!$this->is_valid_reconciliation_period_range($period_start, $period_end)) {
+            return [
+                'granularity' => 'unknown',
+                'classification' => 'insufficient_or_invalid_temporal_bounds',
+                'comparable_at_same_granularity' => false,
+            ];
+        }
+        if ($precision_hint === 'calendar_day'
+            || (substr($period_start, 11) === '00:00:00' && substr($period_end, 11) === '23:59:59')) {
+            return [
+                'granularity' => 'calendar_day',
+                'classification' => 'day_level_interval',
+                'comparable_at_same_granularity' => true,
+            ];
+        }
+        if ($record_type === 'aggregate') {
+            return [
+                'granularity' => 'aggregate_period',
+                'classification' => 'aggregate_interval',
+                'comparable_at_same_granularity' => true,
+            ];
+        }
+        if ($record_type === 'event' && $period_start === $period_end) {
+            return [
+                'granularity' => 'point_timestamp',
+                'classification' => 'event_timestamp_unverified',
+                'comparable_at_same_granularity' => true,
+            ];
+        }
+        return [
+            'granularity' => 'unknown',
+            'classification' => 'unrecognized_temporal_shape',
+            'comparable_at_same_granularity' => false,
+        ];
+    }
+
+    /**
+     * Accept only canonical local SQL datetime values for reconciliation periods.
+     * This validates representation, not timezone equivalence or event identity.
+     */
+    private function is_valid_reconciliation_period_datetime($value) {
+        if (!is_string($value) || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $value)) {
+            return false;
+        }
+        $parsed = DateTime::createFromFormat('!Y-m-d H:i:s', $value);
+        $errors = DateTime::getLastErrors();
+        return $parsed instanceof DateTime
+            && $parsed->format('Y-m-d H:i:s') === $value
+            && ($errors === false || (empty($errors['warning_count']) && empty($errors['error_count'])));
+    }
+
+    /**
+     * Validate chronological ordering when both period boundaries are known.
+     * Canonical local SQL datetimes can be compared lexically; this does not
+     * infer timezone equivalence or prove event identity.
+     */
+    private function is_valid_reconciliation_period_range($period_start, $period_end) {
+        if (!$this->is_valid_reconciliation_period_datetime($period_start)
+            || !$this->is_valid_reconciliation_period_datetime($period_end)) {
+            return null;
+        }
+        return strcmp($period_end, $period_start) >= 0;
+    }
+
+    private function build_generic_adapter_dimension_evidence_consistency($conflict_assessment, $adapter_overlap_evidence) {
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $adapter_overlap_evidence = is_array($adapter_overlap_evidence) ? $adapter_overlap_evidence : [];
+        $expected = [];
+        foreach ((array) ($conflict_assessment['candidates'] ?? []) as $candidate) {
+            if (!is_array($candidate) || empty($candidate['candidate_event_id'])) { continue; }
+            $expected[absint($candidate['candidate_event_id'])] = (array) ($candidate['dimension_checks'] ?? []);
+        }
+        $seen = [];
+        $missing = [];
+        $unexpected = [];
+        $mismatched = [];
+        $incomplete = [];
+        $invalid_period_ranges = [];
+        $dimensions = ['product_id', 'record_type', 'observed_views', 'period_start', 'period_end'];
+        foreach ($adapter_overlap_evidence as $entry) {
+            if (!is_array($entry) || empty($entry['candidate_event_id'])) { $incomplete[] = 'missing_candidate_event_id'; continue; }
+            $id = absint($entry['candidate_event_id']);
+            if (isset($seen[$id])) { $mismatched[] = $id; }
+            $seen[$id] = true;
+            if (!array_key_exists($id, $expected)) { $unexpected[] = $id; continue; }
+            $incoming = $entry['comparison']['incoming'] ?? null;
+            $candidate = $entry['comparison']['candidate'] ?? null;
+            if (!is_array($incoming) || !is_array($candidate)) { $incomplete[] = $id; continue; }
+            $actual = [];
+            foreach ($dimensions as $dimension) {
+                if (!array_key_exists($dimension, $incoming) || !array_key_exists($dimension, $candidate)) {
+                    $actual[$dimension] = null;
+                    continue;
+                }
+                if ($dimension === 'product_id' || $dimension === 'observed_views') {
+                    $left_value = $incoming[$dimension];
+                    $right_value = $candidate[$dimension];
+                    if ($left_value === null || $right_value === null || $left_value === '' || $right_value === ''
+                        || !is_numeric($left_value) || !is_numeric($right_value)) {
+                        $actual[$dimension] = null;
+                        $incomplete[] = $id . ':' . $dimension;
+                    } else {
+                        $left_number = (float) $left_value;
+                        $right_number = (float) $right_value;
+                        if ($left_number < 0 || $right_number < 0
+                            || ($dimension === 'product_id' && ($left_number <= 0 || $right_number <= 0))) {
+                            $actual[$dimension] = null;
+                            $incomplete[] = $id . ':' . $dimension;
+                        } else {
+                            $actual[$dimension] = $left_number === $right_number;
+                        }
+                    }
+                } elseif ($dimension === 'record_type') {
+                    $left = is_scalar($incoming[$dimension]) ? (string) $incoming[$dimension] : '';
+                    $right = is_scalar($candidate[$dimension]) ? (string) $candidate[$dimension] : '';
+                    $actual[$dimension] = ($left !== '' && $right !== '') ? $left === $right : null;
+                    if ($actual[$dimension] === null) { $incomplete[] = $id . ':' . $dimension; }
+                } else {
+                    $left = $incoming[$dimension];
+                    $right = $candidate[$dimension];
+                    if (!$this->is_valid_reconciliation_period_datetime($left)
+                        || !$this->is_valid_reconciliation_period_datetime($right)) {
+                        $actual[$dimension] = null;
+                        $incomplete[] = $id . ':' . $dimension;
+                    } else {
+                        $actual[$dimension] = $left === $right;
+                    }
+                }
+            }
+            foreach (['incoming' => $incoming, 'candidate' => $candidate] as $side => $period_data) {
+                $range_valid = $this->is_valid_reconciliation_period_range(
+                    $period_data['period_start'] ?? null,
+                    $period_data['period_end'] ?? null
+                );
+                if ($range_valid === false) {
+                    $invalid_period_ranges[] = $id . ':' . $side;
+                    $mismatched[] = $id;
+                } elseif ($range_valid === null) {
+                    // Boundary validity is already reported per dimension above.
+                    // Do not turn unknown boundaries into an ordering conclusion.
+                }
+            }
+            $expected_checks = $expected[$id];
+            foreach ($dimensions as $dimension) {
+                if (!array_key_exists($dimension, $expected_checks) || $expected_checks[$dimension] !== $actual[$dimension]) {
+                    $mismatched[] = $id;
+                    break;
+                }
+            }
+        }
+        $missing = array_values(array_diff(array_keys($expected), array_keys($seen)));
+        $errors = [];
+        if ($missing) { $errors[] = 'adapter_dimension_evidence_missing_candidates'; }
+        if ($unexpected) { $errors[] = 'adapter_dimension_evidence_has_unexpected_candidates'; }
+        if ($mismatched) { $errors[] = 'adapter_dimension_checks_disagree_with_conflict_assessment'; }
+        if ($incomplete) { $errors[] = 'adapter_dimension_evidence_incomplete'; }
+        if ($invalid_period_ranges) { $errors[] = 'adapter_period_range_end_precedes_start'; }
+        return [
+            'status' => $errors ? 'adapter_dimension_evidence_requires_review' : 'adapter_dimension_evidence_consistent',
+            'consistent' => !$errors,
+            'errors' => $errors,
+            'candidate_count_expected' => count($expected),
+            'candidate_count_observed' => count($seen),
+            'missing_candidate_event_ids' => $missing,
+            'unexpected_candidate_event_ids' => array_values(array_unique($unexpected)),
+            'mismatched_candidate_event_ids' => array_values(array_unique($mismatched)),
+            'incomplete_candidate_records' => array_values(array_unique($incomplete, SORT_REGULAR)),
+            'invalid_period_ranges' => array_values(array_unique($invalid_period_ranges)),
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Adapter dimension evidence must reproduce the independently recorded comparison checks. Missing dimensions remain unknown; reversed known period boundaries require review. Consistency validates audit integrity only and never proves shared event identity.',
+        ];
+    }
+
+    /**
+     * Validate the complete candidate reconciliation audit chain, including the
+     * independent candidate ordering checks. This is diagnostic only and cannot
+     * promote evidence to identity proof or change any applied contribution.
+     */
+    private function build_generic_candidate_reconciliation_chain_assessment($candidate_set_assessment, $conflict_assessment, $evidence_decision, $audit_consistency, $candidate_consistency, $reference_consistency = [], $discovery_signal_consistency = []) {
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $evidence_decision = is_array($evidence_decision) ? $evidence_decision : [];
+        $audit_consistency = is_array($audit_consistency) ? $audit_consistency : [];
+        $candidate_consistency = is_array($candidate_consistency) ? $candidate_consistency : [];
+        $reference_consistency = is_array($reference_consistency) ? $reference_consistency : [];
+        $discovery_signal_consistency = is_array($discovery_signal_consistency) ? $discovery_signal_consistency : [];
+        $errors = [];
+
+        $inventory_count = max(0, (int) ($candidate_set_assessment['candidate_count_retained'] ?? 0));
+        $conflict_count = max(0, (int) ($conflict_assessment['candidate_count'] ?? 0));
+        $decision_count = max(0, (int) ($evidence_decision['candidate_count'] ?? 0));
+        $ordering_count = max(0, (int) ($candidate_consistency['candidate_count'] ?? 0));
+        $adapter_count = max(0, (int) ($candidate_consistency['adapter_evidence_candidate_count'] ?? 0));
+
+        if (count(array_unique([$inventory_count, $conflict_count, $decision_count, $ordering_count])) > 1) {
+            $errors[] = 'candidate_inventory_conflict_decision_and_ordering_counts_disagree';
+        }
+        if (!empty($candidate_consistency['adapter_evidence_order_consistent']) && $adapter_count !== $ordering_count) {
+            $errors[] = 'adapter_evidence_count_disagrees_despite_order_consistency_claim';
+        }
+        if (!empty($candidate_consistency['primary_in_candidate_list']) === false) {
+            $errors[] = 'primary_candidate_missing_from_candidate_list';
+        }
+        if (!empty($candidate_consistency['adapter_evidence_primary_consistent']) === false) {
+            $errors[] = 'adapter_evidence_primary_candidate_inconsistent';
+        }
+        if (!empty($candidate_consistency['adapter_evidence_order_consistent']) === false) {
+            $errors[] = 'adapter_evidence_candidate_order_inconsistent';
+        }
+        if (array_key_exists('adapter_discovery_evidence_consistent', $candidate_consistency)
+            && empty($candidate_consistency['adapter_discovery_evidence_consistent'])) {
+            $errors[] = 'adapter_discovery_evidence_provenance_inconsistent';
+        }
+        if (array_key_exists('adapter_dimension_evidence_consistent', $candidate_consistency)
+            && empty($candidate_consistency['adapter_dimension_evidence_consistent'])) {
+            $errors[] = 'adapter_dimension_evidence_inconsistent_with_conflict_assessment';
+        }
+        if (empty($audit_consistency['consistent'])) {
+            $errors[] = 'underlying_candidate_audit_layers_are_inconsistent';
+        }
+        if (array_key_exists('consistent', $reference_consistency) && empty($reference_consistency['consistent'])) {
+            $errors[] = 'candidate_event_or_source_references_are_inconsistent';
+        }
+        if (array_key_exists('consistent', $discovery_signal_consistency) && empty($discovery_signal_consistency['consistent'])) {
+            $errors[] = 'candidate_discovery_signal_provenance_is_inconsistent';
+        }
+        if (array_key_exists('classification_coverage_complete', $audit_consistency)
+            && empty($audit_consistency['classification_coverage_complete'])) {
+            $errors[] = 'candidate_classification_coverage_incomplete_in_chain';
+        }
+        if (!empty($candidate_set_assessment['candidate_set_truncated']) && empty($evidence_decision['candidate_search_truncated'])) {
+            $errors[] = 'truncation_missing_from_final_candidate_decision';
+        }
+        if (!empty($evidence_decision['identity_proven']) || !empty($candidate_consistency['identity_proven'])) {
+            $errors[] = 'candidate_reconciliation_chain_claims_identity_proof';
+        }
+        if (!empty($evidence_decision['automatic_suppression_authorized']) || !empty($candidate_consistency['automatic_suppression_authorized'])) {
+            $errors[] = 'candidate_reconciliation_chain_authorizes_automatic_suppression';
+        }
+
+        return [
+            'status' => $errors ? 'reconciliation_chain_requires_review' : 'reconciliation_chain_consistent',
+            'consistent' => !$errors,
+            'errors' => array_values(array_unique($errors)),
+            'candidate_counts' => [
+                'inventory' => $inventory_count,
+                'conflict_assessment' => $conflict_count,
+                'evidence_decision' => $decision_count,
+                'candidate_ordering' => $ordering_count,
+                'adapter_evidence' => $adapter_count,
+            ],
+            'candidate_search_truncated' => !empty($evidence_decision['candidate_search_truncated']),
+            'classification_coverage_complete' => !empty($audit_consistency['classification_coverage_complete']),
+            'classified_candidate_count' => max(0, (int) ($audit_consistency['classified_candidate_count'] ?? 0)),
+            'unclassified_candidate_count' => max(0, (int) ($audit_consistency['unclassified_candidate_count'] ?? 0)),
+            'candidate_reference_consistency' => $reference_consistency,
+            'candidate_discovery_signal_consistency' => $discovery_signal_consistency,
+            'adapter_discovery_evidence_consistent' => !empty($candidate_consistency['adapter_discovery_evidence_consistent']),
+            'adapter_dimension_evidence_consistent' => !empty($candidate_consistency['adapter_dimension_evidence_consistent']),
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'This end-to-end check validates audit-chain consistency only. Any inconsistency requires review; no result changes applied_views, totals, or count suppression.',
+        ];
+    }
+
+    private function build_generic_product_reconciliation_summary($product_id, $cross_source, $partial_overlap, $product_synthesis, $matched_event = null, $candidate_set = null) {
+        $cross_source = is_array($cross_source) ? $cross_source : [];
+        $partial_overlap = is_array($partial_overlap) ? $partial_overlap : [];
+        $product_synthesis = is_array($product_synthesis) ? $product_synthesis : [];
+        $candidate_set = is_array($candidate_set) ? $candidate_set : [];
+        $candidate_set_assessment = $this->build_generic_candidate_set_assessment(
+            $candidate_set['candidates'] ?? [],
+            !empty($candidate_set['truncated']),
+            $candidate_set['observed_count'] ?? null
+        );
+
+        $capability_status = sanitize_key((string) ($product_synthesis['capability_profile_status'] ?? 'unknown'));
+        $synthesis_status = sanitize_key((string) ($product_synthesis['status'] ?? 'unknown'));
+        $partial_status = sanitize_key((string) ($partial_overlap['status'] ?? 'unknown'));
+        $cross_truncated = !empty($cross_source['candidate_set_truncated']);
+        $inventory_truncated = !empty($product_synthesis['source_record_groups_truncated']);
+        $partial_truncated = !empty($partial_overlap['records_truncated']);
+
+        $limitations = [];
+        if ($synthesis_status !== 'available') { $limitations[] = 'product_source_synthesis_' . ($synthesis_status ?: 'unknown'); }
+        if (!in_array($capability_status, ['available'], true)) { $limitations[] = 'source_capability_profiles_' . ($capability_status ?: 'unknown'); }
+        if ($cross_truncated) { $limitations[] = 'cross_source_candidate_set_truncated'; }
+        if ($inventory_truncated) { $limitations[] = 'product_source_record_groups_truncated'; }
+        if ($partial_status !== 'ok') { $limitations[] = 'partial_overlap_' . ($partial_status ?: 'unknown'); }
+        if ($partial_truncated) { $limitations[] = 'partial_overlap_records_truncated'; }
+
+        $source_count = max(0, (int) ($product_synthesis['source_count_in_scope'] ?? 0));
+        $capability_count = max(0, (int) ($product_synthesis['capability_profile_source_count'] ?? 0));
+        $complete = !$limitations && $source_count === $capability_count;
+
+        // Classify the available evidence without making a new counting decision.
+        // The exact-match flag is supplied only by the importer's existing path,
+        // which has already validated the shared fingerprint and normalized dimensions.
+        $candidate_records = max(0, (int) ($cross_source['candidate_record_count'] ?? 0));
+        $candidate_sources = max(0, (int) ($cross_source['candidate_source_count'] ?? 0));
+        if (is_array($matched_event) && !empty($matched_event['id'])) {
+            $decision_classification = 'confirmed_exact_shared_fingerprint_match';
+            $decision_basis = 'existing_importer_exact_match_contract';
+            $decision_identity_proven = true;
+        } elseif (!empty($candidate_set_assessment['multiple_candidate_ambiguity'])) {
+            $decision_classification = 'multiple_cross_source_candidates_require_review';
+            $decision_basis = 'all_candidates_retained_without_identity_resolution';
+            $decision_identity_proven = false;
+        } elseif ($candidate_records > 0 || $candidate_sources > 0) {
+            $decision_classification = 'possible_cross_source_overlap_requires_review';
+            $decision_basis = 'candidate_fingerprint_or_temporal_evidence_only';
+            $decision_identity_proven = false;
+        } else {
+            $decision_classification = 'insufficient_evidence_to_establish_cross_source_overlap';
+            $decision_basis = 'no_candidate_found_within_declared_search_bounds';
+            $decision_identity_proven = false;
+        }
+
+        return [
+            'version' => '1.0.0',
+            'status' => $complete ? 'evidence_inventory_complete_within_declared_bounds' : 'evidence_inventory_partial_or_limited',
+            'product_id' => absint($product_id),
+            'source_scope' => 'all_persisted_generic_sources_for_product',
+            'source_count' => $source_count,
+            'capability_profile_source_count' => $capability_count,
+            'cross_source_candidate_count' => max(0, (int) ($cross_source['candidate_source_count'] ?? 0)),
+            'partial_overlap_source_count' => count((array) ($partial_overlap['profiles'] ?? [])),
+            'same_bucket_count_bounds' => $cross_source['identical_bucket_count_range'] ?? ['status' => 'unavailable'],
+            'reconciliation_decision' => [
+                'classification' => $decision_classification,
+                'basis' => $decision_basis,
+                'identity_proven' => $decision_identity_proven,
+                'summary_authorizes_count_change' => false,
+                'candidate_search_truncated' => $cross_truncated,
+                'candidate_set_assessment' => $candidate_set_assessment,
+                'policy' => 'This classification describes evidence only. It does not independently authorize suppression, adjustment, or rewriting of applied_views.',
+            ],
+            'unique_view_total' => null,
+            'counting_decision' => 'preserve_all_applied_contributions_no_automatic_suppression',
+            'limitations' => array_values(array_unique($limitations)),
+            'interpretation' => 'This summary combines source inventory, declared capabilities, candidate overlap evidence, and the availability limits of partial-period comparison. It does not prove event identity or calculate a deduplicated unique-view total.',
+        ];
+    }
+
+    /**
+     * Partial aggregate-period duration comparisons are withheld until source
+     * timezone provenance is persisted. Naive datetime strings cannot safely be
+     * converted into shared elapsed-time intervals.
+     */
+    private function build_generic_partial_overlap_profiles($product_id, $source_id, $period_start, $period_end) {
+        // Persisted period strings do not include source timezone provenance.
+        // Do not report elapsed seconds or coverage ratios from naive datetimes.
+        return [
+            'status' => 'unavailable',
+            'reason' => 'timezone_basis_not_persisted',
+            'incoming_period_seconds' => null,
+            'profiles' => [],
+            'records_truncated' => false,
+            'identity_confidence' => 'unproven_without_shared_event_identity',
+            'temporal_comparison' => 'not_performed',
+        ];
+    }
+
+    /** Execute the importer while the caller holds the source-origin advisory lock. */
+    private function process_generic_historical_view_import_batch($source_id, $origin_key, $retry_checkpoint_override = null, $origin_lock = null) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = sanitize_key((string) $origin_key);
+        if (!$source_id || $origin_key === '') {
+            return ['status' => 'invalid_input'];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'origin_lock_session_lost'];
+        }
+
+        $state = $this->get_view_source_origin_state($source_id, $origin_key);
+        if (empty($state['status']) || $state['status'] !== 'found') {
+            return ['status' => 'origin_not_found'];
+        }
+        // A queued action may outlive a provider's latest discovery inventory.
+        // Never let such a stale action process an origin that has since been
+        // marked unavailable or is no longer explicitly detected as available.
+        if ($state['origin_status'] === 'unavailable' || $state['detection_status'] !== 'available') {
+            return ['status' => 'origin_unavailable'];
+        }
+        if ($state['origin_status'] === 'completed' && $retry_checkpoint_override === null) {
+            return ['status' => 'already_completed'];
+        }
+        // A terminal failure for one record must not stop the main source scan.
+        // The failed record remains in the ledger for review, while later records
+        // continue importing. Only the independent retry worker is capped at three
+        // total attempts for that individual record.
+        if (!is_array($state['snapshot']) || empty($state['snapshot']['boundary']) || !is_array($state['checkpoint'])) {
+            return ['status' => 'snapshot_not_ready'];
+        }
+
+        $adapter_key = isset($state['adapter_key']) ? sanitize_key($state['adapter_key']) : '';
+        $adapter = $this->get_historical_view_adapter($adapter_key);
+        if (!$adapter) {
+            // A scheduled request may have arrived before provider registration.
+            $this->discover_historical_view_adapters();
+            $adapter = $this->get_historical_view_adapter($adapter_key);
+        }
+        if (!$adapter) {
+            // Provider plugins may be temporarily inactive, load later than this
+            // worker, or briefly fail while assembling their registry. Keep the
+            // immutable snapshot/checkpoint untouched and retry discovery later.
+            // Normal plugin initialization also rediscovers providers, so a
+            // returning adapter can resume automatically without administrator
+            // intervention. A replacement adapter still cannot reinterpret the
+            // persisted identity because register_view_source_origin() guards it.
+            $this->update_view_source_origin_state($source_id, $origin_key, [
+                'last_error' => 'The registered historical adapter is temporarily unavailable; automatic discovery will be retried.',
+            ], $origin_lock);
+            $this->schedule_generic_historical_view_import_batch(21600, $source_id, $origin_key);
+            return ['status' => 'adapter_unavailable', 'retry_scheduled' => true];
+        }
+
+        $checkpoint = ($retry_checkpoint_override !== null && is_array($retry_checkpoint_override))
+            ? $retry_checkpoint_override
+            : $state['checkpoint'];
+        $batch_start_checkpoint = $checkpoint;
+        try {
+            $batch = $adapter->get_product_view_batch($origin_key, $checkpoint, $state['snapshot'], 100);
+        } catch (Throwable $exception) {
+            $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin_key,
+                    'batch:' . substr(hash('sha256', wp_json_encode($checkpoint)), 0, 32),
+                    0,
+                    $exception->getMessage(),
+                    null,
+                    8,
+                    $origin_lock);
+            if (!$failure['blocked']) {
+                $this->schedule_generic_historical_view_import_batch($failure['retry_delay'], $source_id, $origin_key);
+            }
+            return ['status' => $failure['blocked'] ? 'needs_attention' : 'source_read_failed', 'attempts' => $failure['attempts']];
+        }
+
+        $batch_rows_are_valid_list = is_array($batch)
+            && isset($batch['rows'])
+            && is_array($batch['rows'])
+            && array_keys($batch['rows']) === (count($batch['rows']) > 0 ? range(0, count($batch['rows']) - 1) : [])
+            && count($batch['rows']) <= 100;
+        if ($batch_rows_are_valid_list) {
+            foreach ($batch['rows'] as $batch_row) {
+                if (!is_array($batch_row)) {
+                    $batch_rows_are_valid_list = false;
+                    break;
+                }
+            }
+        }
+
+        $batch_is_valid = is_array($batch)
+            && $batch_rows_are_valid_list
+            && array_key_exists('has_more', $batch)
+            && is_bool($batch['has_more'])
+            // The adapter must apply the immutable snapshot boundary in its source query.
+            && isset($batch['boundary_applied'])
+            && $batch['boundary_applied'] === true;
+
+        if ($batch_is_valid && $batch['has_more']) {
+            $batch_is_valid = !empty($batch['rows'])
+                && array_key_exists('next_checkpoint', $batch)
+                && (is_array($batch['next_checkpoint']) || is_scalar($batch['next_checkpoint']))
+                && $this->is_valid_generic_historical_cursor($batch['next_checkpoint'])
+                && wp_json_encode($batch['next_checkpoint']) !== wp_json_encode($checkpoint);
+        }
+
+        if (!$batch_is_valid) {
+            $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin_key,
+                    'batch:' . substr(hash('sha256', wp_json_encode($checkpoint)), 0, 32),
+                    0,
+                    'Adapter returned an invalid or non-progressing batch. Expected a sequential list of at most 100 array rows, a boolean has_more, boundary_applied=true, and an advancing next_checkpoint whenever more rows remain.',
+                    null,
+                    8,
+                    $origin_lock);
+            if (!$failure['blocked']) {
+                $this->schedule_generic_historical_view_import_batch($failure['retry_delay'], $source_id, $origin_key);
+            }
+            return ['status' => $failure['blocked'] ? 'needs_attention' : 'invalid_batch', 'attempts' => $failure['attempts']];
+        }
+
+        // The source has now returned a structurally valid, snapshot-bounded batch;
+        // clear a previous transient batch-read failure before processing its records.
+        $batch_failure_cleared = $this->clear_generic_historical_view_failure(
+            $source_id,
+            $origin_key,
+            'batch:' . substr(hash('sha256', wp_json_encode($checkpoint)), 0, 32)
+        , $origin_lock);
+        if (!$batch_failure_cleared) {
+            // Do not consume this batch while its previous batch-level failure
+            // remains unresolved in the durable ledger.
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'failure_ledger_clear_failed'];
+        }
+
+        $processed = 0;
+        $duplicates = 0;
+        $failed = 0;
+        $skipped = 0;
+        $next_checkpoint = $checkpoint;
+
+        $checkpoint_persistence_failed = false;
+        foreach ($batch['rows'] as $record) {
+            try {
+                $normalized = $adapter->normalize_record($origin_key, $record);
+            } catch (Throwable $exception) {
+                $normalized = null;
+                $normalization_error = $exception->getMessage();
+            }
+
+            // A replay of a saved batch must retry only records whose own retry
+            // deadline has arrived. Otherwise one due record could cause blocked
+            // or not-yet-due neighbours in the same batch to be retried indefinitely.
+            if ($retry_checkpoint_override !== null) {
+                if (is_array($normalized)) {
+                    $retry_record_key = !empty($normalized['source_record_key'])
+                        ? (string) $normalized['source_record_key']
+                        : wp_json_encode($record);
+                } elseif (is_array($record) && isset($record['source_record_key'])) {
+                    $retry_record_key = (string) $record['source_record_key'];
+                } else {
+                    $retry_record_key = wp_json_encode($record);
+                }
+                $retry_record_key = substr((string) $retry_record_key, 0, 191);
+                $retry_record_hash = hash('sha256', (string) $origin_key . "\0" . $retry_record_key);
+                $retry_is_due = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT id FROM {$this->view_source_failures_table}
+                     WHERE source_id = %d AND source_record_hash = %s
+                       AND status = 'retry' AND next_retry_at <= %s
+                     LIMIT 1",
+                    $source_id,
+                    $retry_record_hash,
+                    current_time('mysql')
+                ));
+                if (!empty($wpdb->last_error)) {
+                    $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                    return ['status' => 'retry_ledger_lookup_failed', 'processed' => $processed, 'duplicates' => $duplicates];
+                }
+                if (!$retry_is_due) {
+                    continue;
+                }
+            }
+
+            if (is_array($normalized) && !empty($normalized['skip'])) {
+                // Adapters may explicitly identify a source row as outside their
+                // product-view scope (for example, a site-wide analytics row for
+                // a blog page). Such rows are not failures and must not block the
+                // scan, but their source key and cursor still require validation.
+                $skip_record_key = isset($normalized['source_record_key'])
+                    ? trim((string) $normalized['source_record_key']) : '';
+                $skip_cursor = array_key_exists('cursor', $normalized) ? $normalized['cursor'] : null;
+                if ($skip_record_key === '' || strlen($skip_record_key) > 191
+                    || !$this->is_valid_generic_historical_cursor($skip_cursor)) {
+                    $normalized = null;
+                    $normalization_error = 'Adapter returned an invalid explicit skip record.';
+                } else {
+                    $skip_failure_cleared = $this->clear_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $skip_record_key
+                    , $origin_lock, null);
+                    if (!$skip_failure_cleared) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    $next_checkpoint['cursor'] = $skip_cursor;
+                    $skipped++;
+                    continue;
+                }
+            }
+
+            if (!is_array($normalized)) {
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure(
+                    $source_id,
+                    $origin_key,
+                    (is_array($record) && isset($record['source_record_key'])) ? $record['source_record_key'] : wp_json_encode($record),
+                    0,
+                    isset($normalization_error) ? $normalization_error : 'Adapter could not normalize a source record.',
+                    $batch_start_checkpoint,
+                    3
+                , $origin_lock);
+                if (empty($failure['persisted'])) {
+                    // Without a durable failure-ledger entry, do not advance past this record.
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    $checkpoint_persistence_failed = true;
+                    break;
+                }
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                }
+                unset($normalization_error);
+                continue;
+            }
+
+            $product_id = isset($normalized['product_id']) ? absint($normalized['product_id']) : 0;
+            $record_key = isset($normalized['source_record_key']) ? trim((string) $normalized['source_record_key']) : '';
+            $raw_views = array_key_exists('views', $normalized) ? $normalized['views'] : null;
+            $views_is_valid = is_int($raw_views) && $raw_views >= 0;
+            if (is_string($raw_views) && preg_match('/^(0|[1-9]\d*)$/D', $raw_views)) {
+                // Do not compare large decimal strings through float: on 64-bit PHP,
+                // (float) PHP_INT_MAX rounds to 2^63 and can admit an overflowing value.
+                $max_views_string = (string) PHP_INT_MAX;
+                $raw_views_length = strlen($raw_views);
+                $max_views_length = strlen($max_views_string);
+                $views_is_valid = $raw_views_length < $max_views_length
+                    || ($raw_views_length === $max_views_length && strcmp($raw_views, $max_views_string) <= 0);
+            }
+            $views = $views_is_valid ? (int) $raw_views : -1;
+            $cursor = array_key_exists('cursor', $normalized) ? $normalized['cursor'] : null;
+            $record_type = isset($normalized['record_type']) ? sanitize_key($normalized['record_type']) : 'event';
+            $period_start = array_key_exists('period_start', $normalized) && $normalized['period_start'] !== null
+                ? (string) $normalized['period_start'] : null;
+            $period_end = array_key_exists('period_end', $normalized) && $normalized['period_end'] !== null
+                ? (string) $normalized['period_end'] : null;
+            $periods_are_valid = $this->is_valid_generic_historical_datetime($period_start)
+                && $this->is_valid_generic_historical_datetime($period_end);
+            if ($periods_are_valid && $period_start !== null && $period_end !== null) {
+                $periods_are_valid = strcmp($period_start, $period_end) <= 0;
+            }
+
+            if (
+                !$product_id || get_post_type($product_id) !== 'product'
+                || $record_key === '' || strlen($record_key) > 191
+                || !$views_is_valid || $views < 0 || !in_array($record_type, ['event', 'aggregate'], true)
+                || !$this->is_valid_generic_historical_cursor($cursor)
+                || !$periods_are_valid
+                || ($record_type === 'aggregate' && ($period_start === null || $period_end === null))
+            ) {
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure(
+                    $source_id,
+                    $origin_key,
+                    $record_key !== '' ? $record_key : wp_json_encode($record),
+                    $product_id,
+                    'Normalized record failed validation (product, key, views, type or cursor).',
+                    $batch_start_checkpoint,
+                    3
+                , $origin_lock);
+                if (empty($failure['persisted'])) {
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    $checkpoint_persistence_failed = true;
+                    break;
+                }
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                }
+                unset($normalization_error);
+                continue;
+            }
+
+            $record_hash = hash('sha256', $origin_key . "\0" . $record_key);
+            $now = current_time('mysql');
+            $source_fingerprint = isset($normalized['source_fingerprint'])
+                ? strtolower(trim((string) $normalized['source_fingerprint']))
+                : '';
+            if ($source_fingerprint !== '' && !preg_match('/^[a-f0-9]{64}$/D', $source_fingerprint)) {
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure(
+                    $source_id,
+                    $origin_key,
+                    $record_key,
+                    $product_id,
+                    'Adapter supplied an invalid cross-source fingerprint; expected exactly 64 hexadecimal characters.',
+                    $batch_start_checkpoint,
+                    3
+                , $origin_lock);
+                if (empty($failure['persisted'])) {
+                    // Without a durable failure-ledger entry, do not advance past this record.
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    $checkpoint_persistence_failed = true;
+                    break;
+                }
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                }
+                continue;
+            }
+
+            // Cross-plugin reconciliation is deliberately conservative: suppress a
+            // second contribution only when both adapters provide the same explicit
+            // stable fingerprint AND all normalized event dimensions agree exactly.
+            // A fingerprint-scoped advisory lock also serializes the no-existing-row
+            // case, which SELECT ... FOR UPDATE alone cannot reliably protect.
+            $reconciliation_lock = 'statpl_xr_' . substr(hash('sha256', $wpdb->prefix . ':' . $source_fingerprint), 0, 48);
+            $reconciliation_lock_state = null;
+            // Aggregate fingerprints derived from product/date/count are not shared
+            // event identities. They must never drive exact cross-source suppression.
+            // Keep exact fingerprint reconciliation restricted to individual events.
+            $has_exact_event_fingerprint = $source_fingerprint !== '' && $record_type === 'event';
+            if ($has_exact_event_fingerprint) {
+                $reconciliation_lock_state = $this->acquire_generic_advisory_lock($reconciliation_lock);
+                if (empty($reconciliation_lock_state['acquired'])) {
+                    $this->schedule_generic_historical_view_import_batch(30, $source_id, $origin_key);
+                    return ['status' => 'cross_source_lock_busy', 'processed' => $processed, 'duplicates' => $duplicates];
+                }
+                if (!$this->generic_advisory_lock_session_is_current($reconciliation_lock_state)) {
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    return ['status' => 'cross_source_lock_session_lost', 'processed' => $processed, 'duplicates' => $duplicates];
+                }
+            }
+
+            $transaction_open = false;
+            try {
+                if (statpl_db_query('START TRANSACTION') === false) {
+                    $failed++;
+                    $transaction_error = (string) $wpdb->last_error;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Could not start atomic source-event transaction: ' . $transaction_error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                    break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                $transaction_open = true;
+                $matched_event = null;
+            $possible_overlap_event = null;
+            $possible_overlap_events = [];
+            $possible_overlap_candidates_truncated = false;
+            $possible_overlap_fingerprint_candidates_observed = 0;
+            $possible_overlap_temporal_candidates_observed = 0;
+            $possible_overlap_candidate_count_observed = 0;
+            $possible_overlap_candidate_count_is_lower_bound = false;
+            $possible_overlap_reason_code = '';
+            if ($has_exact_event_fingerprint) {
+                $matched_event = statpl_db_get_row(statpl_db_prepare(
+                    "SELECT id, source_id, product_id, record_type, observed_views, period_start, period_end, applied_views
+                     FROM {$this->view_source_events_table}
+                     WHERE source_fingerprint = %s
+                       AND source_id <> %d
+                       AND product_id = %d
+                       AND record_type = %s
+                       AND observed_views = %d
+                       AND ((period_start IS NULL AND %s = '') OR period_start = %s)
+                       AND ((period_end IS NULL AND %s = '') OR period_end = %s)
+                     ORDER BY id ASC LIMIT 1 FOR UPDATE",
+                    $source_fingerprint,
+                    $source_id,
+                    $product_id,
+                    $record_type,
+                    $views,
+                    (string) $period_start,
+                    $period_start,
+                    (string) $period_end,
+                    $period_end
+                ), ARRAY_A);
+                if (!empty($wpdb->last_error)) {
+                    $lookup_error = $wpdb->last_error;
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Cross-source reconciliation lookup failed: ' . $lookup_error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                    break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                if (!$matched_event) {
+                    // Same explicit fingerprint with different normalized dimensions is
+                    // evidence of a possible/partial overlap, not proof of a duplicate.
+                    // Preserve and count this contribution, but retain an auditable
+                    // candidate link so a source-specific reconciliation rule can review it.
+                    $fingerprint_candidate_result = $this->get_generic_reconciliation_candidates_by_source(
+                        'fingerprint',
+                        ['fingerprint' => $source_fingerprint, 'source_id' => $source_id],
+                        25
+                    );
+                    $possible_overlap_events = $fingerprint_candidate_result['events'];
+                    $possible_overlap_fingerprint_candidates_observed = (int) $fingerprint_candidate_result['observed'];
+                    if ($fingerprint_candidate_result['status'] === 'error') {
+                        $lookup_error = $fingerprint_candidate_result['error'];
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                        }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id, $origin_key, $record_key, $product_id,
+                            'Possible-overlap reconciliation lookup failed: ' . $lookup_error,
+                            $batch_start_checkpoint, 3, $origin_lock
+                        );
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                            break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                    if (!empty($fingerprint_candidate_result['truncated'])) {
+                        $possible_overlap_candidates_truncated = true;
+                        $possible_overlap_candidate_count_is_lower_bound = true;
+                    }
+                    if (!empty($possible_overlap_events)) {
+                        $possible_overlap_event = $possible_overlap_events[0];
+                        $possible_overlap_reason_code = 'shared_fingerprint_dimension_mismatch';
+                    }
+                    if (!empty($wpdb->last_error)) {
+                        $lookup_error = $wpdb->last_error;
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id,
+                            $origin_key,
+                            $record_key,
+                            $product_id,
+                            'Possible-overlap reconciliation lookup failed: ' . $lookup_error,
+                            $batch_start_checkpoint,
+                            3
+                        , $origin_lock);
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                    break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                }
+            }
+            // Cross-source temporal overlap is retained as evidence only. This
+            // includes aggregate/event, aggregate/aggregate, and event/event pairs.
+            // Event timestamps can reveal strong candidate relationships even when
+            // providers do not share an event ID; temporal proximity alone still does
+            // not prove identity, so this discovery step never suppresses counts.
+            if (
+                !$matched_event
+                && in_array($record_type, ['aggregate', 'event'], true)
+                && $period_start !== null
+                && $period_end !== null
+            ) {
+                $temporal_candidate_result = $this->get_generic_reconciliation_candidates_by_source(
+                    'temporal',
+                    ['source_id' => $source_id, 'product_id' => $product_id, 'period_start' => $period_start, 'period_end' => $period_end],
+                    25
+                );
+                $temporal_overlap_events = $temporal_candidate_result['events'];
+                if ($temporal_candidate_result['status'] === 'error') {
+                    $lookup_error = $temporal_candidate_result['error'];
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id, $origin_key, $record_key, $product_id,
+                        'Cross-source temporal-overlap lookup failed: ' . $lookup_error,
+                        $batch_start_checkpoint, 3, $origin_lock
+                    );
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                if (!empty($wpdb->last_error)) {
+                    $lookup_error = $wpdb->last_error;
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Cross-source temporal-overlap lookup failed: ' . $lookup_error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                $possible_overlap_temporal_candidates_observed = (int) $temporal_candidate_result['observed'];
+                if (!empty($temporal_candidate_result['truncated'])) {
+                    $possible_overlap_candidates_truncated = true;
+                    $possible_overlap_candidate_count_is_lower_bound = true;
+                }
+
+                $candidate_discovery_by_id = [];
+                foreach ($possible_overlap_events as $candidate_event) {
+                    $candidate_id = isset($candidate_event['id']) ? (int) $candidate_event['id'] : 0;
+                    if ($candidate_id > 0) {
+                        $candidate_discovery_by_id[$candidate_id]['fingerprint'] = true;
+                    }
+                }
+                foreach ($temporal_overlap_events as $candidate_event) {
+                    $candidate_id = isset($candidate_event['id']) ? (int) $candidate_event['id'] : 0;
+                    if ($candidate_id > 0) {
+                        $candidate_discovery_by_id[$candidate_id]['temporal'] = true;
+                    }
+                }
+
+                $candidate_events_by_id = [];
+                foreach (array_merge($possible_overlap_events, $temporal_overlap_events) as $candidate_event) {
+                    $candidate_id = isset($candidate_event['id']) ? (int) $candidate_event['id'] : 0;
+                    if ($candidate_id > 0) {
+                        $candidate_event['_discovered_by'] = array_keys($candidate_discovery_by_id[$candidate_id] ?? []);
+                        $candidate_events_by_id[$candidate_id] = $candidate_event;
+                    }
+                }
+                $possible_overlap_events = array_values($candidate_events_by_id);
+                usort($possible_overlap_events, static function ($left, $right) {
+                    $left_sources = isset($left['_discovered_by']) ? $left['_discovered_by'] : [];
+                    $right_sources = isset($right['_discovered_by']) ? $right['_discovered_by'] : [];
+                    $left_rank = count($left_sources) > 1 ? 0 : (in_array('fingerprint', $left_sources, true) ? 1 : 2);
+                    $right_rank = count($right_sources) > 1 ? 0 : (in_array('fingerprint', $right_sources, true) ? 1 : 2);
+                    if ($left_rank !== $right_rank) {
+                        return $left_rank <=> $right_rank;
+                    }
+                    return (int) $left['id'] <=> (int) $right['id'];
+                });
+                $possible_overlap_candidate_count_observed = count($possible_overlap_events);
+                if (count($possible_overlap_events) > 25) {
+                    $possible_overlap_candidates_truncated = true;
+                    $possible_overlap_candidate_count_is_lower_bound = true;
+                    $possible_overlap_events = array_slice($possible_overlap_events, 0, 25);
+                }
+                if (!empty($possible_overlap_events)) {
+                    $possible_overlap_event = $possible_overlap_events[0];
+                }
+                if ($possible_overlap_event) {
+                    $has_fingerprint_candidate = false;
+                    $has_cross_type_candidate = false;
+                    $has_same_type_event_candidate = false;
+                    foreach ($possible_overlap_events as $candidate_event) {
+                        $discovery = isset($candidate_event['_discovered_by']) ? $candidate_event['_discovered_by'] : [];
+                        if (in_array('fingerprint', $discovery, true)) {
+                            $has_fingerprint_candidate = true;
+                        }
+                        if (
+                            in_array('temporal', $discovery, true)
+                            && isset($candidate_event['record_type'])
+                            && $candidate_event['record_type'] !== $record_type
+                        ) {
+                            $has_cross_type_candidate = true;
+                        }
+                        if (
+                            in_array('temporal', $discovery, true)
+                            && $record_type === 'event'
+                            && isset($candidate_event['record_type'])
+                            && $candidate_event['record_type'] === 'event'
+                        ) {
+                            $has_same_type_event_candidate = true;
+                        }
+                    }
+                    if ($has_fingerprint_candidate) {
+                        $possible_overlap_reason_code = 'shared_fingerprint_dimension_mismatch';
+                    } elseif ($has_cross_type_candidate) {
+                        $possible_overlap_reason_code = 'aggregate_event_temporal_overlap';
+                    } elseif ($has_same_type_event_candidate) {
+                        $possible_overlap_reason_code = 'event_timestamp_overlap';
+                    } elseif ($possible_overlap_reason_code === '') {
+                        $possible_overlap_reason_code = 'overlapping_aggregate_periods';
+                    }
+                }
+            }
+
+            if (empty($temporal_overlap_events) && !empty($possible_overlap_events)) {
+                foreach ($possible_overlap_events as &$candidate_event) {
+                    $candidate_event['_discovered_by'] = ['fingerprint'];
+                }
+                unset($candidate_event);
+                $possible_overlap_candidate_count_observed = count($possible_overlap_events);
+                if (!empty($possible_overlap_events)) {
+                    $possible_overlap_event = $possible_overlap_events[0];
+                }
+            }
+
+            // Optional source-specific analysis enriches the audit trail for partial
+            // overlaps. It is deliberately advisory: an adapter cannot silently change
+            // the counting policy or suppress a contribution through this extension.
+            $adapter_overlap_evidence = [];
+            $adapter_evidence_bytes = 0;
+            $adapter_evidence_total_limit = 65536;
+            $adapter_evidence_candidate_limit = 4096;
+            $adapter_evidence_omitted = 0;
+            if (!$matched_event && $possible_overlap_event && method_exists($adapter, 'get_reconciliation_evidence')) {
+                $overlap_candidates = !empty($possible_overlap_events)
+                    ? $possible_overlap_events
+                    : [$possible_overlap_event];
+                foreach ($overlap_candidates as $candidate_event) {
+                    try {
+                        $adapter_evidence = $adapter->get_reconciliation_evidence(
+                            $origin_key,
+                            $normalized,
+                            $candidate_event
+                        );
+                    } catch (Throwable $exception) {
+                        $adapter_evidence = [
+                            'analysis_status' => 'failed',
+                            'error' => substr(sanitize_text_field($exception->getMessage()), 0, 500),
+                        ];
+                    }
+
+                    if (!is_array($adapter_evidence)) {
+                        $adapter_evidence = ['analysis_status' => 'invalid_result'];
+                    }
+                    $encoded_adapter_evidence = wp_json_encode($adapter_evidence);
+                    $candidate_evidence_size = is_string($encoded_adapter_evidence) ? strlen($encoded_adapter_evidence) : 0;
+                    if (!is_string($encoded_adapter_evidence)) {
+                        $adapter_evidence = [
+                            'analysis_status' => 'rejected',
+                            'reason' => 'Evidence was not JSON serializable.',
+                        ];
+                        $candidate_evidence_size = strlen(wp_json_encode($adapter_evidence));
+                    } elseif ($candidate_evidence_size > $adapter_evidence_candidate_limit) {
+                        $adapter_evidence = [
+                            'analysis_status' => 'rejected',
+                            'reason' => 'Evidence exceeded the 4 KiB per-candidate limit.',
+                            'original_bytes' => $candidate_evidence_size,
+                        ];
+                        $candidate_evidence_size = strlen(wp_json_encode($adapter_evidence));
+                    }
+                    if ($adapter_evidence_bytes + $candidate_evidence_size > $adapter_evidence_total_limit) {
+                        $adapter_evidence_omitted++;
+                        $adapter_evidence = [
+                            'analysis_status' => 'omitted_budget',
+                            'reason' => 'The 64 KiB total adapter-evidence budget was reached.',
+                        ];
+                        $candidate_evidence_size = strlen(wp_json_encode($adapter_evidence));
+                    }
+                    $adapter_evidence_bytes += $candidate_evidence_size;
+                    $candidate_start = isset($candidate_event['period_start']) ? (string) $candidate_event['period_start'] : '';
+                    $candidate_end = isset($candidate_event['period_end']) ? (string) $candidate_event['period_end'] : '';
+                    $incoming_start = (string) $period_start;
+                    $incoming_end = (string) $period_end;
+                    $incoming_has_period = $incoming_start !== '' && $incoming_end !== '';
+                    $candidate_has_period = $candidate_start !== '' && $candidate_end !== '';
+                    // Exact string equality remains a representation-level signal;
+                    // it is not a timezone-safe temporal comparison.
+                    $same_start = $incoming_has_period && $candidate_has_period && $incoming_start === $candidate_start;
+                    $same_end = $incoming_has_period && $candidate_has_period && $incoming_end === $candidate_end;
+                    $incoming_temporal_basis = $this->classify_reconciliation_temporal_basis(
+                        $adapter_key,
+                        $origin_key,
+                        $record_type
+                    );
+                    $candidate_adapter_key = isset($candidate_event['candidate_adapter_key'])
+                        ? sanitize_key((string) $candidate_event['candidate_adapter_key']) : '';
+                    $candidate_record_key = isset($candidate_event['source_record_key'])
+                        ? (string) $candidate_event['source_record_key'] : '';
+                    $candidate_origin_key = '';
+                    if ($candidate_adapter_key === 'pulseviews') {
+                        if (strpos($candidate_record_key, 'pulseviews_day_') === 0) {
+                            $candidate_origin_key = 'daily_aggregates';
+                        } elseif (strpos($candidate_record_key, 'pulseviews_view_') === 0) {
+                            $candidate_origin_key = 'recent_raw_views';
+                        }
+                    }
+                    $candidate_temporal_basis = $this->classify_reconciliation_temporal_basis(
+                        $candidate_adapter_key,
+                        $candidate_origin_key,
+                        isset($candidate_event['record_type']) ? $candidate_event['record_type'] : ''
+                    );
+                    $periods_intersect = false;
+                    $temporal_relation = ($incoming_has_period && $candidate_has_period)
+                        ? 'not_compared_timezone_basis_unverified'
+                        : 'insufficient_temporal_data';
+                    $incoming_precision = 'unknown';
+                    if ($record_type === 'aggregate') {
+                        $incoming_precision = 'aggregate_period';
+                    } elseif ($adapter_key === 'statify') {
+                        $incoming_precision = 'calendar_day';
+                    } elseif (in_array($adapter_key, ['burst_statistics', 'independent_analytics'], true)) {
+                        $incoming_precision = 'seconds';
+                    } elseif ($adapter_key === 'pulseviews') {
+                        $incoming_precision = $origin_key === 'daily_aggregates' ? 'calendar_day' : 'seconds';
+                    } elseif ($record_type === 'event' && $incoming_start !== '' && $incoming_start === $incoming_end) {
+                        $incoming_precision = 'source_event_timestamp_unverified';
+                    }
+                    $candidate_precision = (isset($candidate_event['record_type']) && $candidate_event['record_type'] === 'aggregate')
+                        ? 'aggregate_period'
+                        : ((isset($candidate_event['record_type']) && $candidate_event['record_type'] === 'event' && $candidate_start !== '' && $candidate_start === $candidate_end)
+                            ? 'stored_event_timestamp_unverified'
+                            : 'unknown');
+                    $incoming_granularity = $this->classify_reconciliation_temporal_granularity(
+                        (string) $record_type,
+                        $incoming_start,
+                        $incoming_end,
+                        $incoming_precision
+                    );
+                    $candidate_granularity = $this->classify_reconciliation_temporal_granularity(
+                        isset($candidate_event['record_type']) ? (string) $candidate_event['record_type'] : '',
+                        $candidate_start,
+                        $candidate_end,
+                        $candidate_precision
+                    );
+                    $same_temporal_granularity = $incoming_granularity['granularity'] !== 'unknown'
+                        && $incoming_granularity['granularity'] === $candidate_granularity['granularity'];
+                    $temporal_granularity_relation = $same_temporal_granularity
+                        ? 'same_granularity_temporal_evidence_only'
+                        : (($incoming_granularity['granularity'] !== 'unknown' && $candidate_granularity['granularity'] !== 'unknown')
+                            ? 'different_temporal_granularity'
+                            : 'insufficient_temporal_granularity');
+
+                    $candidate_rank = count($adapter_overlap_evidence) + 1;
+                    $adapter_overlap_evidence[] = [
+                        'candidate_event_id' => (int) $candidate_event['id'],
+                        'candidate_rank' => $candidate_rank,
+                        'is_primary_candidate' => $candidate_rank === 1
+                            && (int) $candidate_event['id'] === (int) $possible_overlap_event['id'],
+                        'discovered_by' => isset($candidate_event['_discovered_by']) ? $candidate_event['_discovered_by'] : [],
+                        'adapter_key' => $adapter_key,
+                        'comparison' => [
+                            'identity_assessment' => [
+                                'candidate_discovery_signals' => isset($candidate_event['_discovered_by'])
+                                    ? array_values((array) $candidate_event['_discovered_by'])
+                                    : [],
+                                'same_explicit_fingerprint_signal' => in_array(
+                                    'fingerprint',
+                                    (array) ($candidate_event['_discovered_by'] ?? []),
+                                    true
+                                ) && $source_fingerprint !== '',
+                                'classification' => (
+                                    in_array('fingerprint', (array) ($candidate_event['_discovered_by'] ?? []), true)
+                                    && $source_fingerprint !== ''
+                                ) ? 'shared_fingerprint_candidate_requires_contract_and_dimension_validation' : 'temporal_or_other_candidate_without_shared_identity',
+                                'identity_proven' => false,
+                                'automatic_suppression_authorized' => false,
+                                'reason' => 'Candidate discovery by a matching fingerprint is a review signal only. Identity is confirmed only by the separate exact-match path, which also requires event type and all normalized dimensions to agree.',
+                            ],
+                            'incoming' => [
+                                'source_id' => (int) $source_id,
+                                'origin_key' => (string) $origin_key,
+                                'product_id' => (int) $product_id,
+                                'record_type' => (string) $record_type,
+                                'observed_views' => (int) $views,
+                                'period_start' => $incoming_start,
+                                'period_end' => $incoming_end,
+                                'temporal_basis' => $incoming_temporal_basis,
+                            ],
+                            'candidate' => [
+                                'source_id' => isset($candidate_event['source_id']) ? (int) $candidate_event['source_id'] : 0,
+                                'source_key' => isset($candidate_event['candidate_source_key']) ? (string) $candidate_event['candidate_source_key'] : null,
+                                'adapter_key' => isset($candidate_event['candidate_adapter_key']) ? (string) $candidate_event['candidate_adapter_key'] : null,
+                                'product_id' => isset($candidate_event['product_id']) ? (int) $candidate_event['product_id'] : 0,
+                                'record_type' => isset($candidate_event['record_type']) ? (string) $candidate_event['record_type'] : '',
+                                'observed_views' => isset($candidate_event['observed_views']) ? (int) $candidate_event['observed_views'] : 0,
+                                'applied_views' => isset($candidate_event['applied_views']) ? (int) $candidate_event['applied_views'] : 0,
+                                'period_start' => $candidate_start,
+                                'period_end' => $candidate_end,
+                                'temporal_basis' => $candidate_temporal_basis,
+                            ],
+                            'temporal_analysis' => [
+                                'incoming_precision' => $incoming_precision,
+                                'candidate_precision' => $candidate_precision,
+                                'relation' => $temporal_relation,
+                                'incoming_basis' => $incoming_temporal_basis,
+                                'candidate_basis' => $candidate_temporal_basis,
+                                'absolute_time_comparison_performed' => false,
+                                'incoming_granularity' => $incoming_granularity,
+                                'candidate_granularity' => $candidate_granularity,
+                                'granularity_relation' => $temporal_granularity_relation,
+                                'same_granularity_is_identity_proof' => false,
+                                'same_granularity_establishes_timezone_compatibility' => false,
+                                'same_period_bounds' => $same_start && $same_end,
+                                'same_instant_bounds' => false,
+                                'same_event_datetime_string_representation' => $same_start && $same_end
+                                    && $record_type === 'event'
+                                    && isset($candidate_event['record_type']) && $candidate_event['record_type'] === 'event',
+                                'same_instant_is_proven' => false,
+                                'interpretation' => 'Temporal similarity is evidence of possible overlap only; it does not establish event identity.',
+                            ],
+                            'signals' => [
+                                'same_product' => isset($candidate_event['product_id']) && (int) $candidate_event['product_id'] === (int) $product_id,
+                                'same_record_type' => isset($candidate_event['record_type']) && (string) $candidate_event['record_type'] === (string) $record_type,
+                                'same_period_start' => $candidate_start !== '' && $candidate_start === $incoming_start,
+                                'same_period_end' => $candidate_end !== '' && $candidate_end === $incoming_end,
+                                'same_observed_view_count' => isset($candidate_event['observed_views']) && (int) $candidate_event['observed_views'] === (int) $views,
+                                'same_explicit_fingerprint_candidate_signal' => in_array('fingerprint', (array) ($candidate_event['_discovered_by'] ?? []), true) && $source_fingerprint !== '',
+                                'periods_intersect' => null,
+                                'same_period_string_representation' => $same_start && $same_end,
+                                'period_string_equality_is_temporal_proof' => false,
+                            ],
+                        ],
+                        'evidence_contract_version' => '1.7.0',
+                        'evidence' => $adapter_evidence,
+                    ];
+                }
+            }
+
+            if ($adapter_evidence_omitted > 0 && !empty($adapter_overlap_evidence)) {
+                $adapter_overlap_evidence[0]['evidence_budget_summary'] = [
+                    'total_limit_bytes' => $adapter_evidence_total_limit,
+                    'candidate_limit_bytes' => $adapter_evidence_candidate_limit,
+                    'omitted_candidates' => $adapter_evidence_omitted,
+                    'stored_evidence_bytes' => $adapter_evidence_bytes,
+                ];
+            }
+
+            $applied_views = $matched_event ? 0 : $views;
+            $inserted = statpl_db_insert($this->view_source_events_table, [
+                'source_id' => $source_id,
+                'source_record_key' => $record_key,
+                'source_record_hash' => $record_hash,
+                'product_id' => $product_id,
+                'record_type' => $record_type,
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'observed_views' => $views,
+                'applied_views' => $applied_views,
+                'source_fingerprint' => $has_exact_event_fingerprint ? $source_fingerprint : null,
+                'status' => $matched_event ? 'reconciled' : ($possible_overlap_event ? 'possible_overlap' : 'applied'),
+                'created_at' => $now,
+                'updated_at' => $now,
+            ]);
+
+            if ($inserted === 1) {
+                $new_event_id = (int) $wpdb->insert_id;
+                // Build the shared audit context for both exact matches and possible
+                // overlaps. The possible-overlap persistence path below also stores
+                // these values, so they must never depend on the exact-match branch.
+                $cross_source_assessment = null;
+                $partial_overlap_profiles = null;
+                $product_source_synthesis = null;
+                $product_reconciliation_summary = null;
+                if ($matched_event || $possible_overlap_event) {
+                    $audit_candidates = !empty($possible_overlap_events)
+                        ? $possible_overlap_events
+                        : ($matched_event ? [$matched_event] : [$possible_overlap_event]);
+                    $cross_source_assessment = $this->build_generic_cross_source_overlap_assessment(
+                        $product_id,
+                        $source_id,
+                        $adapter_key,
+                        $record_type,
+                        $period_start,
+                        $period_end,
+                        $audit_candidates,
+                        $possible_overlap_candidates_truncated,
+                        $views
+                    );
+                    $partial_overlap_profiles = $this->build_generic_partial_overlap_profiles(
+                        $product_id,
+                        $source_id,
+                        $period_start,
+                        $period_end
+                    );
+                    $product_source_synthesis = $this->build_generic_product_source_synthesis($product_id);
+                    $product_reconciliation_summary = $this->build_generic_product_reconciliation_summary(
+                        $product_id,
+                        $cross_source_assessment,
+                        $partial_overlap_profiles,
+                        $product_source_synthesis,
+                        $matched_event,
+                        [
+                            'candidates' => !empty($possible_overlap_events)
+                                ? $possible_overlap_events
+                                : ($matched_event ? [$matched_event] : ($possible_overlap_event ? [$possible_overlap_event] : [])),
+                            'truncated' => $possible_overlap_candidates_truncated,
+                            'observed_count' => $possible_overlap_candidate_count_observed,
+                        ]
+                    );
+                }
+                if ($matched_event) {
+                    $adapter_discovery_evidence_consistency = $this->build_generic_adapter_discovery_evidence_consistency(
+                        $candidate_conflict_assessment,
+                        $adapter_overlap_evidence
+                    );
+
+                    $evidence = wp_json_encode([
+                        'match_type' => 'exact_shared_fingerprint',
+                        'source_id' => $source_id,
+                        'matched_source_id' => (int) $matched_event['source_id'],
+                        'product_id' => $product_id,
+                        'record_type' => $record_type,
+                        'observed_views' => $views,
+                        'period_start' => $period_start,
+                        'period_end' => $period_end,
+                        'source_fingerprint' => $source_fingerprint,
+                        'cross_source_assessment' => $cross_source_assessment,
+                        'partial_overlap_profiles' => $partial_overlap_profiles,
+                        'product_source_synthesis' => $product_source_synthesis,
+                        'product_reconciliation_summary' => $product_reconciliation_summary,
+                        'candidate_set_assessment' => $this->build_generic_candidate_set_assessment(
+                            !empty($possible_overlap_events) ? $possible_overlap_events : [$matched_event],
+                            $possible_overlap_candidates_truncated,
+                            $possible_overlap_candidate_count_observed
+                        ),
+                    ]);
+                    $reconciliation_inserted = statpl_db_insert($this->view_source_reconciliation_table, [
+                        'event_id' => $new_event_id,
+                        'status' => 'matched_exact',
+                        'reason_code' => 'shared_fingerprint_exact_match',
+                        'reason' => 'A different source supplied the same explicit fingerprint and identical normalized event dimensions. This contribution was retained for audit but not added again.',
+                        'matched_event_id' => (int) $matched_event['id'],
+                        'evidence' => $evidence,
+                        'algorithm_version' => '1.0.0',
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ]);
+                    $history_inserted = $reconciliation_inserted === 1 ? statpl_db_insert($this->view_source_reconciliation_history_table, [
+                        'event_id' => $new_event_id,
+                        'previous_status' => null,
+                        'new_status' => 'matched_exact',
+                        'reason_code' => 'shared_fingerprint_exact_match',
+                        'reason' => 'Exact cross-source match using an adapter-provided shared fingerprint and identical normalized dimensions.',
+                        'matched_event_id' => (int) $matched_event['id'],
+                        'evidence' => $evidence,
+                        'algorithm_version' => '1.0.0',
+                        'created_at' => $now,
+                    ]) : false;
+                    if ($reconciliation_inserted !== 1 || $history_inserted !== 1) {
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id,
+                            $origin_key,
+                            $record_key,
+                            $product_id,
+                            'Could not persist cross-source reconciliation evidence: ' . $wpdb->last_error,
+                            $batch_start_checkpoint,
+                            3
+                        , $origin_lock);
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                    break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                }
+                if ($possible_overlap_event) {
+                    $adapter_dimension_evidence_consistency = $this->build_generic_adapter_dimension_evidence_consistency(
+                        $candidate_conflict_assessment,
+                        $adapter_overlap_evidence
+                    );
+                    // Validate that the primary reference, ordered candidate set and
+                    // adapter evidence describe the same candidate identities before
+                    // persisting the reconciliation record.
+                    $primary_candidate_id = (int) $possible_overlap_event['id'];
+                    $candidate_ids = array_values(array_unique(array_map(
+                        static function ($candidate) {
+                            return isset($candidate['id']) ? (int) $candidate['id'] : 0;
+                        },
+                        !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event]
+                    )));
+                    $candidate_ids = array_values(array_filter($candidate_ids, static function ($id) {
+                        return $id > 0;
+                    }));
+                    $candidate_list_primary_consistent = in_array($primary_candidate_id, $candidate_ids, true)
+                        && !empty($candidate_ids)
+                        && $candidate_ids[0] === $primary_candidate_id;
+
+                    $adapter_candidate_ids = array_values(array_map(
+                        static function ($entry) {
+                            return isset($entry['candidate_event_id']) ? (int) $entry['candidate_event_id'] : 0;
+                        },
+                        $adapter_overlap_evidence
+                    ));
+                    $adapter_evidence_primary_consistent = empty($adapter_overlap_evidence)
+                        || (
+                            isset($adapter_overlap_evidence[0]['is_primary_candidate'])
+                            && $adapter_overlap_evidence[0]['is_primary_candidate'] === true
+                            && $adapter_candidate_ids[0] === $primary_candidate_id
+                        );
+                    $adapter_evidence_order_consistent = true;
+                    foreach ($adapter_overlap_evidence as $index => $entry) {
+                        if (
+                            !isset($entry['candidate_rank'], $entry['candidate_event_id'])
+                            || (int) $entry['candidate_rank'] !== $index + 1
+                            || (int) $entry['candidate_event_id'] !== (int) ($candidate_ids[$index] ?? 0)
+                        ) {
+                            $adapter_evidence_order_consistent = false;
+                            break;
+                        }
+                    }
+
+                    $evidence = wp_json_encode([
+                        'match_type' => $possible_overlap_reason_code,
+                        'source_id' => $source_id,
+                        'matched_source_id' => (int) $possible_overlap_event['source_id'],
+                        'matched_event_id' => (int) $possible_overlap_event['id'],
+                        'current' => [
+                            'product_id' => $product_id,
+                            'record_type' => $record_type,
+                            'observed_views' => $views,
+                            'period_start' => $period_start,
+                            'period_end' => $period_end,
+                        ],
+                        'candidates_truncated' => $possible_overlap_candidates_truncated,
+                        'candidate_limit' => 25,
+                        'candidate_count_observed' => $possible_overlap_candidate_count_observed,
+                        'candidate_count_is_lower_bound' => $possible_overlap_candidate_count_is_lower_bound,
+                        'candidate_set_assessment' => $this->build_generic_candidate_set_assessment(
+                            !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event],
+                            $possible_overlap_candidates_truncated,
+                            $possible_overlap_candidate_count_observed
+                        ),
+                        'candidate_conflict_assessment' => $candidate_conflict_assessment = $this->build_generic_candidate_conflict_assessment(
+                            [
+                                'product_id' => $product_id,
+                                'record_type' => $record_type,
+                                'observed_views' => $views,
+                                'period_start' => $period_start,
+                                'period_end' => $period_end,
+                            ],
+                            !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event]
+                        ),
+                        'candidate_evidence_decision' => $candidate_evidence_decision = $this->build_generic_candidate_evidence_decision(
+                            $candidate_conflict_assessment,
+                            $candidate_set_assessment = $this->build_generic_candidate_set_assessment(
+                                !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event],
+                                $possible_overlap_candidates_truncated,
+                                $possible_overlap_candidate_count_observed
+                            ),
+                            $possible_overlap_candidates_truncated
+                        ),
+                        'candidate_audit_consistency' => $this->build_generic_candidate_audit_consistency(
+                            $candidate_set_assessment,
+                            $candidate_conflict_assessment,
+                            $candidate_evidence_decision
+                        ),
+                        'candidate_reference_consistency' => $this->build_generic_candidate_reference_consistency(
+                            $candidate_set_assessment,
+                            $candidate_conflict_assessment
+                        ),
+                        'candidate_discovery_signal_consistency' => $this->build_generic_candidate_discovery_signal_consistency(
+                            $candidate_set_assessment,
+                            $candidate_conflict_assessment
+                        ),
+                        'adapter_discovery_evidence_consistency' => $adapter_discovery_evidence_consistency,
+                        'adapter_dimension_evidence_consistency' => $adapter_dimension_evidence_consistency,
+                        'candidate_consistency' => [
+                            'primary_in_candidate_list' => $candidate_list_primary_consistent,
+                            'adapter_evidence_primary_consistent' => $adapter_evidence_primary_consistent,
+                            'adapter_evidence_order_consistent' => $adapter_evidence_order_consistent,
+                            'adapter_discovery_evidence_consistent' => !empty($adapter_discovery_evidence_consistency['consistent']),
+                            'adapter_dimension_evidence_consistent' => !empty($adapter_dimension_evidence_consistency['consistent']),
+                            'candidate_count' => count($candidate_ids),
+                            'adapter_evidence_candidate_count' => count($adapter_candidate_ids),
+                            'validation_policy' => 'audit_only_no_automatic_count_suppression',
+                        ],
+                        'candidate_reconciliation_chain' => $this->build_generic_candidate_reconciliation_chain_assessment(
+                            $candidate_set_assessment,
+                            $candidate_conflict_assessment,
+                            $candidate_evidence_decision,
+                            $this->build_generic_candidate_audit_consistency(
+                                $candidate_set_assessment,
+                                $candidate_conflict_assessment,
+                                $candidate_evidence_decision
+                            ),
+                            [
+                                'primary_in_candidate_list' => $candidate_list_primary_consistent,
+                                'adapter_evidence_primary_consistent' => $adapter_evidence_primary_consistent,
+                                'adapter_evidence_order_consistent' => $adapter_evidence_order_consistent,
+                                'adapter_discovery_evidence_consistent' => !empty($adapter_discovery_evidence_consistency['consistent']),
+                                'adapter_dimension_evidence_consistent' => !empty($adapter_dimension_evidence_consistency['consistent']),
+                                'candidate_count' => count($candidate_ids),
+                                'adapter_evidence_candidate_count' => count($adapter_candidate_ids),
+                            ],
+                            $this->build_generic_candidate_reference_consistency(
+                                $candidate_set_assessment,
+                                $candidate_conflict_assessment
+                            ),
+                            $this->build_generic_candidate_discovery_signal_consistency(
+                                $candidate_set_assessment,
+                                $candidate_conflict_assessment
+                            )
+                        ),
+                        'primary_candidate' => [
+                            'event_id' => (int) $possible_overlap_event['id'],
+                            'source_id' => (int) $possible_overlap_event['source_id'],
+                            'source_key' => isset($possible_overlap_event['candidate_source_key']) ? (string) $possible_overlap_event['candidate_source_key'] : null,
+                            'adapter_key' => isset($possible_overlap_event['candidate_adapter_key']) ? (string) $possible_overlap_event['candidate_adapter_key'] : null,
+                            'discovered_by' => isset($possible_overlap_event['_discovered_by']) ? $possible_overlap_event['_discovered_by'] : [],
+                            'selection_policy' => 'highest_discovery_evidence_then_lowest_event_id',
+                        ],
+                        'fingerprint_candidates_observed' => $possible_overlap_fingerprint_candidates_observed,
+                        'temporal_candidates_observed' => $possible_overlap_temporal_candidates_observed,
+                        'candidates' => array_map(static function ($candidate) {
+                            return [
+                                'event_id' => (int) $candidate['id'],
+                                'discovered_by' => isset($candidate['_discovered_by']) ? $candidate['_discovered_by'] : [],
+                                'source_id' => (int) $candidate['source_id'],
+                                'source_key' => isset($candidate['candidate_source_key']) ? (string) $candidate['candidate_source_key'] : null,
+                                'adapter_key' => isset($candidate['candidate_adapter_key']) ? (string) $candidate['candidate_adapter_key'] : null,
+                                'product_id' => (int) $candidate['product_id'],
+                                'record_type' => (string) $candidate['record_type'],
+                                'observed_views' => (int) $candidate['observed_views'],
+                                'applied_views' => (int) $candidate['applied_views'],
+                                'period_start' => $candidate['period_start'],
+                                'period_end' => $candidate['period_end'],
+                            ];
+                        }, !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event]),
+                        'cross_source_assessment' => $cross_source_assessment,
+                        'partial_overlap_profiles' => $partial_overlap_profiles,
+                        'product_source_synthesis' => $product_source_synthesis,
+                        'product_reconciliation_summary' => $product_reconciliation_summary,
+                        'source_fingerprint' => $source_fingerprint !== '' ? $source_fingerprint : null,
+                        'adapter_overlap_evidence' => $adapter_overlap_evidence,
+                        'counting_policy' => 'preserve_both_pending_source_specific_evidence',
+                    ]);
+                    $reconciliation_inserted = statpl_db_insert($this->view_source_reconciliation_table, [
+                        'event_id' => $new_event_id,
+                        'status' => 'possible_overlap',
+                        'reason_code' => $possible_overlap_reason_code,
+                        'reason' => 'A different source contains one or more potentially overlapping records. All matching candidates were retained as evidence; the contribution was preserved and counted because no automatic suppression was justified without stronger source-specific evidence.',
+                        'matched_event_id' => (int) $possible_overlap_event['id'],
+                        'evidence' => $evidence,
+                        'algorithm_version' => '1.6.0',
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ]);
+                    $history_inserted = $reconciliation_inserted === 1 ? statpl_db_insert($this->view_source_reconciliation_history_table, [
+                        'event_id' => $new_event_id,
+                        'previous_status' => null,
+                        'new_status' => 'possible_overlap',
+                        'reason_code' => $possible_overlap_reason_code,
+                        'reason' => 'Potential partial overlap recorded for review. Both source contributions remain counted until source-specific evidence justifies adjustment.',
+                        'matched_event_id' => (int) $possible_overlap_event['id'],
+                        'evidence' => $evidence,
+                        'algorithm_version' => '1.6.0',
+                        'created_at' => $now,
+                    ]) : false;
+                    if ($reconciliation_inserted !== 1 || $history_inserted !== 1) {
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id,
+                            $origin_key,
+                            $record_key,
+                            $product_id,
+                            'Could not persist possible-overlap reconciliation evidence: ' . $wpdb->last_error,
+                            $batch_start_checkpoint,
+                            3
+                        , $origin_lock);
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                    break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                }
+                if ($applied_views > 0) {
+                    $total_result = statpl_db_query(statpl_db_prepare(
+                        "INSERT INTO {$this->views_table} (product_id, total_views) VALUES (%d, %d)
+                         ON DUPLICATE KEY UPDATE total_views = total_views + VALUES(total_views)",
+                        $product_id,
+                        $applied_views
+                    ));
+                    if ($total_result === false) {
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id,
+                            $origin_key,
+                            $record_key,
+                            $product_id,
+                            'Could not update product view totals: ' . $wpdb->last_error,
+                            $batch_start_checkpoint,
+                            3
+                        , $origin_lock);
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                    break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                }
+                $origin_session_current = $this->generic_advisory_lock_session_is_current($origin_lock);
+                $fingerprint_session_current = !is_array($reconciliation_lock_state)
+                    || empty($reconciliation_lock_state['acquired'])
+                    || $this->generic_advisory_lock_session_is_current($reconciliation_lock_state);
+                if (!$origin_session_current || !$fingerprint_session_current) {
+                    // The transaction belongs to the origin-lock connection. A lost
+                    // advisory lock does not itself mean the DB connection changed.
+                    // Never send ROLLBACK to a transparently reconnected session.
+                    if ($transaction_open && !$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    return [
+                        'status' => 'transaction_lock_session_lost',
+                        'processed' => $processed,
+                        'duplicates' => $duplicates,
+                        'failed' => $failed,
+                    ];
+                }
+
+                if (statpl_db_query('COMMIT') === false) {
+                    $commit_error = (string) $wpdb->last_error;
+
+                    // A failed COMMIT acknowledgement is ambiguous when WordPress has
+                    // transparently reconnected: the server may have committed the
+                    // transaction before the client lost its connection. Do not issue
+                    // ledger writes on a replacement session or classify the record
+                    // as failed. Replaying the same record is safe because the source
+                    // event's unique key and transactional totals update are idempotent.
+                    $origin_session_after_commit = $this->generic_advisory_lock_session_is_current($origin_lock);
+                    $fingerprint_session_after_commit = !is_array($reconciliation_lock_state)
+                        || empty($reconciliation_lock_state['acquired'])
+                        || $this->generic_advisory_lock_session_is_current($reconciliation_lock_state);
+                    if (!$origin_session_after_commit || !$fingerprint_session_after_commit) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return [
+                            'status' => 'commit_outcome_unknown',
+                            'processed' => $processed,
+                            'duplicates' => $duplicates,
+                            'failed' => $failed,
+                        ];
+                    }
+
+                    // The original session is still alive, so the failed COMMIT can
+                    // be rolled back and recorded as a normal retryable row failure.
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Could not commit imported source event: ' . $commit_error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                $transaction_open = false;
+                $processed++;
+            } elseif ($inserted === false && stripos((string) $wpdb->last_error, 'duplicate') !== false) {
+                if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                // A repeated source_record_key is idempotent only when the stored
+                // normalized payload is identical. A changed payload under the same
+                // key signals an adapter/source inconsistency and must not be silently
+                // accepted as an ordinary duplicate.
+                $existing_event = statpl_db_get_row(statpl_db_prepare(
+                    "SELECT id, product_id, record_type, observed_views, period_start, period_end, source_fingerprint, status
+                     FROM {$this->view_source_events_table}
+                     WHERE source_id = %d AND source_record_hash = %s
+                     LIMIT 1",
+                    $source_id,
+                    $record_hash
+                ), ARRAY_A);
+                if (!empty($wpdb->last_error) || !is_array($existing_event)) {
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    return ['status' => 'duplicate_verification_failed', 'processed' => $processed, 'duplicates' => $duplicates];
+                }
+                $existing_period_start = $existing_event['period_start'] !== null ? (string) $existing_event['period_start'] : null;
+                $existing_period_end = $existing_event['period_end'] !== null ? (string) $existing_event['period_end'] : null;
+                $existing_fingerprint = $existing_event['source_fingerprint'] !== null ? (string) $existing_event['source_fingerprint'] : '';
+                $same_existing_payload = (int) $existing_event['product_id'] === $product_id
+                    && (string) $existing_event['record_type'] === $record_type
+                    && (int) $existing_event['observed_views'] === $views
+                    && $existing_period_start === $period_start
+                    && $existing_period_end === $period_end
+                    && $existing_fingerprint === $source_fingerprint;
+                if ($same_existing_payload) {
+                    // A retry must not rewrite reconciliation evidence or append
+                    // another history row. Verify the already committed audit record
+                    // before accepting the source event as a complete duplicate.
+                    $existing_event_id = isset($existing_event['id']) ? (int) $existing_event['id'] : 0;
+                    $existing_event_status = isset($existing_event['status']) ? (string) $existing_event['status'] : '';
+                    if (in_array($existing_event_status, ['possible_overlap', 'reconciled'], true)) {
+                        $existing_audit = statpl_db_get_row(statpl_db_prepare(
+                            "SELECT status, reason_code, matched_event_id, evidence, algorithm_version
+                             FROM {$this->view_source_reconciliation_table}
+                             WHERE event_id = %d
+                             LIMIT 1",
+                            $existing_event_id
+                        ), ARRAY_A);
+                        if (!empty($wpdb->last_error) || !is_array($existing_audit)) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_missing_or_unreadable',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+                        $existing_audit_evidence = !empty($existing_audit['evidence'])
+                            ? json_decode((string) $existing_audit['evidence'], true)
+                            : null;
+                        $audit_matches_event = is_array($existing_audit_evidence)
+                            && isset($existing_audit_evidence['source_id'])
+                            && (int) $existing_audit_evidence['source_id'] === (int) $source_id;
+                        if ($existing_event_status === 'possible_overlap') {
+                            $audit_matches_event = $audit_matches_event
+                                && isset($existing_audit['matched_event_id'], $existing_audit_evidence['primary_candidate']['event_id'])
+                                && (int) $existing_audit['matched_event_id'] === (int) $existing_audit_evidence['primary_candidate']['event_id']
+                                && (int) $existing_audit_evidence['primary_candidate']['event_id'] > 0;
+                        } elseif ($existing_event_status === 'reconciled') {
+                            $audit_matches_event = $audit_matches_event
+                                && (string) $existing_audit['status'] === 'matched_exact'
+                                && isset($existing_audit['matched_event_id'])
+                                && (int) $existing_audit['matched_event_id'] > 0;
+                        }
+                        if (!$audit_matches_event) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_integrity_mismatch',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+
+                        // The current reconciliation row and its latest history
+                        // snapshot must agree. History is verified, never synthesized
+                        // or repaired during a duplicate retry.
+                        $latest_history = statpl_db_get_row(statpl_db_prepare(
+                            "SELECT new_status, reason_code, matched_event_id, evidence, algorithm_version
+                             FROM {$this->view_source_reconciliation_history_table}
+                             WHERE event_id = %d
+                             ORDER BY id DESC
+                             LIMIT 1",
+                            $existing_event_id
+                        ), ARRAY_A);
+                        if (!empty($wpdb->last_error) || !is_array($latest_history)) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_history_missing_or_unreadable',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+
+                        $history_matches_audit = (string) $latest_history['new_status'] === (string) $existing_audit['status']
+                            && (string) $latest_history['reason_code'] === (string) $existing_audit['reason_code']
+                            && (int) ($latest_history['matched_event_id'] ?? 0) === (int) ($existing_audit['matched_event_id'] ?? 0)
+                            && (string) ($latest_history['evidence'] ?? '') === (string) ($existing_audit['evidence'] ?? '')
+                            && (string) $latest_history['algorithm_version'] === (string) $existing_audit['algorithm_version'];
+
+                        // Validate the recorded transition chain in ascending history
+                        // order. The first row is treated as the chain anchor because
+                        // older installations may not have retained its predecessor.
+                        $history_chain = statpl_db_get_results(statpl_db_prepare(
+                            "SELECT id, previous_status, new_status
+                             FROM {$this->view_source_reconciliation_history_table}
+                             WHERE event_id = %d
+                             ORDER BY id ASC",
+                            $existing_event_id
+                        ), ARRAY_A);
+                        if (!empty($wpdb->last_error) || !is_array($history_chain) || empty($history_chain)) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_history_chain_unreadable',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+
+                        $history_chain_consistent = true;
+                        $previous_new_status = null;
+                        $previous_history_id = 0;
+                        foreach ($history_chain as $history_entry) {
+                            $history_id = isset($history_entry['id']) ? (int) $history_entry['id'] : 0;
+                            $new_status = isset($history_entry['new_status']) ? (string) $history_entry['new_status'] : '';
+                            $previous_status = isset($history_entry['previous_status']) && $history_entry['previous_status'] !== null
+                                ? (string) $history_entry['previous_status']
+                                : null;
+
+                            if ($history_id <= $previous_history_id || $new_status === '') {
+                                $history_chain_consistent = false;
+                                break;
+                            }
+                            if ($previous_new_status !== null && $previous_status !== $previous_new_status) {
+                                $history_chain_consistent = false;
+                                break;
+                            }
+                            $previous_new_status = $new_status;
+                            $previous_history_id = $history_id;
+                        }
+
+                        if (!$history_chain_consistent) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_history_transition_chain_mismatch',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+
+                        if (!$history_matches_audit) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_history_integrity_mismatch',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+                    }
+                    $duplicates++;
+                } else {
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'The adapter returned different normalized data for an existing source record key. The original imported event was preserved.',
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                } else {
+                    $error = (string) $wpdb->last_error;
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Could not persist source event: ' . $error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                    break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+            } finally {
+                if ($transaction_open) {
+                    // A changed or unverifiable session means the original transaction
+                    // outcome cannot be inspected here. Do not issue transaction control
+                    // on a replacement connection; ensure the record is retried instead.
+                    if (!$this->generic_db_session_matches_lock($origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                }
+                if (is_array($reconciliation_lock_state) && !empty($reconciliation_lock_state['acquired'])) {
+                    $this->release_generic_advisory_lock($reconciliation_lock_state, 'cross_source_fingerprint');
+                }
+            }
+
+            $failure_cleared = $this->clear_generic_historical_view_failure($source_id, $origin_key, $record_key, $origin_lock);
+            if ($failure_cleared && is_array($record) && !empty($record['source_record_key']) && (string) $record['source_record_key'] !== $record_key) {
+                $failure_cleared = $this->clear_generic_historical_view_failure($source_id, $origin_key, $record['source_record_key'], $origin_lock, null);
+            } elseif ($failure_cleared && (!is_array($record) || empty($record['source_record_key']))) {
+                $failure_cleared = $this->clear_generic_historical_view_failure($source_id, $origin_key, wp_json_encode($record), $origin_lock, null);
+            }
+            if (!$failure_cleared) {
+                // The event may already be committed. Idempotency makes replay
+                // safe, but the cursor must not move beyond this record until
+                // its stale failure-ledger entries have been cleared.
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                $checkpoint_persistence_failed = true;
+                break;
+            }
+            $next_checkpoint['cursor'] = $cursor;
+            $next_checkpoint['processed'] = isset($next_checkpoint['processed']) ? (int) $next_checkpoint['processed'] + 1 : 1;
+            unset($normalization_error);
+        }
+
+        if ($checkpoint_persistence_failed) {
+            // Do not persist the adapter's batch-level next_checkpoint when a
+            // row could not be durably represented in the failure ledger. The
+            // next main-import attempt must revisit this batch and this row.
+            return [
+                'status' => 'failure_ledger_persist_failed',
+                'processed' => $processed,
+                'duplicates' => $duplicates,
+                'failed' => $failed,
+                'skipped' => $skipped,
+            ];
+        }
+
+        // A connection can be transparently re-established after a mid-batch DB outage.
+        // Never persist checkpoint/status progress unless this request still owns the
+        // original origin lock session that serialized the batch.
+        if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return [
+                'status' => 'checkpoint_blocked_origin_lock_session_lost',
+                'processed' => $processed,
+                'duplicates' => $duplicates,
+                'failed' => $failed,
+                'skipped' => $skipped,
+            ];
+        }
+
+        // Individual bad records have been durably placed in the failure ledger.
+        // Continue advancing the main batch checkpoint; a separate replay worker
+        // revisits the saved batch checkpoint without blocking later records.
+        if ($retry_checkpoint_override !== null) {
+            return [
+                'status' => $failed ? 'retry_replay_partial' : 'retry_replay_completed',
+                'processed' => $processed,
+                'duplicates' => $duplicates,
+                'failed' => $failed,
+            ];
+        }
+
+        if (isset($batch['next_checkpoint'])) {
+            $next_checkpoint['cursor'] = $batch['next_checkpoint'];
+        }
+        $has_more = !empty($batch['has_more']);
+        $failure_counts = statpl_db_get_row(statpl_db_prepare(
+            "SELECT SUM(CASE WHEN status = 'retry' THEN 1 ELSE 0 END) AS pending,
+                    SUM(CASE WHEN status = 'blocked' THEN 1 ELSE 0 END) AS blocked
+             FROM {$this->view_source_failures_table} WHERE source_id = %d AND origin_key = %s",
+            $source_id,
+            $origin_key
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error) || !is_array($failure_counts)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'failure_ledger_read_failed', 'processed' => $processed, 'duplicates' => $duplicates];
+        }
+        $pending_failures = (int) $failure_counts['pending'];
+        $blocked_failures = (int) $failure_counts['blocked'];
+        $origin_status = $has_more ? 'importing' : (($pending_failures > 0 || $blocked_failures > 0) ? ($blocked_failures > 0 ? 'needs_attention' : 'retry_wait') : 'completed');
+        if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'checkpoint_blocked_origin_lock_session_lost', 'processed' => $processed, 'duplicates' => $duplicates];
+        }
+
+        $updates = [
+            'checkpoint_data' => $next_checkpoint,
+            'last_error' => ($pending_failures > 0 || $blocked_failures > 0) ? 'One or more historical records remain unresolved; the main import continues independently.' : null,
+            'status' => $origin_status,
+        ];
+        if (!$has_more && $pending_failures === 0 && $blocked_failures === 0) {
+            $updates['completed_at'] = current_time('mysql');
+        } else {
+            $updates['completed_at'] = null;
+        }
+        $saved = $this->update_view_source_origin_state($source_id, $origin_key, $updates, $origin_lock);
+        if (empty($saved['status']) || $saved['status'] !== 'updated') {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'checkpoint_write_failed', 'processed' => $processed, 'duplicates' => $duplicates];
+        }
+
+        // A successful statpl_db_query() confirms that MySQL accepted the UPDATE,
+        // but a worker must not report durable progress until the exact state is
+        // readable again. This also handles ambiguous acknowledgements and
+        // storage-layer anomalies without advancing the scheduler to the next
+        // batch on an unverified checkpoint.
+        $persisted_state = $this->get_view_source_origin_state($source_id, $origin_key);
+        $checkpoint_is_persisted = isset($persisted_state['status'])
+            && $persisted_state['status'] === 'found'
+            && isset($persisted_state['checkpoint'])
+            && wp_json_encode($persisted_state['checkpoint']) === wp_json_encode($next_checkpoint)
+            && isset($persisted_state['origin_status'])
+            && $persisted_state['origin_status'] === $origin_status;
+        $completion_is_persisted = array_key_exists('completed_at', $updates)
+            && ((array_key_exists('completed_at', $persisted_state) && $updates['completed_at'] === null && $persisted_state['completed_at'] === null)
+                || (array_key_exists('completed_at', $persisted_state) && $updates['completed_at'] !== null && $persisted_state['completed_at'] === $updates['completed_at']));
+        if (!$checkpoint_is_persisted || !$completion_is_persisted || !$this->generic_advisory_lock_session_is_current($origin_lock)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return [
+                'status' => 'checkpoint_write_unverified',
+                'processed' => $processed,
+                'duplicates' => $duplicates,
+            ];
+        }
+
+        if ($has_more) {
+            $this->schedule_generic_historical_view_import_batch(5, $source_id, $origin_key);
+        }
+        if ($pending_failures > 0) {
+            $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+        }
+        return [
+            'status' => $has_more ? 'batch_completed' : ($pending_failures > 0 ? 'completed_with_pending_retries' : ($blocked_failures > 0 ? 'completed_with_unresolved_records' : 'completed')),
+            'processed' => $processed,
+            'duplicates' => $duplicates,
+            'checkpoint' => $next_checkpoint,
+        ];
+    }
+
+    private function register_view_source($source_key, $display_name, $adapter_version, $granularity, $status = 'detected', $adapter_key = null) {
+        global $wpdb;
+
+        $source_key = (string) $source_key;
+        $display_name = sanitize_text_field($display_name);
+        $adapter_version = sanitize_text_field($adapter_version);
+        $granularity = (string) $granularity;
+        $status = (string) $status;
+        $adapter_key = $adapter_key === null ? null : sanitize_key((string) $adapter_key);
+
+        if (
+            ($adapter_key !== null && ($adapter_key === '' || strlen($adapter_key) > 100))
+            ||
+            !preg_match('/^[a-z0-9_-]{1,100}$/D', $source_key)
+            || $display_name === ''
+            || $adapter_version === ''
+            || !preg_match('/^[a-z0-9_-]{1,20}$/D', $granularity)
+            || !preg_match('/^[a-z0-9_-]{1,20}$/D', $status)
+            || strlen($display_name) > 191
+            || strlen($adapter_version) > 32
+        ) {
+            return [
+                'status' => 'invalid_input',
+                'source_id' => 0,
+            ];
+        }
+
+        $now = current_time('mysql');
+
+        $result = statpl_db_query(statpl_db_prepare(
+            "INSERT INTO {$this->view_sources_table}
+                (source_key, adapter_key, display_name, adapter_version, granularity, status, created_at, updated_at)
+             VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+             ON DUPLICATE KEY UPDATE
+                display_name = IF(VALUES(adapter_key) IS NULL OR adapter_key IS NULL OR adapter_key = VALUES(adapter_key), VALUES(display_name), display_name),
+                adapter_version = IF(VALUES(adapter_key) IS NULL OR adapter_key IS NULL OR adapter_key = VALUES(adapter_key), VALUES(adapter_version), adapter_version),
+                granularity = IF(VALUES(adapter_key) IS NULL OR adapter_key IS NULL OR adapter_key = VALUES(adapter_key), VALUES(granularity), granularity),
+                updated_at = IF(VALUES(adapter_key) IS NULL OR adapter_key IS NULL OR adapter_key = VALUES(adapter_key), VALUES(updated_at), updated_at)",
+            $source_key,
+            $adapter_key,
+            $display_name,
+            $adapter_version,
+            $granularity,
+            $status,
+            $now,
+            $now
+        ));
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return [
+                'status' => 'database_error',
+                'source_id' => 0,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        $source_id = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT id FROM {$this->view_sources_table} WHERE source_key = %s",
+                $source_key
+            )
+        );
+
+        if (!empty($wpdb->last_error) || !$source_id) {
+            return [
+                'status' => 'database_error',
+                'source_id' => 0,
+                'error' => $wpdb->last_error !== ''
+                    ? $wpdb->last_error
+                    : 'Registered source ID could not be retrieved.',
+            ];
+        }
+
+        if ($adapter_key !== null) {
+            $ownership_result = statpl_db_query(
+                statpl_db_prepare(
+                    "UPDATE {$this->view_sources_table}
+                     SET adapter_key = %s
+                     WHERE id = %d AND (adapter_key IS NULL OR adapter_key = %s)",
+                    $adapter_key,
+                    (int) $source_id,
+                    $adapter_key
+                )
+            );
+            if ($ownership_result === false || $wpdb->last_error !== '') {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => 0,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+
+            $stored_adapter_key = statpl_db_get_var(statpl_db_prepare(
+                "SELECT adapter_key FROM {$this->view_sources_table} WHERE id = %d",
+                (int) $source_id
+            ));
+            if ($wpdb->last_error !== '') {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => 0,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+            if ((string) $stored_adapter_key !== $adapter_key) {
+                return [
+                    'status' => 'adapter_mismatch',
+                    'source_id' => 0,
+                ];
+            }
+        }
+
+        return [
+            'status' => 'registered',
+            'source_id' => (int) $source_id,
+        ];
+    }
+
+    private function register_view_source_origin($source_id, $origin_key, $adapter_key, $capabilities = [], $detection_status = 'unknown') {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = (string) $origin_key;
+        $adapter_key = (string) $adapter_key;
+        $detection_status = (string) $detection_status;
+
+        if (
+            !$source_id
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $adapter_key)
+            || !in_array($detection_status, ['unknown', 'available', 'missing_table', 'incompatible_schema', 'database_error'], true)
+            || !is_array($capabilities)
+        ) {
+            return [
+                'status' => 'invalid_input',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $source_exists = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT id FROM {$this->view_sources_table} WHERE id = %d",
+                $source_id
+            )
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        if (!$source_exists) {
+            return [
+                'status' => 'source_not_found',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        // An adapter identity is part of the immutable meaning of an origin's
+        // snapshot and checkpoint. Never silently replace it after initialization.
+        $existing_origin = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT adapter_key, snapshot_data, checkpoint_data, status
+                 FROM {$this->view_source_origins_table}
+                 WHERE source_id = %d AND origin_key = %s",
+                $source_id,
+                $origin_key
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        $existing_source_events = 0;
+        $existing_origin_failures = 0;
+        if (is_array($existing_origin) && isset($existing_origin['adapter_key']) && (string) $existing_origin['adapter_key'] !== $adapter_key) {
+            $existing_source_events = (int) statpl_db_get_var(statpl_db_prepare(
+                "SELECT COUNT(*) FROM {$this->view_source_events_table} WHERE source_id = %d",
+                $source_id
+            ));
+            if (!empty($wpdb->last_error)) {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+            $existing_origin_failures = (int) statpl_db_get_var(statpl_db_prepare(
+                "SELECT COUNT(*) FROM {$this->view_source_failures_table} WHERE source_id = %d AND origin_key = %s",
+                $source_id,
+                $origin_key
+            ));
+            if (!empty($wpdb->last_error)) {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+        }
+
+        if (
+            is_array($existing_origin)
+            && isset($existing_origin['adapter_key'])
+            && (string) $existing_origin['adapter_key'] !== $adapter_key
+            && (
+                !empty($existing_origin['snapshot_data'])
+                || !empty($existing_origin['checkpoint_data'])
+                || !in_array($existing_origin['status'], ['pending', 'unavailable'], true)
+                || $existing_source_events > 0
+                || $existing_origin_failures > 0
+            )
+        ) {
+            $message = sprintf(
+                'Historical adapter identity changed from "%1$s" to "%2$s" after this origin was initialized. Existing historical data and checkpoints were preserved; the replacement adapter was not allowed to reinterpret them.',
+                sanitize_key((string) $existing_origin['adapter_key']),
+                sanitize_key($adapter_key)
+            );
+            // A replacement adapter cannot safely inherit the old adapter's
+            // snapshot or checkpoint. Keep the origin automatically unavailable
+            // (rather than requiring administrator intervention), while normal
+            // discovery continues to look for the original adapter. If that
+            // original identity returns, the ordinary registration path can resume
+            // from the preserved checkpoint without reinterpreting historical data.
+            statpl_db_update(
+                $this->view_source_origins_table,
+                [
+                    'status' => 'unavailable',
+                    'last_error' => $message,
+                    'updated_at' => current_time('mysql'),
+                ],
+                [
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                ],
+                ['%s', '%s', '%s'],
+                ['%d', '%s']
+            );
+            if (!empty($wpdb->last_error)) {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+            return [
+                'status' => 'adapter_mismatch',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $capabilities_json = wp_json_encode($capabilities);
+
+        if (!is_string($capabilities_json)) {
+            return [
+                'status' => 'invalid_capabilities',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $now = current_time('mysql');
+
+        $result = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->view_source_origins_table}
+                    (source_id, origin_key, adapter_key, capabilities, detection_status, status, updated_at)
+                 VALUES (%d, %s, %s, %s, %s, %s, %s)
+                 ON DUPLICATE KEY UPDATE
+                    adapter_key = VALUES(adapter_key),
+                    capabilities = VALUES(capabilities),
+                    detection_status = %s,
+                    status = CASE
+                        WHEN VALUES(detection_status) <> 'available' AND status NOT IN ('completed', 'needs_attention') THEN 'unavailable'
+                        WHEN VALUES(detection_status) = 'available' AND status = 'unavailable' THEN 'pending'
+                        ELSE status
+                    END,
+                    updated_at = %s",
+                $source_id,
+                $origin_key,
+                $adapter_key,
+                $capabilities_json,
+                $detection_status,
+                $detection_status === 'available' ? 'pending' : 'unavailable',
+                $now,
+                $detection_status,
+                $now
+            )
+        );
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return [
+                'status' => 'database_error',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        return [
+            'status' => 'registered',
+            'source_id' => $source_id,
+            'origin_key' => $origin_key,
+        ];
+    }
+
+    private function get_view_source_origin_state($source_id, $origin_key) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = is_string($origin_key) ? trim($origin_key) : '';
+
+        if (
+            !$source_id
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+        ) {
+            return [
+                'status' => 'invalid_input',
+            ];
+        }
+
+        $row = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT
+                    source_id,
+                    origin_key,
+                    adapter_key,
+                    capabilities,
+                    snapshot_data,
+                    checkpoint_data,
+                    detection_status,
+                    status,
+                    last_error,
+                    started_at,
+                    completed_at,
+                    updated_at
+                 FROM {$this->view_source_origins_table}
+                 WHERE source_id = %d
+                   AND origin_key = %s",
+                $source_id,
+                $origin_key
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        if (!$row) {
+            return [
+                'status' => 'not_found',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $capabilities = null;
+        if ($row['capabilities'] !== null && $row['capabilities'] !== '') {
+            $capabilities = json_decode($row['capabilities'], true);
+            if (json_last_error() !== JSON_ERROR_NONE) {
+                return [
+                    'status' => 'invalid_stored_data',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'field' => 'capabilities',
+                ];
+            }
+        }
+
+        $snapshot = null;
+        if ($row['snapshot_data'] !== null && $row['snapshot_data'] !== '') {
+            $snapshot = json_decode($row['snapshot_data'], true);
+            if (json_last_error() !== JSON_ERROR_NONE) {
+                return [
+                    'status' => 'invalid_stored_data',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'field' => 'snapshot_data',
+                ];
+            }
+        }
+
+        $checkpoint = null;
+        if ($row['checkpoint_data'] !== null && $row['checkpoint_data'] !== '') {
+            $checkpoint = json_decode($row['checkpoint_data'], true);
+            if (json_last_error() !== JSON_ERROR_NONE) {
+                return [
+                    'status' => 'invalid_stored_data',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'field' => 'checkpoint_data',
+                ];
+            }
+        }
+
+        return [
+            'status' => 'found',
+            'source_id' => (int) $row['source_id'],
+            'origin_key' => $row['origin_key'],
+            'adapter_key' => $row['adapter_key'],
+            'capabilities' => $capabilities,
+            'snapshot' => $snapshot,
+            'checkpoint' => $checkpoint,
+            'detection_status' => $row['detection_status'],
+            'origin_status' => $row['status'],
+            'last_error' => $row['last_error'],
+            'started_at' => $row['started_at'],
+            'completed_at' => $row['completed_at'],
+            'updated_at' => $row['updated_at'],
+        ];
+    }
+
+    private function update_view_source_origin_state($source_id, $origin_key, $updates, $lock_context = null) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = is_string($origin_key) ? trim($origin_key) : '';
+
+        if (
+            !$source_id
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+            || !is_array($updates)
+            || empty($updates)
+        ) {
+            return [
+                'status' => 'invalid_input',
+            ];
+        }
+
+        $allowed_fields = [
+            'snapshot_data',
+            'checkpoint_data',
+            'status',
+            'last_error',
+            'started_at',
+            'completed_at',
+        ];
+
+        $columns = [];
+        $values = [];
+
+        foreach ($updates as $field => $value) {
+            if (!in_array($field, $allowed_fields, true)) {
+                return [
+                    'status' => 'invalid_field',
+                    'field' => $field,
+                ];
+            }
+
+            if (in_array($field, ['snapshot_data', 'checkpoint_data'], true)) {
+                if ($value !== null && !is_array($value)) {
+                    return [
+                        'status' => 'invalid_input',
+                        'field' => $field,
+                    ];
+                }
+
+                $encoded = $value === null ? null : wp_json_encode($value);
+
+                if ($value !== null && !is_string($encoded)) {
+                    return [
+                        'status' => 'encoding_error',
+                        'field' => $field,
+                    ];
+                }
+
+                $columns[] = "`{$field}` = %s";
+                $values[] = $encoded;
+                continue;
+            }
+
+            if ($field === 'status') {
+                if (
+                    !is_string($value)
+                    || !preg_match('/^[a-z0-9_-]{1,20}$/D', $value)
+                ) {
+                    return [
+                        'status' => 'invalid_input',
+                        'field' => $field,
+                    ];
+                }
+
+                $columns[] = "`{$field}` = %s";
+                $values[] = $value;
+                continue;
+            }
+
+            if ($field === 'last_error') {
+                if ($value !== null && !is_string($value)) {
+                    return [
+                        'status' => 'invalid_input',
+                        'field' => $field,
+                    ];
+                }
+
+                $columns[] = "`{$field}` = %s";
+                $values[] = $value;
+                continue;
+            }
+
+            if ($value !== null && (
+                !is_string($value)
+                || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $value)
+            )) {
+                return [
+                    'status' => 'invalid_input',
+                    'field' => $field,
+                ];
+            }
+
+            $columns[] = "`{$field}` = %s";
+            $values[] = $value;
+        }
+
+        $columns[] = '`updated_at` = %s';
+        $values[] = current_time('mysql');
+
+        $values[] = $source_id;
+        $values[] = $origin_key;
+
+        $lock_name = '';
+        if ($lock_context !== null) {
+            if (!$this->generic_advisory_lock_session_is_current($lock_context) || empty($lock_context['lock_name'])) {
+                return ['status' => 'lock_session_lost'];
+            }
+            $lock_name = (string) $lock_context['lock_name'];
+        }
+        // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- The optional lock predicate and its matching lock-name argument are both added only when lock_context is present.
+        $lock_predicate = $lock_context !== null ? ' AND IS_USED_LOCK(%s) = CONNECTION_ID()' : '';
+        if ($lock_context !== null) {
+            $values[] = $lock_name;
+        }
+        // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- SET placeholders and values are appended together from the validated origin-state field allowlist; source_id/origin_key and the optional lock placeholder are appended to the values in matching order.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+        $result = statpl_db_query(/* phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- Placeholder fragments and their values are assembled together from the same fixed allowlists; optional lock predicates and matching values are added together. */ statpl_db_prepare(
+            "UPDATE {$this->view_source_origins_table}
+             SET " . implode(', ', /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $columns) . "
+             WHERE source_id = %d AND origin_key = %s" . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $lock_predicate,
+            ...$values
+        ));
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return [
+                'status' => 'database_error',
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        if ($result === 0) {
+            if ($lock_context !== null && !$this->generic_advisory_lock_session_is_current($lock_context)) {
+                return ['status' => 'lock_session_lost'];
+            }
+            $exists = statpl_db_get_var(
+                statpl_db_prepare(
+                    "SELECT 1 FROM {$this->view_source_origins_table}
+                     WHERE source_id = %d AND origin_key = %s",
+                    $source_id,
+                    $origin_key
+                )
+            );
+
+            if (!empty($wpdb->last_error)) {
+                return [
+                    'status' => 'database_error',
+                    'error' => $wpdb->last_error,
+                ];
+            }
+
+            // The existence read can itself trigger a transparent wpdb reconnect.
+            // Revalidate the original lock session after that read before treating
+            // a zero-row UPDATE as a successful no-op. Otherwise a replacement
+            // connection could make an unperformed state transition look complete.
+            if ($lock_context !== null && !$this->generic_advisory_lock_session_is_current($lock_context)) {
+                return ['status' => 'lock_session_lost'];
+            }
+
+            if (!$exists) {
+                return [
+                    'status' => 'not_found',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                ];
+            }
+        }
+
+        return [
+            'status' => 'updated',
+            'source_id' => $source_id,
+            'origin_key' => $origin_key,
+        ];
+    }
+
+    private function save_view_source_origin_snapshot_if_empty($source_id, $origin_key, $snapshot) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = is_string($origin_key) ? trim($origin_key) : '';
+
+        if (
+            !$source_id
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+            || !is_array($snapshot)
+            || empty($snapshot)
+        ) {
+            return [
+                'status' => 'invalid_input',
+            ];
+        }
+
+        $encoded = wp_json_encode($snapshot);
+
+        if (!is_string($encoded)) {
+            return [
+                'status' => 'encoding_error',
+            ];
+        }
+
+        $result = statpl_db_query(
+            statpl_db_prepare(
+                "UPDATE {$this->view_source_origins_table}
+                 SET snapshot_data = %s, updated_at = %s
+                 WHERE source_id = %d
+                 AND origin_key = %s
+                 AND snapshot_data IS NULL",
+                $encoded,
+                current_time('mysql'),
+                $source_id,
+                $origin_key
+            )
+        );
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return [
+                'status' => 'database_error',
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        if ($result === 1) {
+            return [
+                'status' => 'updated',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $existing = $this->get_view_source_origin_state($source_id, $origin_key);
+
+        if ($existing['status'] !== 'found') {
+            return $existing;
+        }
+
+        if ($existing['snapshot'] !== null) {
+            return [
+                'status' => 'already_initialized',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'snapshot' => $existing['snapshot'],
+            ];
+        }
+
+        return [
+            'status' => 'database_error',
+            'source_id' => $source_id,
+            'origin_key' => $origin_key,
+        ];
+    }
+
+    private function initialize_view_source_origin_snapshot($source_id, $origin_key) {
+        global $wpdb;
+
+        $state = $this->get_view_source_origin_state($source_id, $origin_key);
+
+        if ($state['status'] !== 'found') {
+            return $state;
+        }
+
+        if (!empty($state['snapshot'])) {
+            return [
+                'status' => 'already_initialized',
+                'source_id' => (int) $source_id,
+                'origin_key' => $origin_key,
+                'snapshot' => $state['snapshot'],
+            ];
+        }
+
+        if ($state['detection_status'] !== 'available') {
+            return [
+                'status' => 'origin_unavailable',
+                'source_id' => (int) $source_id,
+                'origin_key' => $origin_key,
+                'detection_status' => $state['detection_status'],
+            ];
+        }
+
+        $origin_tables = [
+            'slim_stats' => $wpdb->prefix . 'slim_stats',
+            'slim_stats_archive' => $wpdb->prefix . 'slim_stats_archive',
+        ];
+
+        if (!isset($origin_tables[$origin_key])) {
+            return [
+                'status' => 'unsupported_origin',
+                'source_id' => (int) $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $table = $origin_tables[$origin_key];
+
+        $max_id = statpl_db_get_var(
+            "SELECT MAX(id) FROM `{$table}`"
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'source_id' => (int) $source_id,
+                'origin_key' => $origin_key,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        $snapshot = [
+            'max_id' => $max_id === null ? 0 : (int) $max_id,
+            'captured_at' => current_time('mysql'),
+        ];
+
+        $saved = $this->save_view_source_origin_snapshot_if_empty(
+            $source_id,
+            $origin_key,
+            $snapshot
+        );
+
+        if ($saved['status'] === 'already_initialized') {
+            return $saved;
+        }
+
+        if ($saved['status'] !== 'updated') {
+            return $saved;
+        }
+
+        return [
+            'status' => 'initialized',
+            'source_id' => (int) $source_id,
+            'origin_key' => $origin_key,
+            'snapshot' => $snapshot,
+        ];
+    }
+
+    private function save_view_source_origin_snapshot($source_id, $origin_key, $snapshot) {
+        if (!is_array($snapshot) || empty($snapshot)) {
+            return [
+                'status' => 'invalid_snapshot',
+            ];
+        }
+
+        return $this->update_view_source_origin_state(
+            $source_id,
+            $origin_key,
+            [
+                'snapshot_data' => $snapshot,
+            ]
+        );
+    }
+
+    private function save_view_source_origin_checkpoint($source_id, $origin_key, $checkpoint) {
+        if (!is_array($checkpoint) || empty($checkpoint)) {
+            return [
+                'status' => 'invalid_checkpoint',
+            ];
+        }
+
+        return $this->update_view_source_origin_state(
+            $source_id,
+            $origin_key,
+            [
+                'checkpoint_data' => $checkpoint,
+            ]
+        );
+    }
+
+    private function detect_slimstat_view_origins() {
+        global $wpdb;
+
+        $origins = [
+            'slim_stats' => $wpdb->prefix . 'slim_stats',
+            'slim_stats_archive' => $wpdb->prefix . 'slim_stats_archive',
+        ];
+
+        $required_columns = [
+            'id',
+            'content_type',
+            'content_id',
+            'dt',
+        ];
+
+        $results = [];
+
+        foreach ($origins as $origin_key => $table) {
+            $exists = statpl_db_get_var(
+                statpl_db_prepare(
+                    'SHOW TABLES LIKE %s',
+                    $wpdb->esc_like($table)
+                )
+            );
+
+            if (!empty($wpdb->last_error)) {
+                $results[$origin_key] = [
+                    'status' => 'database_error',
+                    'error' => $wpdb->last_error,
+                ];
+                continue;
+            }
+
+            if ($exists !== $table) {
+                $results[$origin_key] = [
+                    'status' => 'missing_table',
+                ];
+                continue;
+            }
+
+            $columns = statpl_db_get_col(
+                "SHOW COLUMNS FROM `{$table}`",
+                0
+            );
+
+            if (!empty($wpdb->last_error)) {
+                $results[$origin_key] = [
+                    'status' => 'database_error',
+                    'error' => $wpdb->last_error,
+                ];
+                continue;
+            }
+
+            $missing_columns = array_values(
+                array_diff($required_columns, $columns)
+            );
+
+            if (!empty($missing_columns)) {
+                $results[$origin_key] = [
+                    'status' => 'incompatible_schema',
+                    'missing_columns' => $missing_columns,
+                ];
+                continue;
+            }
+
+            $results[$origin_key] = [
+                'status' => 'available',
+                'capabilities' => [
+                    'historical_views' => true,
+                    'record_id' => true,
+                    'product_reference' => true,
+                    'event_timestamp' => true,
+                ],
+            ];
+        }
+
+        return $results;
+    }
+
+    private function initialize_slimstat_view_source_origins() {
+        $registration = $this->register_slimstat_view_source();
+
+        if (
+            !in_array($registration['status'], ['registered', 'partial'], true)
+            || empty($registration['source']['source_id'])
+        ) {
+            return [
+                'status' => 'registration_failed',
+                'registration' => $registration,
+                'origins' => [],
+            ];
+        }
+
+        $source_id = (int) $registration['source']['source_id'];
+        $origins = [];
+        $initialization_failed = false;
+        $available_origins = 0;
+
+        foreach ($registration['origins'] as $origin_key => $origin_data) {
+            $origin_registration = isset($origin_data['registration'])
+                ? $origin_data['registration']
+                : [];
+
+            if (($origin_registration['status'] ?? '') !== 'registered') {
+                $origins[$origin_key] = [
+                    'status' => 'registration_failed',
+                    'registration' => $origin_registration,
+                ];
+                $initialization_failed = true;
+                continue;
+            }
+
+            $detection_status = $origin_data['detection']['status'] ?? 'unknown';
+
+            if ($detection_status !== 'available') {
+                $origins[$origin_key] = [
+                    'status' => 'skipped',
+                    'reason' => $detection_status,
+                ];
+                continue;
+            }
+
+            $available_origins++;
+
+            $result = $this->initialize_view_source_origin_snapshot(
+                $source_id,
+                $origin_key
+            );
+
+            $origins[$origin_key] = $result;
+
+            if (!in_array(
+                $result['status'],
+                ['initialized', 'already_initialized'],
+                true
+            )) {
+                $initialization_failed = true;
+            }
+        }
+
+        if ($available_origins === 0 && !$initialization_failed) {
+            $status = 'no_available_origins';
+        } else {
+            $status = $initialization_failed ? 'partial' : 'initialized';
+        }
+
+        return [
+            'status' => $status,
+            'source_id' => $source_id,
+            'registration' => $registration,
+            'origins' => $origins,
+        ];
+    }
+
+    private function register_slimstat_view_source() {
+        $source = $this->register_view_source(
+            'slimstat',
+            'SlimStat',
+            '1.0.0',
+            'event',
+            'registered'
+        );
+
+        if ($source['status'] !== 'registered' || empty($source['source_id'])) {
+            return [
+                'status' => 'source_registration_failed',
+                'source' => $source,
+                'origins' => [],
+            ];
+        }
+
+        $source_id = (int) $source['source_id'];
+        $detected_origins = $this->detect_slimstat_view_origins();
+        $origins = [];
+        $registration_failed = false;
+
+        foreach ($detected_origins as $origin_key => $detection) {
+            $capabilities = isset($detection['capabilities'])
+                ? $detection['capabilities']
+                : [];
+
+            $registration = $this->register_view_source_origin(
+                $source_id,
+                $origin_key,
+                'slimstat',
+                $capabilities,
+                in_array($detection['status'], ['unknown', 'available', 'missing_table', 'incompatible_schema', 'database_error'], true)
+                    ? $detection['status']
+                    : 'unknown'
+            );
+
+            $origins[$origin_key] = [
+                'detection' => $detection,
+                'registration' => $registration,
+            ];
+
+            if ($registration['status'] !== 'registered') {
+                $registration_failed = true;
+            }
+        }
+
+        return [
+            'status' => $registration_failed ? 'partial' : 'registered',
+            'source' => $source,
+            'origins' => $origins,
+        ];
+    }
+
+    private function detect_slimstat_source() {
+    global $wpdb;
+
+    // Check whether SlimStat is installed and loaded.
+    if (!class_exists('wp_slimstat', false)) {
+        return [
+            'status' => 'not_installed',
+        ];
+    }
+
+    // SlimStat source tables.
+    $tables = [
+        'active'  => $wpdb->prefix . 'slim_stats',
+        'archive' => $wpdb->prefix . 'slim_stats_archive',
+    ];
+
+    $missing_tables = [];
+
+    // Check that both tables exist.
+    foreach ($tables as $key => $table) {
+        $exists = statpl_db_get_var(
+            statpl_db_prepare(
+                'SHOW TABLES LIKE %s',
+                $wpdb->esc_like($table)
+            )
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+            ];
+        }
+
+        if ($exists !== $table) {
+            $missing_tables[] = $table;
+        }
+    }
+
+    if (!empty($missing_tables)) {
+        return [
+            'status'  => 'missing_tables',
+            'missing' => $missing_tables,
+        ];
+    }
+
+    // Required columns for historical product-view import.
+    $required_columns = [
+        'id',
+        'content_type',
+        'content_id',
+        'dt',
+    ];
+
+    $incompatible_tables = [];
+
+    // Check the required schema in both tables.
+    foreach ($tables as $key => $table) {
+        $columns = statpl_db_get_col(
+            "SHOW COLUMNS FROM `{$table}`",
+            0
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+            ];
+        }
+
+        $missing_columns = array_diff(
+            $required_columns,
+            $columns
+        );
+
+        if (!empty($missing_columns)) {
+            $incompatible_tables[$table] = array_values(
+                $missing_columns
+            );
+        }
+    }
+
+    if (!empty($incompatible_tables)) {
+        return [
+            'status'          => 'incompatible_schema',
+            'missing_columns' => $incompatible_tables,
+        ];
+    }
+
+    return [
+        'status' => 'available',
+        'tables' => $tables,
+    ];
+}
+    private function get_slimstat_view_snapshot() {
+    global $wpdb;
+
+    $source = $this->detect_slimstat_source();
+
+    if ($source['status'] !== 'available') {
+        return $source;
+    }
+
+    $snapshot = [];
+
+    foreach ($source['tables'] as $key => $table) {
+        $max_id = statpl_db_get_var(
+    statpl_db_prepare(
+        "SELECT MAX(id) FROM `{$table}` WHERE content_type = %s",
+        'cpt:product'
+      )
+   );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+            ];
+        }
+
+        $snapshot[$key] = (int) $max_id;
+    }
+
+    return [
+        'status'   => 'available',
+        'snapshot' => $snapshot,
+    ];
+}
+private function initialize_slimstat_view_import() {
+    global $wpdb;
+
+    $existing = statpl_db_get_var(
+        statpl_db_prepare(
+            "SELECT source FROM {$this->view_import_state_table} WHERE source = %s",
+            'slimstat'
+        )
+    );
+
+    if (!empty($wpdb->last_error)) {
+        return [
+            'status' => 'database_error',
+        ];
+    }
+
+    if ($existing === 'slimstat') {
+        return [
+            'status' => 'already_initialized',
+        ];
+    }
+
+    $result = $this->get_slimstat_view_snapshot();
+
+    if ($result['status'] !== 'available') {
+        return $result;
+    }
+
+    $inserted = statpl_db_query(
+        statpl_db_prepare(
+            "INSERT IGNORE INTO {$this->view_import_state_table}
+            (source, snapshot_max_id, snapshot_active_max_id, snapshot_archive_max_id, last_processed_id, status, updated_at)
+        VALUES (%s, %d, %d, %d, %d, %s, %s)",
+                       'slimstat',
+                       max($result['snapshot']['active'], $result['snapshot']['archive']),
+                       $result['snapshot']['active'],
+                       $result['snapshot']['archive'],
+                       0,
+                       'pending',
+                       current_time('mysql')
+        )
+    );
+
+    if (false === $inserted) {
+        return [
+            'status' => 'database_error',
+        ];
+    }
+
+    if (0 === $inserted) {
+        $existing = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT source FROM {$this->view_import_state_table} WHERE source = %s",
+                'slimstat'
+            )
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+            ];
+        }
+
+        if ($existing === 'slimstat') {
+            return [
+                'status' => 'already_initialized',
+            ];
+        }
+
+        return [
+            'status' => 'insert_not_confirmed',
+        ];
+    }
+
+    return [
+        'status' => 'initialized',
+        'snapshot' => $result['snapshot'],
+    ];
+}
+
+    /**
+     * Retrieve the next historical SlimStat product-view batch.
+     * This method is read-only: it never changes the checkpoint or import tables.
+     */
+    private function get_slimstat_view_import_batch($last_processed_id, $batch_size = 50) {
+        global $wpdb;
+
+        $state = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT snapshot_active_max_id, snapshot_archive_max_id
+                 FROM {$this->view_import_state_table}
+                 WHERE source = %s",
+                'slimstat'
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'rows'   => [],
+            ];
+        }
+
+        if (!is_array($state)) {
+            return [
+                'status' => 'state_missing',
+                'rows'   => [],
+            ];
+        }
+
+        $active_max_id  = (int) $state['snapshot_active_max_id'];
+        $archive_max_id = (int) $state['snapshot_archive_max_id'];
+        $last_processed_id = max(0, (int) $last_processed_id);
+        $batch_size = max(1, min(500, (int) $batch_size));
+
+        $active_table  = $wpdb->prefix . 'slim_stats';
+        $archive_table = $wpdb->prefix . 'slim_stats_archive';
+
+        $sql = "
+            SELECT id, product_id, dt, source
+            FROM (
+                SELECT
+                    s.id AS id,
+                    s.content_id AS product_id,
+                    s.dt AS dt,
+                    'active' AS source
+                FROM `{$active_table}` s
+                WHERE s.content_type = %s
+                  AND s.id > %d
+                  AND s.id <= %d
+
+                UNION ALL
+
+                SELECT
+                    a.id AS id,
+                    a.content_id AS product_id,
+                    a.dt AS dt,
+                    'archive' AS source
+                FROM `{$archive_table}` a
+                WHERE a.content_type = %s
+                  AND a.id > %d
+                  AND a.id <= %d
+                  AND NOT EXISTS (
+                      SELECT 1
+                      FROM `{$active_table}` s
+                      WHERE s.id = a.id
+                        AND s.id <= %d
+                  )
+            ) AS combined
+            ORDER BY id ASC
+            LIMIT %d
+        ";
+
+        // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $sql is a fixed SQL template with value placeholders; execution below passes it through statpl_db_prepare() with the complete value list.
+        $rows = statpl_db_get_results(
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            statpl_db_prepare(
+                /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $sql,
+                'cpt:product',
+                $last_processed_id,
+                $active_max_id,
+                'cpt:product',
+                $last_processed_id,
+                $archive_max_id,
+                $active_max_id,
+                $batch_size
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'rows'   => [],
+            ];
+        }
+
+        return [
+            'status' => 'available',
+            'rows'   => is_array($rows) ? $rows : [],
+        ];
+    }
+
+    /**
+     * Import one historical SlimStat product-view event idempotently.
+     *
+     * The event ledger is the unique source of truth. A guarded multi-table
+     * update applies the metrics and marks the event in one atomic statement.
+     *
+     * The caller is responsible for checkpoint progression and retry handling.
+     *
+     * @param array $row Historical SlimStat source row.
+     * @return string imported|duplicate|failed
+     */
+    private function import_slimstat_view_event($row) {
+        global $wpdb;
+
+        if (
+            !is_array($row)
+            || !isset($row['id'], $row['product_id'])
+        ) {
+            return 'failed';
+        }
+
+        $source_view_id = (int) $row['id'];
+        $product_id = (int) $row['product_id'];
+
+        if ($source_view_id <= 0 || $product_id <= 0) {
+            return 'failed';
+        }
+
+        $now = current_time('mysql');
+
+        // Insert the event as unapplied. Repeating this insert is harmless.
+        $ledger_inserted = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->view_import_events_table}
+                (source, source_view_id, product_id, imported_at, counts_applied)
+                VALUES (%s, %d, %d, %s, 0)
+                ON DUPLICATE KEY UPDATE
+                    source_view_id = VALUES(source_view_id)",
+                'slimstat',
+                $source_view_id,
+                $product_id,
+                $now
+            )
+        );
+
+        if (false === $ledger_inserted) {
+            return 'failed';
+        }
+
+        // Verify the existing event identity; never reassign it to another product.
+        $event = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT product_id, counts_applied
+                FROM {$this->view_import_events_table}
+                WHERE source = %s AND source_view_id = %d",
+                'slimstat',
+                $source_view_id
+            ),
+            ARRAY_A
+        );
+
+        if (
+            !is_array($event)
+            || !isset($event['product_id'], $event['counts_applied'])
+            || (int) $event['product_id'] !== $product_id
+        ) {
+            return 'failed';
+        }
+
+        if (1 === (int) $event['counts_applied']) {
+            return 'duplicate';
+        }
+
+        // Ensure both metric rows exist. These writes are safe to repeat.
+        $total_ready = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->views_table}
+                (product_id, total_views)
+                VALUES (%d, 0)
+                ON DUPLICATE KEY UPDATE product_id = VALUES(product_id)",
+                $product_id
+            )
+        );
+
+        if (false === $total_ready) {
+            return 'failed';
+        }
+
+        $aggregate_ready = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->view_imports_table}
+                (source, product_id, imported_views, imported_at)
+                VALUES (%s, %d, 0, %s)
+                ON DUPLICATE KEY UPDATE product_id = VALUES(product_id)",
+                'slimstat',
+                $product_id,
+                $now
+            )
+        );
+
+        if (false === $aggregate_ready) {
+            return 'failed';
+        }
+
+        /*
+         * Apply all three changes atomically.
+         * Replaying this statement cannot increment the metrics twice.
+         */
+        $metrics_updated = statpl_db_query(
+            statpl_db_prepare(
+                "UPDATE {$this->views_table} t
+                INNER JOIN {$this->view_imports_table} i
+                    ON i.source = %s AND i.product_id = t.product_id
+                INNER JOIN {$this->view_import_events_table} e
+                    ON e.source = %s
+                    AND e.source_view_id = %d
+                    AND e.product_id = t.product_id
+                SET
+                    t.total_views = t.total_views + 1,
+                    i.imported_views = i.imported_views + 1,
+                    i.imported_at = %s,
+                    e.counts_applied = 1
+                WHERE t.product_id = %d
+                  AND e.counts_applied = 0",
+                'slimstat',
+                'slimstat',
+                $source_view_id,
+                $now,
+                $product_id
+            )
+        );
+
+        if (false === $metrics_updated) {
+            return 'failed';
+        }
+
+        if (3 === $metrics_updated) {
+            delete_transient('statpl_global_summary_v2');
+            return 'imported';
+        }
+
+        // Verify an ambiguous or concurrent result using the durable marker.
+        if (0 === $metrics_updated) {
+            $event = statpl_db_get_row(
+                statpl_db_prepare(
+                    "SELECT product_id, counts_applied
+                    FROM {$this->view_import_events_table}
+                    WHERE source = %s AND source_view_id = %d",
+                    'slimstat',
+                    $source_view_id
+                ),
+                ARRAY_A
+            );
+
+            if (
+                is_array($event)
+                && isset($event['product_id'], $event['counts_applied'])
+                && (int) $event['product_id'] === $product_id
+                && 1 === (int) $event['counts_applied']
+            ) {
+                delete_transient('statpl_global_summary_v2');
+                return 'duplicate';
+            }
+        }
+
+        return 'failed';
+    }
+
+
+    /** Persist an initial SlimStat import failure without counting a replay as another attempt. */
+    private function record_slimstat_view_import_failure($row, $error) {
+        global $wpdb;
+
+        $source_view_id = isset($row['id']) ? absint($row['id']) : 0;
+        $product_id = isset($row['product_id']) ? absint($row['product_id']) : 0;
+
+        if ($source_view_id < 1) {
+            return false;
+        }
+
+        $error = substr(wp_strip_all_tags((string) $error), 0, 4000);
+        if ($error === '') {
+            $error = 'SlimStat historical view could not be imported.';
+        }
+
+        $result = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->view_import_failures_table}
+                    (source, source_view_id, product_id, attempts, last_error, status, updated_at)
+                 VALUES (%s, %d, %d, 1, %s, 'retry', %s)
+                 ON DUPLICATE KEY UPDATE last_error = VALUES(last_error)",
+                'slimstat',
+                $source_view_id,
+                $product_id,
+                $error,
+                current_time('mysql')
+            )
+        );
+
+        if (false === $result) {
+            return false;
+        }
+        $this->save_historical_import_report_record('slimstat', 'SlimStat', 'slimstat', hash('sha256', "slimstat\0" . $source_view_id), 'retry', 1, 'record_import_failed');
+
+        $failure = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT product_id
+                 FROM {$this->view_import_failures_table}
+                 WHERE source = %s AND source_view_id = %d",
+                'slimstat',
+                $source_view_id
+            ),
+            ARRAY_A
+        );
+
+        return empty($wpdb->last_error)
+            && is_array($failure)
+            && isset($failure['product_id'])
+            && (int) $failure['product_id'] === $product_id;
+    }
+
+    /** Process independently due SlimStat retries. */
+    private function process_slimstat_view_import_retries($lock = null) {
+        global $wpdb;
+
+        // Retry processing is part of the same serialized worker as the main
+        // batch. Verify ownership per event, not merely before and after the
+        // entire retry loop, because a transparent reconnect can occur midway.
+        if (!$this->slimstat_import_lock_is_current($lock)) {
+            return false;
+        }
+
+        $now = current_time('mysql');
+
+        $failures = statpl_db_get_results(
+            statpl_db_prepare(
+                "SELECT id, source_view_id, product_id, attempts
+                 FROM {$this->view_import_failures_table}
+                 WHERE source = %s
+                   AND status = 'retry'
+                   AND (
+                       (attempts = 1 AND updated_at <= DATE_SUB(%s, INTERVAL 1 MINUTE))
+                       OR
+                       (attempts = 2 AND updated_at <= DATE_SUB(%s, INTERVAL 2 MINUTE))
+                   )
+                 ORDER BY updated_at ASC
+                 LIMIT 50",
+                'slimstat',
+                $now,
+                $now
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error) || !is_array($failures)) {
+            return false;
+        }
+
+        foreach ($failures as $failure) {
+            if (!$this->slimstat_import_lock_is_current($lock)) {
+                return false;
+            }
+
+            $result = $this->import_slimstat_view_event([
+                'id'         => (int) $failure['source_view_id'],
+                'product_id' => (int) $failure['product_id'],
+            ]);
+
+            // The event may have committed immediately before a DB reconnect.
+            // Its counts_applied marker makes replay safe, but no retry-ledger
+            // mutation may continue on a replacement session without the lock.
+            if (!$this->slimstat_import_lock_is_current($lock)) {
+                return false;
+            }
+
+            if (in_array($result, ['imported', 'duplicate'], true)) {
+                $this->save_historical_import_report_record('slimstat', 'SlimStat', 'slimstat', hash('sha256', "slimstat\0" . (int) $failure['source_view_id']), 'imported', (int) $failure['attempts'], '');
+                $deleted = statpl_db_delete(
+                    $this->view_import_failures_table,
+                    [
+                        'id'     => (int) $failure['id'],
+                        'source' => 'slimstat',
+                    ],
+                    ['%d', '%s']
+                );
+
+                if (false === $deleted || !$this->slimstat_import_lock_is_current($lock)) {
+                    return false;
+                }
+
+                continue;
+            }
+
+            $error = !empty($wpdb->last_error)
+                ? $wpdb->last_error
+                : 'SlimStat historical view retry failed.';
+
+            $updated = statpl_db_query(
+                statpl_db_prepare(
+                    "UPDATE {$this->view_import_failures_table}
+                     SET
+                         status = IF(attempts >= 2, 'failed', 'retry'),
+                         attempts = attempts + 1,
+                         last_error = %s,
+                         updated_at = %s
+                     WHERE id = %d
+                       AND source = %s
+                       AND status = 'retry'
+                       AND attempts < 3",
+                    substr(wp_strip_all_tags((string) $error), 0, 4000),
+                    current_time('mysql'),
+                    (int) $failure['id'],
+                    'slimstat'
+                )
+            );
+
+            if (1 !== $updated || !$this->slimstat_import_lock_is_current($lock)) {
+                return false;
+            }
+            $this->save_historical_import_report_record('slimstat', 'SlimStat', 'slimstat', hash('sha256', "slimstat\0" . (int) $failure['source_view_id']), ((int) $failure['attempts'] >= 2 ? 'failed' : 'retry'), (int) $failure['attempts'] + 1, 'record_import_failed');
+        }
+
+        return $this->slimstat_import_lock_is_current($lock);
+    }
+
+    /** Return the delay until the earliest pending SlimStat retry. */
+    private function get_slimstat_view_import_retry_delay() {
+        global $wpdb;
+
+        $delay = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT GREATEST(
+                    5,
+                    TIMESTAMPDIFF(
+                        SECOND,
+                        %s,
+                        CASE
+                            WHEN attempts = 1 THEN DATE_ADD(updated_at, INTERVAL 1 MINUTE)
+                            ELSE DATE_ADD(updated_at, INTERVAL 2 MINUTE)
+                        END
+                    )
+                 )
+                 FROM {$this->view_import_failures_table}
+                 WHERE source = %s AND status = 'retry'
+                 ORDER BY
+                    CASE
+                        WHEN attempts = 1 THEN DATE_ADD(updated_at, INTERVAL 1 MINUTE)
+                        ELSE DATE_ADD(updated_at, INTERVAL 2 MINUTE)
+                    END ASC
+                 LIMIT 1",
+                current_time('mysql'),
+                'slimstat'
+            )
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return 60;
+        }
+
+        return null === $delay ? 5 : max(5, (int) $delay);
+    }
+
+    /** Advance the SlimStat checkpoint only after the current row is durably resolved. */
+    private function update_slimstat_view_import_checkpoint($expected_id, $next_id, $lock) {
+        global $wpdb;
+
+        $expected_id = max(0, (int) $expected_id);
+        $next_id = max(0, (int) $next_id);
+
+        if ($next_id <= $expected_id) {
+            return $this->slimstat_import_lock_is_current($lock);
+        }
+        if (!$this->slimstat_import_lock_is_current($lock)) {
+            return false;
+        }
+
+        // Enforce ownership inside the checkpoint UPDATE itself. This closes
+        // the check/write race if wpdb reconnects between separate statements.
+        $updated = statpl_db_query(
+            statpl_db_prepare(
+                "UPDATE {$this->view_import_state_table}
+                 SET last_processed_id = %d, updated_at = %s
+                 WHERE source = %s AND last_processed_id = %d
+                   AND CONNECTION_ID() = %s
+                   AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+                $next_id,
+                current_time('mysql'),
+                'slimstat',
+                $expected_id,
+                (string) $lock['connection_id'],
+                (string) $lock['lock_name']
+            )
+        );
+
+        return 1 === $updated && $this->slimstat_import_lock_is_current($lock);
+    }
+
+    /** Capture and verify the exact MySQL session that owns the SlimStat import lock. */
+    private function acquire_slimstat_import_lock($lock_name) {
+        global $wpdb;
+        try {
+            $row = statpl_db_get_row(statpl_db_prepare(
+                'SELECT CONNECTION_ID() AS connection_id, GET_LOCK(%s, 0) AS lock_acquired',
+                (string) $lock_name
+            ), ARRAY_A);
+        } catch (Throwable $exception) {
+            return ['acquired' => false, 'error' => $exception->getMessage()];
+        }
+        if (!is_array($row) || !empty($wpdb->last_error)
+            || (string) ($row['lock_acquired'] ?? '') !== '1'
+            || empty($row['connection_id'])) {
+            return ['acquired' => false, 'error' => (string) $wpdb->last_error];
+        }
+        return [
+            'acquired' => true,
+            'connection_id' => (string) $row['connection_id'],
+            'lock_name' => (string) $lock_name,
+        ];
+    }
+
+    /** Verify both connection identity and actual ownership of the SlimStat lock. */
+    private function slimstat_import_lock_is_current($lock) {
+        global $wpdb;
+        if (!is_array($lock) || empty($lock['acquired'])
+            || empty($lock['connection_id']) || empty($lock['lock_name'])) {
+            return false;
+        }
+        try {
+            $row = statpl_db_get_row(statpl_db_prepare(
+                'SELECT CONNECTION_ID() AS connection_id, IS_USED_LOCK(%s) AS lock_owner',
+                (string) $lock['lock_name']
+            ), ARRAY_A);
+        } catch (Throwable $exception) {
+            return false;
+        }
+        return is_array($row) && empty($wpdb->last_error)
+            && (string) ($row['connection_id'] ?? '') === (string) $lock['connection_id']
+            && (string) ($row['lock_owner'] ?? '') === (string) $lock['connection_id'];
+    }
+
+    /** Release the SlimStat lock only through the original lock-owning session. */
+    private function release_slimstat_import_lock($lock) {
+        global $wpdb;
+        if (!$this->slimstat_import_lock_is_current($lock)) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: SlimStat advisory lock session changed before release.');
+            }
+            return false;
+        }
+        try {
+            $released = statpl_db_get_var(statpl_db_prepare(
+                'SELECT RELEASE_LOCK(%s)', (string) $lock['lock_name']
+            ));
+            return (string) $released === '1' && empty($wpdb->last_error);
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: SlimStat advisory lock release failed: ' . $exception->getMessage());
+            }
+            return false;
+        }
+    }
+
+    /** Execute one protected SlimStat historical import batch. */
+    public function run_slimstat_view_import_batch() {
+        global $wpdb;
+
+        // MySQL advisory lock names must remain within the server's 64-character limit.
+        $lock_name = 'statpl_view_import_' . substr(md5($wpdb->prefix), 0, 32);
+
+        $slimstat_lock = $this->acquire_slimstat_import_lock($lock_name);
+
+        if (empty($slimstat_lock['acquired'])) {
+            $this->schedule_slimstat_view_import_batch(
+                !empty($wpdb->last_error) ? 60 : 15
+            );
+            return;
+        }
+
+        try {
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            $state = statpl_db_get_row(
+                statpl_db_prepare(
+                    "SELECT snapshot_max_id, last_processed_id, status
+                     FROM {$this->view_import_state_table}
+                     WHERE source = %s",
+                    'slimstat'
+                ),
+                ARRAY_A
+            );
+
+            if (!empty($wpdb->last_error)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            if (!is_array($state)) {
+                return;
+            }
+
+            if (!in_array($state['status'], ['pending', 'running'], true)) {
+                return;
+            }
+
+            $state_updated = statpl_db_query(
+                statpl_db_prepare(
+                    "UPDATE {$this->view_import_state_table}
+                     SET status = 'running', updated_at = %s
+                     WHERE source = %s AND status IN ('pending', 'running')
+                       AND CONNECTION_ID() = %s
+                       AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+                    current_time('mysql'),
+                    'slimstat',
+                    (string) $slimstat_lock['connection_id'],
+                    (string) $slimstat_lock['lock_name']
+                )
+            );
+
+            if (false === $state_updated) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            // Retry previously failed rows independently of the sequential source batch.
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            if (!$this->process_slimstat_view_import_retries($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                // A retry may have committed its event before a transparent DB
+                // reconnect. Its durable event marker makes replay safe, but this
+                // worker must not advance the sequential checkpoint on a new session.
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            $checkpoint = (int) $state['last_processed_id'];
+            $snapshot_max_id = (int) $state['snapshot_max_id'];
+
+            $batch = $this->get_slimstat_view_import_batch($checkpoint, 50);
+
+            if (
+                !is_array($batch)
+                || !isset($batch['status'], $batch['rows'])
+                || 'available' !== $batch['status']
+                || !is_array($batch['rows'])
+            ) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            foreach ($batch['rows'] as $row) {
+                if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+                // A checkpoint replay must not consume another import attempt.
+                $existing_failure = statpl_db_get_row(
+                    statpl_db_prepare(
+                        "SELECT product_id, status
+                         FROM {$this->view_import_failures_table}
+                         WHERE source = %s AND source_view_id = %d",
+                        'slimstat',
+                        (int) $row['id']
+                    ),
+                    ARRAY_A
+                );
+
+                if (!empty($wpdb->last_error)) {
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+
+                if (is_array($existing_failure)) {
+                    if ((int) $existing_failure['product_id'] !== (int) $row['product_id']) {
+                        $this->debug_log(
+                            'Statora Plus: SlimStat failure ledger product ID mismatch for source event '
+                            . (int) $row['id']
+                        );
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+
+                    if (!in_array($existing_failure['status'], ['retry', 'failed'], true)) {
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+
+                    // The failure is already durable; wait for its independent retry.
+                    $next_id = (int) $row['id'];
+
+                    if (!$this->slimstat_import_lock_is_current($slimstat_lock)
+                        || !$this->update_slimstat_view_import_checkpoint($checkpoint, $next_id, $slimstat_lock)) {
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+
+                    $checkpoint = $next_id;
+                    continue;
+                }
+
+                $result = $this->import_slimstat_view_event($row);
+
+                if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                    // The event helper may have completed its atomic metric update
+                    // just before a connection loss. Do not move the checkpoint;
+                    // replay is protected by counts_applied and the unique event key.
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+
+                if (in_array($result, ['imported', 'duplicate'], true)) {
+                    $this->save_historical_import_report_record('slimstat', 'SlimStat', 'slimstat', hash('sha256', "slimstat\0" . (int) $row['id']), 'imported', is_array($existing_failure) ? (int) ($existing_failure['attempts'] ?? 0) : 0, '');
+                    // A previous retry record is no longer needed after confirmed success.
+                    $deleted = statpl_db_delete(
+                        $this->view_import_failures_table,
+                        [
+                            'source'        => 'slimstat',
+                            'source_view_id' => (int) $row['id'],
+                        ],
+                        ['%s', '%d']
+                    );
+
+                    if (false === $deleted) {
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+                } else {
+                    // Capture the helper's SQL error before executing another database query.
+                    $error = !empty($wpdb->last_error)
+                        ? $wpdb->last_error
+                        : 'SlimStat historical view could not be imported.';
+
+                    if (!$this->record_slimstat_view_import_failure($row, $error)) {
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+                }
+
+                $next_id = (int) $row['id'];
+
+                if (!$this->slimstat_import_lock_is_current($slimstat_lock)
+                    || !$this->update_slimstat_view_import_checkpoint($checkpoint, $next_id, $slimstat_lock)) {
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+
+                $checkpoint = $next_id;
+            }
+
+            if (!empty($batch['rows'])) {
+                $this->schedule_slimstat_view_import_batch(5);
+                return;
+            }
+
+            // An empty successful source query means the snapshot has been exhausted.
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            if ($checkpoint < $snapshot_max_id) {
+                if (!$this->update_slimstat_view_import_checkpoint($checkpoint, $snapshot_max_id, $slimstat_lock)) {
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+
+                $checkpoint = $snapshot_max_id;
+            }
+
+            $failure_counts = statpl_db_get_row(
+                statpl_db_prepare(
+                    "SELECT
+                        SUM(CASE WHEN status = 'retry' THEN 1 ELSE 0 END) AS pending_retries,
+                        SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS terminal_failures
+                     FROM {$this->view_import_failures_table}
+                     WHERE source = %s",
+                    'slimstat'
+                ),
+                ARRAY_A
+            );
+
+            if (!empty($wpdb->last_error) || !is_array($failure_counts)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            $pending_retries = (int) $failure_counts['pending_retries'];
+            $terminal_failures = (int) $failure_counts['terminal_failures'];
+
+            if ($pending_retries > 0) {
+                $this->schedule_slimstat_view_import_batch(
+                    $this->get_slimstat_view_import_retry_delay()
+                );
+                return;
+            }
+
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            $final_status = $terminal_failures > 0 ? 'error' : 'complete';
+
+            $finalized = statpl_db_query(
+                statpl_db_prepare(
+                    "UPDATE {$this->view_import_state_table}
+                     SET status = %s, updated_at = %s
+                     WHERE source = %s AND status IN ('pending', 'running')
+                       AND CONNECTION_ID() = %s
+                       AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+                    $final_status,
+                    current_time('mysql'),
+                    'slimstat',
+                    (string) $slimstat_lock['connection_id'],
+                    (string) $slimstat_lock['lock_name']
+                )
+            );
+
+            if (1 !== $finalized || !$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+            }
+        } finally {
+            // Release only through the original connection. If WordPress transparently
+            // reconnected, MySQL has already released the old session's advisory lock.
+            $this->release_slimstat_import_lock($slimstat_lock);
+        }
+    }
+
+    /** Schedule one independent SlimStat view import batch. */
+    public function schedule_slimstat_view_import_batch($delay = 10) {
+        global $wpdb;
+
+        $status = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT status FROM {$this->view_import_state_table} WHERE source = %s",
+                'slimstat'
+            )
+        );
+
+        if (!empty($wpdb->last_error) || !in_array($status, ['pending', 'running'], true)) {
+            return;
+        }
+
+        $delay = max(5, (int) $delay);
+
+        if (function_exists('as_schedule_single_action') && !did_action('action_scheduler_init')) {
+            add_action('action_scheduler_init', [$this, 'schedule_slimstat_view_import_batch'], 10, 0);
+            return;
+        }
+
+        if (
+            did_action('action_scheduler_init')
+            && class_exists('ActionScheduler')
+            && class_exists('ActionScheduler_Store')
+            && null !== ActionScheduler::store()->query_action(
+                [
+                    'hook'    => 'statpl_view_import_batch',
+                    'status'  => ActionScheduler_Store::STATUS_PENDING,
+                    'group'   => 'statpl-plus',
+                    'args'    => [],
+                    'orderby' => 'none',
+                ]
+            )
+        ) {
+            return;
+        }
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $action_id = as_schedule_single_action(
+                time() + $delay,
+                'statpl_view_import_batch',
+                [],
+                'statpl-plus'
+            );
+
+            if ($action_id) {
+                return;
+            }
+        }
+
+        if (!wp_next_scheduled('statpl_view_import_batch')) {
+            wp_schedule_single_event(time() + $delay, 'statpl_view_import_batch');
+        }
+    }
+
     /** Schedule one import batch with a delay to avoid overlapping batch execution. */
     public function schedule_import_batch($delay = 10) {
@@ -645 +10105 @@
         $args = array_merge([$since,$since,$since], $ids);
         // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Query is prepared with all variable values; table name is a class property built from the WordPress table prefix and fixed suffix; event counts must be current.
-        $rows = $wpdb->get_results($wpdb->prepare($sql, $args), ARRAY_A);
+        $rows = statpl_db_get_results(statpl_db_prepare($sql, $args), ARRAY_A);
         foreach ($rows as $r) {
             $id = (int)$r['product_id']; if (!isset($out[$id])) continue;
@@ -662 +10122 @@
         $event_args = array_merge([$event_since, $event_since], $ids);
         // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Query is prepared with all variable values; table name is a class property built from the WordPress table prefix and fixed suffix; event counts must be current.
-        $event_rows = $wpdb->get_results($wpdb->prepare($event_sql, $event_args), ARRAY_A);
+        $event_rows = statpl_db_get_results(statpl_db_prepare($event_sql, $event_args), ARRAY_A);
         foreach ($event_rows as $event_row) {
             $id = (int)$event_row['product_id'];
@@ -686 +10146 @@
         $summary = [
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- This dashboard aggregate is cached by global_summary_metrics() for 60 seconds and invalidated when relevant data changes.
-            'products' => (int) $wpdb->get_var("SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_type='product' AND post_status IN ('publish','private','draft','pending')"),
+            'products' => (int) statpl_db_get_var("SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_type='product' AND post_status IN ('publish','private','draft','pending')"),
             'views' => 0, 'views24' => 0, 'orders' => 0, 'orders24' => 0,
             'units' => 0.0, 'units24' => 0.0, 'revenue' => 0.0, 'revenue24' => 0.0,
@@ -694 +10154 @@
         // All product views are recorded and aggregated by Statora Plus.
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is constructor-generated from the WordPress prefix and a fixed suffix; the dashboard aggregate is cached for 60 seconds and view recording invalidates that cache.
-        $summary['views'] = (int) $wpdb->get_var("SELECT COALESCE(SUM(total_views),0) FROM {$this->views_table}");
+        $summary['views'] = (int) statpl_db_get_var("SELECT COALESCE(SUM(total_views),0) FROM {$this->views_table}");
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; the date value is prepared.
-        $summary['views24'] = (int) $wpdb->get_var(
-            $wpdb->prepare(
+        $summary['views24'] = (int) statpl_db_get_var(
+            statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; the date value is prepared.
                 "SELECT COUNT(*) FROM {$this->events_table} WHERE viewed_at >= %s",
@@ -707 +10167 @@
         // phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- SQL identifiers cannot be bound as value placeholders; the identifier is internal, not user-controlled.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- This aggregate is cached by global_summary_metrics() for 60 seconds and invalidated on relevant changes.
-        $sales = $wpdb->get_row($wpdb->prepare("SELECT
+        $sales = statpl_db_get_row(statpl_db_prepare("SELECT
             COALESCE(SUM(CASE WHEN statpl_snapshot.order_status='completed' AND statpl_snapshot.completed_at IS NOT NULL THEN statpl_snapshot.net_quantity ELSE 0 END),0) AS units_total,
             COALESCE(SUM(CASE WHEN statpl_snapshot.order_status='completed' AND statpl_snapshot.completed_at >= %s THEN statpl_snapshot.net_quantity ELSE 0 END),0) AS units24,
@@ -723 +10183 @@
         // Product-level detail is calculated separately from rows with actual product IDs.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; no user-supplied SQL values are used.
-        $event_totals = $wpdb->get_row(
+        $event_totals = statpl_db_get_row(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; this aggregate has no user-supplied SQL values.
             "SELECT COUNT(DISTINCT CASE WHEN event_type='cancelled' AND product_id=0 THEN order_id END) AS cancelled_total, COUNT(DISTINCT CASE WHEN event_type='refund' AND product_id=0 AND event_ref_id > 0 THEN event_ref_id END) AS refunds_total FROM {$this->order_events_table}",
@@ -734 +10194 @@
         // Every normal order is represented once per product in the snapshot; count order IDs only once.
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is constructor-generated from the WordPress prefix and a fixed suffix.; Table identifier is internally generated from the WordPress prefix and a fixed suffix.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['total_orders'] = (int) $wpdb->get_var("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table}");
+        $summary['total_orders'] = (int) statpl_db_get_var("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table}");
         // Clean orders are currently processing/completed and retain some non-refunded product quantity/value.
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is constructor-generated from the WordPress prefix and a fixed suffix.; Table identifier is internally generated from the WordPress prefix and a fixed suffix.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['orders'] = (int) $wpdb->get_var("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table} WHERE order_status IN ('processing','completed') AND (net_quantity > 0 OR net_revenue > 0)");
+        $summary['orders'] = (int) statpl_db_get_var("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table} WHERE order_status IN ('processing','completed') AND (net_quantity > 0 OR net_revenue > 0)");
         // Today's clean orders are based on order creation date, not payment/completion date.
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is internally generated; date value is prepared.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['orders24'] = (int) $wpdb->get_var($wpdb->prepare("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table} WHERE order_status IN ('processing','completed') AND created_at >= %s AND (net_quantity > 0 OR net_revenue > 0)", $since));
+        $summary['orders24'] = (int) statpl_db_get_var(statpl_db_prepare("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table} WHERE order_status IN ('processing','completed') AND created_at >= %s AND (net_quantity > 0 OR net_revenue > 0)", $since));
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is internally generated; date value is prepared.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['cancelled24'] = (int) $wpdb->get_var($wpdb->prepare("SELECT COUNT(DISTINCT order_id) FROM {$this->order_events_table} WHERE product_id=0 AND event_type='cancelled' AND event_at >= %s", $since));
+        $summary['cancelled24'] = (int) statpl_db_get_var(statpl_db_prepare("SELECT COUNT(DISTINCT order_id) FROM {$this->order_events_table} WHERE product_id=0 AND event_type='cancelled' AND event_at >= %s", $since));
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is internally generated; date value is prepared.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['refunds24'] = (int) $wpdb->get_var($wpdb->prepare("SELECT COUNT(DISTINCT event_ref_id) FROM {$this->order_events_table} WHERE product_id=0 AND event_type='refund' AND event_ref_id > 0 AND event_at >= %s", $since));
+        $summary['refunds24'] = (int) statpl_db_get_var(statpl_db_prepare("SELECT COUNT(DISTINCT event_ref_id) FROM {$this->order_events_table} WHERE product_id=0 AND event_type='refund' AND event_ref_id > 0 AND event_at >= %s", $since));
         $summary['revenue'] = round($summary['revenue'], wc_get_price_decimals());
         $summary['revenue24'] = round($summary['revenue24'], wc_get_price_decimals());
@@ -829 +10289 @@
                         SELECT product_id, COUNT(*) AS views_today
                         FROM {$this->events_table}
-                        WHERE viewed_at >= " . $wpdb->prepare('%s', $since_mysql) . "
+                        WHERE viewed_at >= " . statpl_db_prepare('%s', $since_mysql) . "
                         GROUP BY product_id
                     ) recent ON recent.product_id = totals.product_id
@@ -837 +10297 @@
                     SELECT product_id, COUNT(*) AS views_today
                     FROM {$this->events_table}
-                    WHERE viewed_at >= " . $wpdb->prepare('%s', $since_mysql) . "
+                    WHERE viewed_at >= " . statpl_db_prepare('%s', $since_mysql) . "
                     GROUP BY product_id
                 ) statpl_recent_views ON statpl_recent_views.product_id = p.ID";
@@ -849 +10309 @@
                     SELECT product_id,
                         COUNT(DISTINCT CASE WHEN order_status IN ('processing','completed') AND (net_quantity > 0 OR net_revenue > 0) THEN order_id END) AS orders,
-                        COUNT(DISTINCT CASE WHEN order_status IN ('processing','completed') AND created_at >= " . $wpdb->prepare('%s', $since) . " AND (net_quantity > 0 OR net_revenue > 0) THEN order_id END) AS orders24,
+                        COUNT(DISTINCT CASE WHEN order_status IN ('processing','completed') AND created_at >= " . statpl_db_prepare('%s', $since) . " AND (net_quantity > 0 OR net_revenue > 0) THEN order_id END) AS orders24,
                         SUM(CASE WHEN order_status='completed' AND completed_at IS NOT NULL THEN net_quantity ELSE 0 END) AS units,
-                        SUM(CASE WHEN order_status='completed' AND completed_at >= " . $wpdb->prepare('%s', $since) . " THEN net_quantity ELSE 0 END) AS units24,
+                        SUM(CASE WHEN order_status='completed' AND completed_at >= " . statpl_db_prepare('%s', $since) . " THEN net_quantity ELSE 0 END) AS units24,
                         SUM(CASE WHEN order_status='completed' AND completed_at IS NOT NULL THEN net_revenue ELSE 0 END) AS revenue,
-                        SUM(CASE WHEN order_status='completed' AND completed_at >= " . $wpdb->prepare('%s', $since) . " THEN net_revenue ELSE 0 END) AS revenue24
+                        SUM(CASE WHEN order_status='completed' AND completed_at >= " . statpl_db_prepare('%s', $since) . " THEN net_revenue ELSE 0 END) AS revenue24
                     FROM {$this->order_items_table} GROUP BY product_id
                 ) statpl_orders ON statpl_orders.product_id = p.ID
@@ -859 +10319 @@
                     SELECT product_id,
                         COUNT(DISTINCT CASE WHEN event_type='cancelled' THEN order_id END) AS cancelled,
-                        COUNT(DISTINCT CASE WHEN event_type='cancelled' AND event_at >= " . $wpdb->prepare('%s', $since) . " THEN order_id END) AS cancelled24,
+                        COUNT(DISTINCT CASE WHEN event_type='cancelled' AND event_at >= " . statpl_db_prepare('%s', $since) . " THEN order_id END) AS cancelled24,
                         COUNT(DISTINCT CASE WHEN event_type='refund' AND event_ref_id > 0 THEN event_ref_id END) AS refunds,
-                        COUNT(DISTINCT CASE WHEN event_type='refund' AND event_ref_id > 0 AND event_at >= " . $wpdb->prepare('%s', $since) . " THEN event_ref_id END) AS refunds24
+                        COUNT(DISTINCT CASE WHEN event_type='refund' AND event_ref_id > 0 AND event_at >= " . statpl_db_prepare('%s', $since) . " THEN event_ref_id END) AS refunds24
                     FROM {$this->order_events_table} GROUP BY product_id
                 ) statpl_events ON statpl_events.product_id = p.ID";
@@ -869 +10329 @@
             // $join and $where are assembled only from fixed SQL fragments and prepared placeholders; user input is passed in $args.
             // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Query fragments are plugin-controlled; all user-supplied values are bound through prepare(); product filters are evaluated live.
-            $total = (int) $wpdb->get_var($wpdb->prepare($count_sql, $args));
+            $total = (int) statpl_db_get_var(statpl_db_prepare($count_sql, $args));
             $order_column = $order_columns[$orderby] ?? 'p.post_title';
             $pages_for_query = max(1, (int) ceil($total / $per_page));
@@ -878 +10338 @@
             // $order_column is selected from the internal allowlist and $order is normalized before query construction.
             // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Query fragments are plugin-controlled; all user-supplied values are bound through prepare(); product filters are evaluated live.
-            $product_ids = array_map('intval', $wpdb->get_col($wpdb->prepare($id_sql, $id_args)));
+            $product_ids = array_map('intval', statpl_db_get_col(statpl_db_prepare($id_sql, $id_args)));
         } else {
             $base_args = ['post_type'=>'product','post_status'=>$statuses,'posts_per_page'=>-1,'fields'=>'ids','orderby'=>'ID','order'=>'ASC'];
@@ -891 +10351 @@
 if (false === $sku_ids) {
     // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery -- Prepared partial-SKU lookup is required; results are cached for 60 seconds.
-    $sku_ids = $wpdb->get_col(
-        $wpdb->prepare(
+    $sku_ids = statpl_db_get_col(
+        statpl_db_prepare(
     "SELECT DISTINCT p.ID
     FROM {$wpdb->posts} p
@@ -928 +10388 @@
             $st = $stats_by_product[$product_id] ?? ['orders'=>0,'orders24'=>0,'units'=>0,'units24'=>0,'revenue'=>0.0,'revenue24'=>0.0,'cancelled'=>0,'cancelled24'=>0,'refunds'=>0,'refunds24'=>0];
             $stock_summary = $this->stock_summary_for_product($product);
+            $product_status = get_post_status($product_id);
+            $visibility_labels = [
+                'private' => 'Κρυφό',
+                'draft' => 'Πρόχειρο',
+                'pending' => 'Σε αναμονή',
+            ];
             $rows[] = ['id'=>$product_id,'title'=>$product->get_name(),'date'=>get_post_field('post_date',$product_id),'sku'=>$product->get_sku(),
-                'views'=>(int)$views['total'],'views24'=>(int)$views['today'],'source'=>$views['source'],'stock_managed'=>$stock_summary['managed'],'stock'=>$stock_summary['quantity'],'edit_url'=>get_edit_post_link($product_id, 'raw')] + $st;
+                'product_visibility'=>$visibility_labels[$product_status] ?? '',
+                'views'=>(int)$views['total'],'views24'=>(int)$views['today'],'source'=>$views['source'],'stock_managed'=>$stock_summary['managed'],'stock'=>$stock_summary['quantity'],'stock_in_stock'=>$stock_summary['in_stock'],'edit_url'=>get_edit_post_link($product_id, 'raw')] + $st;
         }
         if (!$db_paged) {
@@ -945 +10412 @@
         $summary = $this->global_summary_metrics();
 
-        echo '<div class="wrap statpl-metrics-wrap"><h1>Statora Plus</h1><p class="description">Στατιστικά προϊόντων WooCommerce σε μία συνοπτική εικόνα.</p>';
+        echo '<div class="wrap statpl-metrics-wrap"><h1>Statora Plus</h1>';
         $overview_url = add_query_arg(['page'=>'statpl-product-metrics','view'=>'overview'], admin_url('admin.php'));
         $products_url = add_query_arg(['page'=>'statpl-product-metrics','view'=>'products'], admin_url('admin.php'));
         echo '<nav class="nav-tab-wrapper"><a class="nav-tab '.($view === 'overview' ? 'nav-tab-active' : '').'" href="'.esc_url($overview_url).'">Συνολική εικόνα</a><a class="nav-tab '.($view === 'products' ? 'nav-tab-active' : '').'" href="'.esc_url($products_url).'">Στατιστικά ανά προϊόν</a></nav>';
 
-        if (get_option('statpl_import_complete')) {
-            echo '<div class="notice notice-success inline"><p>Η αρχική εισαγωγή ιστορικού έχει επισημανθεί ως ολοκληρωμένη.</p></div>';
-        } else {
-            $import_page = max(1, (int) get_option('statpl_import_page', 1));
-            echo '<div class="notice notice-info inline"><p>Η αρχική εισαγωγή ιστορικού εκτελείται στο παρασκήνιο. Επεξεργασία παρτίδας: '.esc_html((string)$import_page).'. Τα στατιστικά ενδέχεται να είναι ελλιπή μέχρι να ολοκληρωθεί.</p></div>';
-        }
+        $this->render_historical_import_notice();
         if ($view === 'overview') {
             echo '<h2>Συνολικά στατιστικά καταστήματος</h2>'; 
@@ -1006 +10468 @@
         if (!$visible_rows) echo '<tr><td colspan="14">Δεν βρέθηκαν προϊόντα.</td></tr>';
         foreach ($visible_rows as $r) {
-            echo '<tr><td><a class="statpl-product-title" href="'.esc_url($r['edit_url']).'">'.esc_html($r['title']).'</a></td>';
-            echo '<td>'.($r['stock_managed'] ? esc_html(number_format_i18n($r['stock'])) : '<span class="statpl-stock-not-tracked">Δεν παρακολουθείται</span>').'</td>';
+            echo '<tr><td><a class="statpl-product-title" href="'.esc_url($r['edit_url']).'">'.esc_html($r['title']).'</a>';
+            if (!empty($r['product_visibility'])) {
+                echo ' <span class="statpl-product-visibility">'.esc_html($r['product_visibility']).'</span>';
+            }
+            echo '</td>';
+            if ($r['stock_managed']) {
+                $stock_quantity = (float) $r['stock'];
+                if ($stock_quantity > 0) {
+                    echo '<td>'.esc_html(number_format_i18n($stock_quantity)).'</td>';
+                } elseif (!empty($r['stock_in_stock'])) {
+                    // Zero quantity with backorders allowed remains purchasable.
+                    echo '<td>0</td>';
+                } else {
+                    echo '<td>Εξαντλημένο</td>';
+                }
+            } else {
+                echo '<td><span class="statpl-stock-not-tracked">Δεν γίνεται διαχείριση αποθέματος</span></td>';
+            }
             echo '<td>'.esc_html(number_format_i18n($r['views'])).'</td><td>'.esc_html(number_format_i18n($r['views24'])).'</td>';
             foreach (['orders','orders24'] as $k) echo '<td>'.esc_html(number_format_i18n($r[$k])).'</td>';
@@ -1022 +10500 @@
 }
 STATPL_Core::instance();
+
+
+/**
+ * Page View Count adapter.
+ *
+ * Reads only the provider's immutable, per-product daily rows from pvc_daily.
+ * The current day is intentionally excluded because Page View Count updates
+ * that row in place; importing a mutable count would violate the immutable
+ * source snapshot contract. Lifetime totals in pvc_total are deliberately not
+ * imported because they overlap the daily rows and have no date boundaries.
+ */
+if (!class_exists('STATPL_Page_View_Count_Historical_Adapter')) {
+    final class STATPL_Page_View_Count_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'page_view_count';
+        const SOURCE_KEY = 'page_view_count';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'daily_product_views';
+
+        public function get_adapter_key() {
+            return self::ADAPTER_KEY;
+        }
+
+        public function get_source_key() {
+            return self::SOURCE_KEY;
+        }
+
+        public function get_display_name() {
+            return 'Page Views Count';
+        }
+
+        public function get_adapter_version() {
+            return self::ADAPTER_VERSION;
+        }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'pvc_daily';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- SHOW TABLES LIKE has one %s placeholder and receives exactly one escaped table-name value.
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) {
+                return ['status' => 'database_error', 'error' => (string) $wpdb->last_error];
+            }
+            if ($exists !== $table) {
+                return ['status' => 'missing_table'];
+            }
+
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- SHOW COLUMNS contains no value placeholders; the table identifier is validated and quoted by quoted_table_name().
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) {
+                return ['status' => 'database_error', 'error' => (string) $wpdb->last_error];
+            }
+            $names = [];
+            foreach ($columns as $column) {
+                if (isset($column['Field'])) {
+                    $names[] = (string) $column['Field'];
+                }
+            }
+            $required = ['id', 'time', 'postnum', 'postcount'];
+            if (array_diff($required, $names)) {
+                return ['status' => 'incompatible_schema'];
+            }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') {
+                // A previously registered source can be marked unavailable by the
+                // core's authoritative inventory reconciliation if its table was
+                // removed. A never-installed source is not registered needlessly.
+                return [];
+            }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => [
+                    'product_views' => true,
+                    'granularity' => 'daily_aggregate',
+                    'immutable_past_days' => true,
+                ],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) {
+                return [];
+            }
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'available') {
+                throw new RuntimeException('Page View Count source table is not available or has an incompatible schema.');
+            }
+
+            $through_date = current_datetime()->modify('-1 day')->format('Y-m-d');
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(d.id)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS d
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p
+                   ON p.ID = CAST(d.postnum AS UNSIGNED)
+                  AND p.post_type = %s
+                 WHERE d.postnum REGEXP %s AND d.time <= %s',
+                'product',
+                '^[0-9]+$',
+                $through_date
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Page View Count snapshot query failed.');
+            }
+
+            return [
+                'boundary' => [
+                    'max_id' => max(0, (int) $max_id),
+                    'through_date' => $through_date,
+                ],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Page View Count origin or snapshot.');
+            }
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'available') {
+                throw new RuntimeException('Page View Count source table became unavailable or incompatible.');
+            }
+
+            $boundary = $snapshot['boundary'];
+            $max_id = isset($boundary['max_id']) ? absint($boundary['max_id']) : -1;
+            $through_date = isset($boundary['through_date']) ? (string) $boundary['through_date'] : '';
+            $date = DateTime::createFromFormat('!Y-m-d', $through_date);
+            if ($max_id < 0 || !$date || $date->format('Y-m-d') !== $through_date) {
+                throw new RuntimeException('Invalid Page View Count snapshot boundary.');
+            }
+
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_value = $checkpoint['cursor'];
+                if ($cursor_value !== null) {
+                    $cursor_id = absint($cursor_value);
+                }
+            } elseif (is_numeric($checkpoint)) {
+                $cursor_id = absint($checkpoint);
+            }
+
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT MAX(d.id) AS id, d.time, d.postnum, SUM(d.postcount) AS postcount
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS d
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p
+                   ON p.ID = CAST(d.postnum AS UNSIGNED)
+                  AND p.post_type = %s
+                 WHERE d.postnum REGEXP %s
+                   AND d.id <= %d
+                   AND d.time <= %s
+                 GROUP BY d.time, d.postnum
+                 HAVING MAX(d.id) > %d
+                 ORDER BY MAX(d.id) ASC
+                 LIMIT %d',
+                'product',
+                '^[0-9]+$',
+                $max_id,
+                $through_date,
+                $cursor_id,
+                $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Page View Count batch query failed.');
+            }
+
+            $has_more = count($rows) > $limit;
+            if ($has_more) {
+                $rows = array_slice($rows, 0, $limit);
+            }
+            $next_checkpoint = $cursor_id;
+            if ($rows) {
+                $last = end($rows);
+                $next_checkpoint = absint($last['id']);
+            }
+
+            return [
+                'rows' => array_values($rows),
+                'has_more' => $has_more,
+                'next_checkpoint' => $next_checkpoint,
+                'boundary_applied' => true,
+            ];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) {
+                return null;
+            }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_raw = isset($record['postnum']) ? (string) $record['postnum'] : '';
+            $views_raw = $record['postcount'] ?? null;
+            $date = isset($record['time']) ? (string) $record['time'] : '';
+            if (!$record_id || !preg_match('/^[1-9][0-9]*$/D', $product_raw) || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) {
+                return null;
+            }
+            $parsed_date = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed_date || $parsed_date->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) {
+                return null;
+            }
+
+            $product_id = (int) $product_raw;
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'pvc_daily_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => $record_id,
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) {
+        return $adapters;
+    }
+    $adapter = new STATPL_Page_View_Count_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 30);
+
+/**
+ * WP Statistics adapter.
+ *
+ * Imports daily rows from statistics_pages where WP Statistics has explicitly
+ * classified the viewed resource as a WooCommerce product. The historical
+ * summary table is not read here: it no longer preserves a trustworthy date
+ * interval after detailed rows have been aggregated.
+ */
+if (!class_exists('STATPL_WP_Statistics_Historical_Adapter')) {
+    final class STATPL_WP_Statistics_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'wp_statistics_pages';
+        const SOURCE_KEY = 'wp_statistics';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_daily_pages';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'WP Statistics'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'statistics_pages';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) {
+                return ['status' => 'database_error', 'error' => (string) $wpdb->last_error];
+            }
+            if ($exists !== $table) {
+                return ['status' => 'missing_table'];
+            }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) {
+                return ['status' => 'database_error', 'error' => (string) $wpdb->last_error];
+            }
+            $names = [];
+            foreach ($columns as $column) {
+                if (isset($column['Field'])) { $names[] = (string) $column['Field']; }
+            }
+            if (array_diff(['page_id', 'uri', 'type', 'date', 'count', 'id'], $names)) {
+                return ['status' => 'incompatible_schema'];
+            }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'immutable_past_days' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('WP Statistics pages table is unavailable or incompatible.');
+            }
+            $through_date = current_datetime()->modify('-1 day')->format('Y-m-d');
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(s.page_id)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.id AND p.post_type = %s
+                 WHERE s.type = %s AND s.date <= %s',
+                'product', 'product', $through_date
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('WP Statistics snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_page_id' => max(0, (int) $max_id), 'through_date' => $through_date],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid WP Statistics origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('WP Statistics pages table became unavailable or incompatible.');
+            }
+            $boundary = $snapshot['boundary'];
+            $max_id = isset($boundary['max_page_id']) ? absint($boundary['max_page_id']) : -1;
+            $through_date = isset($boundary['through_date']) ? (string) $boundary['through_date'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+            if ($max_id < 0 || !$parsed || $parsed->format('Y-m-d') !== $through_date) {
+                throw new RuntimeException('Invalid WP Statistics snapshot boundary.');
+            }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) {
+                $cursor_id = absint($checkpoint);
+            }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT MAX(s.page_id) AS page_id, s.date, SUM(s.count) AS count, s.id
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.id AND p.post_type = %s
+                 WHERE s.type = %s AND s.page_id <= %d AND s.date <= %s
+                 GROUP BY s.date, s.id
+                 HAVING MAX(s.page_id) > %d
+                 ORDER BY MAX(s.page_id) ASC
+                 LIMIT %d',
+                'product', 'product', $max_id, $through_date, $cursor_id, $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('WP Statistics batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['page_id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['page_id']) ? absint($record['page_id']) : 0;
+            $product_id = isset($record['id']) ? absint($record['id']) : 0;
+            $views_raw = $record['count'] ?? null;
+            $date = isset($record['date']) ? (string) $record['date'] : '';
+            if (!$record_id || !$product_id || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'wp_statistics_product_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => $record_id,
+            ];
+        }
+    }
+}
+
+/**
+ * Post Views Counter adapter.
+ *
+ * Reads only type=0 daily rows from wp_post_views. Week, month, year and total
+ * rows are deliberately excluded because they are overlapping rollups of the
+ * same views. Past-day rows are used so the source counts are stable while the
+ * importer runs; today's row is still mutable and is left to live tracking.
+ */
+if (!class_exists('STATPL_Post_Views_Counter_Historical_Adapter')) {
+    final class STATPL_Post_Views_Counter_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'post_views_counter';
+        const SOURCE_KEY = 'post_views_counter';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'daily_product_views';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Post Views Counter'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'post_views';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = (string) $column['Field']; } }
+            if (array_diff(['id', 'type', 'period', 'count'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'immutable_past_days' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Post Views Counter table is unavailable or incompatible.');
+            }
+            $through_date = current_datetime()->modify('-1 day')->format('Ymd');
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- The query has four fixed value placeholders and receives four values; the two table identifiers are independently validated SQL identifiers.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_period = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(v.period)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS v
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = v.id AND p.post_type = %s
+                 WHERE v.type = %d AND v.period REGEXP %s AND v.period <= %s',
+                'product', 0, '^[0-9]{8}$', $through_date
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Post Views Counter snapshot query failed.');
+            }
+            if (!is_string($max_period) || !preg_match('/^[0-9]{8}$/D', $max_period)) { $max_period = ''; }
+            return [
+                'boundary' => ['max_period' => $max_period],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Post Views Counter origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Post Views Counter table became unavailable or incompatible.');
+            }
+            $max_period = isset($snapshot['boundary']['max_period']) ? (string) $snapshot['boundary']['max_period'] : '';
+            if ($max_period !== '' && !preg_match('/^[0-9]{8}$/D', $max_period)) { throw new RuntimeException('Invalid Post Views Counter snapshot boundary.'); }
+            $cursor_period = '';
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor']) && is_array($checkpoint['cursor'])) {
+                $cursor_period = isset($checkpoint['cursor']['period']) ? (string) $checkpoint['cursor']['period'] : '';
+                $cursor_id = isset($checkpoint['cursor']['id']) ? absint($checkpoint['cursor']['id']) : 0;
+            }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+            if ($max_period === '') { $rows = []; }
+            else {
+                $cursor_sql = '';
+                $args = ['product', 0, '^[0-9]{8}$', $max_period];
+                if ($cursor_period !== '') {
+                    if (!preg_match('/^[0-9]{8}$/D', $cursor_period)) { throw new RuntimeException('Invalid Post Views Counter cursor.'); }
+                    $cursor_sql = ' AND (v.period > %s OR (v.period = %s AND v.id > %d))';
+                    $args[] = $cursor_period;
+                    $args[] = $cursor_period;
+                    $args[] = $cursor_id;
+                }
+                $batch_sql = 'SELECT v.id, v.period, v.count
+                     FROM ' . $this->quoted_table_name() . ' AS v
+                     INNER JOIN ' . $posts_table . ' AS p ON p.ID = v.id AND p.post_type = %s
+                     WHERE v.type = %d AND v.period REGEXP %s AND v.period <= %s' . $cursor_sql . '
+                     ORDER BY v.period ASC, v.id ASC
+                     LIMIT %d';
+                if ($cursor_period !== '') {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                    $rows = statpl_db_get_results(statpl_db_prepare(
+                        /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                        'product', 0, '^[0-9]{8}$', $max_period,
+                        $cursor_period, $cursor_period, $cursor_id, $limit + 1
+                    ), ARRAY_A);
+                } else {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                    $rows = statpl_db_get_results(statpl_db_prepare(
+                        /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                        'product', 0, '^[0-9]{8}$', $max_period, $limit + 1
+                    ), ARRAY_A);
+                }
+            }
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Post Views Counter batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = ($cursor_period !== '') ? ['period' => $cursor_period, 'id' => $cursor_id] : null;
+            if ($rows) { $last = end($rows); $next = ['period' => (string) $last['period'], 'id' => absint($last['id'])]; }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $product_id = isset($record['id']) ? absint($record['id']) : 0;
+            $period = isset($record['period']) ? (string) $record['period'] : '';
+            $views_raw = $record['count'] ?? null;
+            if (!$product_id || !preg_match('/^[0-9]{8}$/D', $period) || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Ymd', $period);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Ymd') !== $period || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $date = $parsed->format('Y-m-d');
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'post_views_counter_day_' . $period . '_' . $product_id,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => ['period' => $period, 'id' => $product_id],
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $wp_statistics = new STATPL_WP_Statistics_Historical_Adapter();
+    if ($wp_statistics->should_register_adapter()) { $adapters[] = $wp_statistics; }
+    $post_views_counter = new STATPL_Post_Views_Counter_Historical_Adapter();
+    if ($post_views_counter->should_register_adapter()) { $adapters[] = $post_views_counter; }
+    return $adapters;
+}, 31);
+
+/**
+ * Statify adapter.
+ *
+ * Statify stores one immutable row per page view, but its schema contains only
+ * a calendar date and target URL (not a timestamp or WordPress post ID). The
+ * adapter resolves same-site targets to published WooCommerce products and
+ * explicitly skips non-product rows. It does not issue cross-source fingerprints:
+ * a date-only row cannot be safely matched one-to-one against another provider's
+ * event stream without risking suppression of legitimate repeat views.
+ */
+if (!class_exists('STATPL_Statify_Historical_Adapter')) {
+    final class STATPL_Statify_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'statify';
+        const SOURCE_KEY = 'statify';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'page_view_events';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Statify'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'statify';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = (string) $column['Field']; } }
+            if (array_diff(['id', 'created', 'referrer', 'target'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'event_date_only', 'target_requires_product_resolution' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Statify table is unavailable or incompatible.');
+            }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var('SELECT MAX(id) FROM ' . $this->quoted_table_name());
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Statify snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_id' => max(0, (int) $max_id)],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Statify origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Statify table became unavailable or incompatible.');
+            }
+            $max_id = isset($snapshot['boundary']['max_id']) ? absint($snapshot['boundary']['max_id']) : -1;
+            if ($max_id < 0) { throw new RuntimeException('Invalid Statify snapshot boundary.'); }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && array_key_exists('cursor', $checkpoint)) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) {
+                $cursor_id = absint($checkpoint);
+            }
+            $limit = max(1, min(100, absint($limit)));
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT id, created, referrer, target
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . '
+                 WHERE id > %d AND id <= %d
+                 ORDER BY id ASC
+                 LIMIT %d',
+                $cursor_id,
+                $max_id,
+                $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Statify batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        private function resolve_product_id($target) {
+            if (!is_string($target) || trim($target) === '' || !function_exists('url_to_postid')) { return 0; }
+            $target = trim($target);
+            if (preg_match('#^https?://#i', $target)) {
+                $url = $target;
+            } elseif (strpos($target, '//') === 0) {
+                return 0;
+            } else {
+                $url = home_url('/' . ltrim($target, '/'));
+            }
+            $target_host = strtolower((string) wp_parse_url($url, PHP_URL_HOST));
+            $home_host = strtolower((string) wp_parse_url(home_url('/'), PHP_URL_HOST));
+            if ($target_host === '' || $home_host === '' || $target_host !== $home_host) { return 0; }
+            $product_id = absint(url_to_postid($url));
+            if (!$product_id || get_post_type($product_id) !== 'product') { return 0; }
+            return $product_id;
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $record_key = $record_id ? 'statify_view_' . $record_id : '';
+            $cursor = $record_id;
+            if (!$record_id) { return null; }
+            $date = isset($record['created']) ? (string) $record['created'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) {
+                return null;
+            }
+            $product_id = $this->resolve_product_id(isset($record['target']) ? (string) $record['target'] : '');
+            if (!$product_id) {
+                return ['skip' => true, 'source_record_key' => $record_key, 'cursor' => $cursor];
+            }
+            $referrer = isset($record['referrer']) ? (string) $record['referrer'] : '';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => $record_key,
+                'views' => 1,
+                'record_type' => 'event',
+                'period_start' => $date . ' 00:00:00',
+                'period_end' => $date . ' 23:59:59',
+                'cursor' => $cursor,
+                'source_referrer_hash' => hash('sha256', $referrer),
+            ];
+        }
+
+        public function get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event) {
+            return [
+                'source' => 'statify',
+                'date_precision' => 'calendar_day_only',
+                'referrer_sha256' => isset($normalized_record['source_referrer_hash']) ? $normalized_record['source_referrer_hash'] : null,
+                'overlap_assessment' => 'possible_but_not_proven',
+                'automatic_suppression' => false,
+                'reason' => 'Statify has no per-view timestamp or stable cross-provider event identifier; a one-to-one match would risk suppressing legitimate repeat views.',
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Statify_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 32);
+
+/**
+ * WP Popular Posts adapter.
+ *
+ * Imports the per-post/per-day summary table only. The all-time data table is
+ * deliberately excluded because it overlaps the daily summary and carries no
+ * date range. WPP's configurable log retention determines how much daily
+ * history remains available at the time Statora captures its snapshot.
+ */
+if (!class_exists('STATPL_WP_Popular_Posts_Historical_Adapter')) {
+    final class STATPL_WP_Popular_Posts_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'wp_popular_posts';
+        const SOURCE_KEY = 'wp_popular_posts';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_daily_summary';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'WP Popular Posts'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'popularpostssummary';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            if (array_diff(['id', 'postid', 'pageviews', 'view_date', 'last_viewed'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'immutable_past_days' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('WP Popular Posts summary table is unavailable or incompatible.');
+            }
+            $through_date = current_datetime()->modify('-1 day')->format('Y-m-d');
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(s.ID)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.postid AND p.post_type = %s
+                 WHERE s.view_date <= %s',
+                'product', $through_date
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('WP Popular Posts snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_id' => max(0, (int) $max_id), 'through_date' => $through_date],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid WP Popular Posts origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('WP Popular Posts summary table became unavailable or incompatible.');
+            }
+            $boundary = $snapshot['boundary'];
+            $max_id = isset($boundary['max_id']) ? absint($boundary['max_id']) : -1;
+            $through_date = isset($boundary['through_date']) ? (string) $boundary['through_date'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+            if ($max_id < 0 || !$parsed || $parsed->format('Y-m-d') !== $through_date) {
+                throw new RuntimeException('Invalid WP Popular Posts snapshot boundary.');
+            }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) { $cursor_id = absint($checkpoint); }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT s.ID AS id, s.postid, s.pageviews, s.view_date
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.postid AND p.post_type = %s
+                 WHERE s.ID > %d AND s.ID <= %d AND s.view_date <= %s
+                 ORDER BY s.ID ASC
+                 LIMIT %d',
+                'product', $cursor_id, $max_id, $through_date, $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('WP Popular Posts batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_id = isset($record['postid']) ? absint($record['postid']) : 0;
+            $views_raw = $record['pageviews'] ?? null;
+            $date = isset($record['view_date']) ? (string) $record['view_date'] : '';
+            if (!$record_id || !$product_id || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'wp_popular_posts_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => $record_id,
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_WP_Popular_Posts_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 33);
+
+/**
+ * WebberZone Top 10 adapter.
+ *
+ * Imports only the per-post hourly rows from top_ten_daily, grouped into local
+ * calendar-day totals. The all-time table, visits funnel and visits log are not
+ * imported in parallel: the funnel/log feed the same daily and lifetime counts.
+ * A two-day safety lag allows Top 10's background aggregation cron to drain
+ * completed days before the snapshot is taken.
+ */
+if (!class_exists('STATPL_Top_Ten_Historical_Adapter')) {
+    final class STATPL_Top_Ten_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'webberzone_top_10';
+        const SOURCE_KEY = 'webberzone_top_10';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_daily_counts';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'WebberZone Top 10'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->base_prefix . 'top_ten_daily';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            if (array_diff(['postnumber', 'cntaccess', 'dp_date', 'blog_id'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available', 'has_feed_column' => in_array('feedcnt', $names, true)];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'source_storage_granularity' => 'hourly', 'immutable_past_days' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Top 10 daily table is unavailable or incompatible.');
+            }
+            $through_date = current_datetime()->modify('-2 days')->format('Y-m-d');
+            return [
+                'boundary' => ['through_date' => $through_date, 'blog_id' => absint(get_current_blog_id())],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Top 10 origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Top 10 daily table became unavailable or incompatible.');
+            }
+            $through_date = isset($snapshot['boundary']['through_date']) ? (string) $snapshot['boundary']['through_date'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+            $blog_id = isset($snapshot['boundary']['blog_id']) ? absint($snapshot['boundary']['blog_id']) : 0;
+            if (!$parsed || $parsed->format('Y-m-d') !== $through_date || !$blog_id) {
+                throw new RuntimeException('Invalid Top 10 snapshot boundary.');
+            }
+            $cursor_date = '';
+            $cursor_product = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor']) && is_array($checkpoint['cursor'])) {
+                $cursor_date = isset($checkpoint['cursor']['date']) ? (string) $checkpoint['cursor']['date'] : '';
+                $cursor_product = isset($checkpoint['cursor']['product_id']) ? absint($checkpoint['cursor']['product_id']) : 0;
+            }
+            if ($cursor_date !== '' && (!preg_match('/^\d{4}-\d{2}-\d{2}$/D', $cursor_date) || !DateTime::createFromFormat('!Y-m-d', $cursor_date))) {
+                throw new RuntimeException('Invalid Top 10 cursor date.');
+            }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+            $inspection = $this->inspect_table();
+            $view_sum_sql = !empty($inspection['has_feed_column'])
+                ? 'SUM(GREATEST(t.cntaccess - t.feedcnt, 0))'
+                : 'SUM(t.cntaccess)';
+            if (!in_array($view_sum_sql, ['SUM(GREATEST(t.cntaccess - t.feedcnt, 0))', 'SUM(t.cntaccess)'], true)) {
+                throw new RuntimeException('Unsupported Top 10 view aggregation expression.');
+            }
+            $cursor_sql = '';
+            $args = ['product', $blog_id, $through_date];
+            if ($cursor_date !== '') {
+                $cursor_sql = ' HAVING (view_date > %s OR (view_date = %s AND product_id > %d))';
+                $args[] = $cursor_date;
+                $args[] = $cursor_date;
+                $args[] = $cursor_product;
+            }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $view_sum_sql is selected from two fixed aggregate expressions and checked against the same strict allowlist; all runtime values remain prepared placeholders.
+            $batch_sql = 'SELECT DATE(t.dp_date) AS view_date, t.postnumber AS product_id, ' . $view_sum_sql . ' AS views
+                 FROM ' . $this->quoted_table_name() . ' AS t
+                 INNER JOIN ' . $posts_table . ' AS p ON p.ID = t.postnumber AND p.post_type = %s
+                 WHERE t.blog_id = %d AND t.dp_date < DATE_ADD(%s, INTERVAL 1 DAY)
+                 GROUP BY DATE(t.dp_date), t.postnumber' . $cursor_sql . '
+                 ORDER BY view_date ASC, product_id ASC
+                 LIMIT %d';
+            if ($cursor_date !== '') {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                    'product', $blog_id, $through_date,
+                    $cursor_date, $cursor_date, $cursor_product, $limit + 1
+                ), ARRAY_A);
+            } else {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                    'product', $blog_id, $through_date, $limit + 1
+                ), ARRAY_A);
+            }
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Top 10 batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = ($cursor_date !== '') ? ['date' => $cursor_date, 'product_id' => $cursor_product] : null;
+            if ($rows) { $last = end($rows); $next = ['date' => (string) $last['view_date'], 'product_id' => absint($last['product_id'])]; }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $product_id = isset($record['product_id']) ? absint($record['product_id']) : 0;
+            $date = isset($record['view_date']) ? (string) $record['view_date'] : '';
+            $views_raw = $record['views'] ?? null;
+            if (!$product_id || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'top_10_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => ['date' => $date, 'product_id' => $product_id],
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Top_Ten_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 34);
+
+/**
+ * Koko Analytics adapter.
+ *
+ * Reads the per-page daily statistics table. Current Koko schemas use path_id
+ * and post_id; older schemas used id directly as the WordPress post ID. Rows
+ * are grouped by product/date because one product can be represented by more
+ * than one canonicalized path. Only completed days are imported.
+ */
+if (!class_exists('STATPL_Koko_Analytics_Historical_Adapter')) {
+    final class STATPL_Koko_Analytics_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'koko_analytics';
+        const SOURCE_KEY = 'koko_analytics';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_daily_stats';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Koko Analytics'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'koko_analytics_post_stats';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            if (!in_array('date', $names, true) || !in_array('pageviews', $names, true)) { return ['status' => 'incompatible_schema']; }
+            if (in_array('post_id', $names, true) && in_array('path_id', $names, true)) {
+                return ['status' => 'available', 'schema_mode' => 'path_id'];
+            }
+            if (in_array('id', $names, true)) {
+                return ['status' => 'available', 'schema_mode' => 'legacy_post_id'];
+            }
+            return ['status' => 'incompatible_schema'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'schema_mode' => isset($inspection['schema_mode']) ? $inspection['schema_mode'] : 'unknown'],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'available') {
+                throw new RuntimeException('Koko Analytics post statistics table is unavailable or incompatible.');
+            }
+            return [
+                'boundary' => [
+                    'through_date' => current_datetime()->modify('-1 day')->format('Y-m-d'),
+                    'schema_mode' => $inspection['schema_mode'],
+                ],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Koko Analytics origin or snapshot.');
+            }
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'available') {
+                throw new RuntimeException('Koko Analytics post statistics table became unavailable or incompatible.');
+            }
+            $boundary = $snapshot['boundary'];
+            $through_date = isset($boundary['through_date']) ? (string) $boundary['through_date'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+            $schema_mode = isset($boundary['schema_mode']) ? (string) $boundary['schema_mode'] : '';
+            if (!$parsed || $parsed->format('Y-m-d') !== $through_date || $schema_mode !== $inspection['schema_mode']) {
+                throw new RuntimeException('Invalid or changed Koko Analytics snapshot boundary.');
+            }
+            $cursor_date = '';
+            $cursor_product = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor']) && is_array($checkpoint['cursor'])) {
+                $cursor_date = isset($checkpoint['cursor']['date']) ? (string) $checkpoint['cursor']['date'] : '';
+                $cursor_product = isset($checkpoint['cursor']['product_id']) ? absint($checkpoint['cursor']['product_id']) : 0;
+            }
+            if ($cursor_date !== '' && (!preg_match('/^\d{4}-\d{2}-\d{2}$/D', $cursor_date) || !DateTime::createFromFormat('!Y-m-d', $cursor_date))) {
+                throw new RuntimeException('Invalid Koko Analytics cursor date.');
+            }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+            if (!in_array($schema_mode, ['path_id', 'id'], true)) {
+                throw new RuntimeException('Unsupported Koko Analytics schema mode.');
+            }
+            $post_id_column = $schema_mode === 'path_id' ? 's.post_id' : 's.id';
+            if (!in_array($post_id_column, ['s.post_id', 's.id'], true)) {
+                throw new RuntimeException('Unsupported Koko Analytics product identifier column.');
+            }
+            $cursor_sql = '';
+            $args = ['product', $through_date];
+            if ($cursor_date !== '') {
+                $cursor_sql = ' HAVING (view_date > %s OR (view_date = %s AND product_id > %d))';
+                $args[] = $cursor_date;
+                $args[] = $cursor_date;
+                $args[] = $cursor_product;
+            }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $post_id_column is selected from the fixed allowlist s.post_id/s.id after schema-mode validation; runtime values remain prepared placeholders.
+            $batch_sql = 'SELECT s.date AS view_date, ' . $post_id_column . ' AS product_id, SUM(s.pageviews) AS views
+                 FROM ' . $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . $posts_table . ' AS p ON p.ID = ' . $post_id_column . ' AND p.post_type = %s
+                 WHERE s.date <= %s
+                 GROUP BY s.date, ' . $post_id_column . $cursor_sql . '
+                 ORDER BY view_date ASC, product_id ASC
+                 LIMIT %d';
+            if ($cursor_date !== '') {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                    'product', $through_date,
+                    $cursor_date, $cursor_date, $cursor_product, $limit + 1
+                ), ARRAY_A);
+            } else {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                    'product', $through_date, $limit + 1
+                ), ARRAY_A);
+            }
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Koko Analytics batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = ($cursor_date !== '') ? ['date' => $cursor_date, 'product_id' => $cursor_product] : null;
+            if ($rows) { $last = end($rows); $next = ['date' => (string) $last['view_date'], 'product_id' => absint($last['product_id'])]; }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $product_id = isset($record['product_id']) ? absint($record['product_id']) : 0;
+            $date = isset($record['view_date']) ? (string) $record['view_date'] : '';
+            $views_raw = $record['views'] ?? null;
+            if (!$product_id || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'koko_analytics_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => ['date' => $date, 'product_id' => $product_id],
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Koko_Analytics_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 35);
+
+/**
+ * Burst Statistics adapter.
+ *
+ * Imports raw product pageview rows from burst_statistics. Unlike aggregate
+ * providers, Burst stores a WordPress post ID and a Unix timestamp per hit, so
+ * product resolution is direct and each source row has a stable ID. Visitor
+ * identifiers and session data are intentionally not read or imported.
+ */
+if (!class_exists('STATPL_Burst_Statistics_Historical_Adapter')) {
+    final class STATPL_Burst_Statistics_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'burst_statistics';
+        const SOURCE_KEY = 'burst_statistics';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_pageview_events';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Burst Statistics'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'burst_statistics';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            if (array_diff(['id', 'page_id', 'page_type', 'time'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'event', 'timestamp_precision' => 'seconds', 'product_id_direct' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Burst Statistics table is unavailable or incompatible.');
+            }
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(s.ID)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.page_id AND p.post_type = %s
+                 WHERE s.page_id > 0 AND s.page_type = %s',
+                'product', 'product'
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Burst Statistics snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_id' => max(0, (int) $max_id)],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Burst Statistics origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Burst Statistics table became unavailable or incompatible.');
+            }
+            $max_id = isset($snapshot['boundary']['max_id']) ? absint($snapshot['boundary']['max_id']) : -1;
+            if ($max_id < 0) { throw new RuntimeException('Invalid Burst Statistics snapshot boundary.'); }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) { $cursor_id = absint($checkpoint); }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT s.ID AS id, s.page_id, s.time
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.page_id AND p.post_type = %s
+                 WHERE s.page_type = %s AND s.page_id > 0 AND s.ID > %d AND s.ID <= %d
+                 ORDER BY s.ID ASC
+                 LIMIT %d',
+                'product', 'product', $cursor_id, $max_id, $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Burst Statistics batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_id = isset($record['page_id']) ? absint($record['page_id']) : 0;
+            $timestamp = isset($record['time']) ? absint($record['time']) : 0;
+            if (!$record_id || !$product_id || !$timestamp || !function_exists('wp_date')) { return null; }
+            $datetime = wp_date('Y-m-d H:i:s', $timestamp);
+            if (!is_string($datetime) || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $datetime)) { return null; }
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'burst_statistic_' . $record_id,
+                'views' => 1,
+                'record_type' => 'event',
+                'period_start' => $datetime,
+                'period_end' => $datetime,
+                'cursor' => $record_id,
+            ];
+        }
+
+        public function get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event) {
+            return [
+                'source' => 'burst_statistics',
+                'timestamp_precision' => 'seconds',
+                'overlap_assessment' => 'possible_but_not_proven',
+                'automatic_suppression' => false,
+                'reason' => 'Burst supplies an exact local event timestamp and product ID, but other providers do not share its stable pageview ID or visitor identity.',
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Burst_Statistics_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 36);
+
+/**
+ * Independent Analytics adapter.
+ *
+ * Imports one row per view from independent_analytics_views and resolves the
+ * resource through independent_analytics_resources.singular_id/post_type.
+ * Independent Analytics writes viewed_at in UTC. Only the timestamp and the
+ * product ID are imported; visitor/session identifiers are intentionally not
+ * accessed.
+ */
+if (!class_exists('STATPL_Independent_Analytics_Historical_Adapter')) {
+    final class STATPL_Independent_Analytics_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'independent_analytics';
+        const SOURCE_KEY = 'independent_analytics';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_view_events';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Independent Analytics'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function views_table() {
+            global $wpdb;
+            return $wpdb->prefix . 'independent_analytics_views';
+        }
+
+        private function resources_table() {
+            global $wpdb;
+            return $wpdb->prefix . 'independent_analytics_resources';
+        }
+
+        private function quote_table($table) {
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_tables() {
+            global $wpdb;
+            $found_any = false;
+            $missing_any = false;
+            foreach ([$this->views_table() => ['id', 'resource_id', 'viewed_at'], $this->resources_table() => ['id', 'singular_id', 'post_type']] as $table => $required) {
+                $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+                if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+                if ($exists !== $table) {
+                    $missing_any = true;
+                    continue;
+                }
+                $found_any = true;
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quote_table($table), ARRAY_A);
+                if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+                $names = [];
+                foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+                if (array_diff($required, $names)) { return ['status' => 'incompatible_schema']; }
+            }
+            if (!$found_any) { return ['status' => 'missing_table']; }
+            if ($missing_any) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_tables();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_tables();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'event', 'timestamp_precision' => 'seconds', 'product_id_direct' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_tables()['status'] !== 'available') {
+                throw new RuntimeException('Independent Analytics tables are unavailable or incompatible.');
+            }
+            $posts_table = $this->quote_table($wpdb->posts);
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(v.id)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->views_table()) . ' AS v
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->resources_table()) . ' AS r ON r.id = v.resource_id
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = r.singular_id AND p.post_type = %s
+                 WHERE r.post_type = %s AND r.singular_id > 0',
+                'product', 'product'
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Independent Analytics snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_id' => max(0, (int) $max_id)],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Independent Analytics origin or snapshot.');
+            }
+            if ($this->inspect_tables()['status'] !== 'available') {
+                throw new RuntimeException('Independent Analytics tables became unavailable or incompatible.');
+            }
+            $max_id = isset($snapshot['boundary']['max_id']) ? absint($snapshot['boundary']['max_id']) : -1;
+            if ($max_id < 0) { throw new RuntimeException('Invalid Independent Analytics snapshot boundary.'); }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) { $cursor_id = absint($checkpoint); }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table = $this->quote_table($wpdb->posts);
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT v.id, r.singular_id AS product_id, v.viewed_at
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->views_table()) . ' AS v
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->resources_table()) . ' AS r ON r.id = v.resource_id
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = r.singular_id AND p.post_type = %s
+                 WHERE r.post_type = %s AND r.singular_id > 0 AND v.id > %d AND v.id <= %d
+                 ORDER BY v.id ASC
+                 LIMIT %d',
+                'product', 'product', $cursor_id, $max_id, $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Independent Analytics batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_id = isset($record['product_id']) ? absint($record['product_id']) : 0;
+            $viewed_at = isset($record['viewed_at']) ? trim((string) $record['viewed_at']) : '';
+            if (!$record_id || !$product_id || $viewed_at === '') { return null; }
+            $timestamp = strtotime(str_replace('T', ' ', $viewed_at) . ' UTC');
+            if (!$timestamp || !function_exists('wp_date')) { return null; }
+            $datetime = wp_date('Y-m-d H:i:s', $timestamp);
+            if (!is_string($datetime) || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $datetime)) { return null; }
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'independent_analytics_view_' . $record_id,
+                'views' => 1,
+                'record_type' => 'event',
+                'period_start' => $datetime,
+                'period_end' => $datetime,
+                'cursor' => $record_id,
+            ];
+        }
+
+        public function get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event) {
+            return [
+                'source' => 'independent_analytics',
+                'timestamp_precision' => 'seconds',
+                'overlap_assessment' => 'possible_but_not_proven',
+                'automatic_suppression' => false,
+                'reason' => 'Independent Analytics provides a per-view timestamp and product ID, but no stable event identifier shared with other providers.',
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Independent_Analytics_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 37);
+
+/**
+ * PulseViews adapter.
+ *
+ * Uses disjoint date windows: completed daily aggregates through two days ago,
+ * then non-bot raw events after that boundary. Weekly/monthly rollups and the
+ * lifetime totals cache are never imported, preventing overlap. PulseViews
+ * prunes raw events after 90 days but retains its daily aggregate history.
+ */
+if (!class_exists('STATPL_PulseViews_Historical_Adapter')) {
+    final class STATPL_PulseViews_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'pulseviews';
+        const SOURCE_KEY = 'pulseviews';
+        const ADAPTER_VERSION = '1.0.0';
+        const DAILY_ORIGIN = 'daily_aggregates';
+        const RAW_ORIGIN = 'recent_raw_views';
+        private $snapshot_through_date = null;
+        private $snapshot_captured_at = null;
+
+        private function get_snapshot_through_date() {
+            if ($this->snapshot_through_date === null) {
+                $this->snapshot_through_date = current_datetime()->modify('-2 days')->format('Y-m-d');
+            }
+            return $this->snapshot_through_date;
+        }
+
+        private function get_snapshot_captured_at() {
+            if ($this->snapshot_captured_at === null) {
+                $this->snapshot_captured_at = current_time('mysql');
+            }
+            return $this->snapshot_captured_at;
+        }
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'PulseViews'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name($kind) {
+            global $wpdb;
+            if (!in_array($kind, ['daily', 'raw'], true)) {
+                throw new InvalidArgumentException('Unsupported PulseViews table kind.');
+            }
+            return $wpdb->prefix . ($kind === 'daily' ? 'pulseviews_aggregates' : 'pulseviews_views');
+        }
+
+        private function quote_table($table) {
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table($kind) {
+            global $wpdb;
+            $table = $this->table_name($kind);
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quote_table($table), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            $required = $kind === 'daily'
+                ? ['id', 'post_id', 'period_date', 'period_type', 'view_count']
+                : ['id', 'post_id', 'viewed_at', 'is_bot'];
+            if (array_diff($required, $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $daily = $this->inspect_table('daily');
+            $raw = $this->inspect_table('raw');
+            if ($daily['status'] !== 'missing_table' || $raw['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $origins = [];
+            $daily = $this->inspect_table('daily');
+            if ($daily['status'] !== 'missing_table') {
+                $origins[] = [
+                    'origin_key' => self::DAILY_ORIGIN,
+                    'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'window' => 'through_two_days_ago'],
+                    'detection_status' => $daily['status'],
+                ];
+            }
+            $raw = $this->inspect_table('raw');
+            if ($raw['status'] !== 'missing_table') {
+                $origins[] = [
+                    'origin_key' => self::RAW_ORIGIN,
+                    'capabilities' => ['product_views' => true, 'granularity' => 'event', 'window' => 'after_daily_aggregate_boundary', 'bot_filtered' => true],
+                    'detection_status' => $raw['status'],
+                ];
+            }
+            return $origins;
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            $through_date = $this->get_snapshot_through_date();
+            $posts_table = $this->quote_table($wpdb->posts);
+            if ($origin_key === self::DAILY_ORIGIN) {
+                if ($this->inspect_table('daily')['status'] !== 'available') {
+                    throw new RuntimeException('PulseViews daily aggregate table is unavailable or incompatible.');
+                }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $max_id = statpl_db_get_var(statpl_db_prepare(
+                    'SELECT MAX(a.id)
+                     FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->table_name('daily')) . ' AS a
+                     INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = a.post_id AND p.post_type = %s
+                     WHERE a.period_type = %s AND a.period_date <= %s',
+                    'product', 'day', $through_date
+                ));
+                if (!empty($wpdb->last_error)) { throw new RuntimeException('PulseViews daily snapshot query failed.'); }
+                return ['boundary' => ['max_id' => max(0, (int) $max_id), 'through_date' => $through_date], 'initial_checkpoint' => null, 'captured_at' => current_time('mysql')];
+            }
+            if ($origin_key === self::RAW_ORIGIN) {
+                if ($this->inspect_table('raw')['status'] !== 'available') {
+                    throw new RuntimeException('PulseViews raw views table is unavailable or incompatible.');
+                }
+                $after_datetime = $through_date . ' 23:59:59';
+                $captured_at = $this->get_snapshot_captured_at();
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $max_id = statpl_db_get_var(statpl_db_prepare(
+                    'SELECT MAX(v.id)
+                     FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->table_name('raw')) . ' AS v
+                     INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = v.post_id AND p.post_type = %s
+                     WHERE v.is_bot = 0 AND v.viewed_at > %s AND v.viewed_at <= %s',
+                    'product', $after_datetime, $captured_at
+                ));
+                if (!empty($wpdb->last_error)) { throw new RuntimeException('PulseViews raw snapshot query failed.'); }
+                return ['boundary' => ['max_id' => max(0, (int) $max_id), 'after_datetime' => $after_datetime, 'captured_at' => $captured_at], 'initial_checkpoint' => null, 'captured_at' => $captured_at];
+            }
+            return [];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if (!is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid PulseViews snapshot.');
+            }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) { $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']); }
+            elseif (is_numeric($checkpoint)) { $cursor_id = absint($checkpoint); }
+            $max_id = isset($snapshot['boundary']['max_id']) ? absint($snapshot['boundary']['max_id']) : -1;
+            if ($max_id < 0) { throw new RuntimeException('Invalid PulseViews snapshot boundary.'); }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table = $this->quote_table($wpdb->posts);
+            if ($origin_key === self::DAILY_ORIGIN) {
+                if ($this->inspect_table('daily')['status'] !== 'available') { throw new RuntimeException('PulseViews daily aggregate table became unavailable.'); }
+                $through_date = isset($snapshot['boundary']['through_date']) ? (string) $snapshot['boundary']['through_date'] : '';
+                $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+                if (!$parsed || $parsed->format('Y-m-d') !== $through_date) { throw new RuntimeException('Invalid PulseViews daily boundary.'); }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    'SELECT a.id, a.post_id, a.period_date, a.view_count
+                     FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->table_name('daily')) . ' AS a
+                     INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = a.post_id AND p.post_type = %s
+                     WHERE a.period_type = %s AND a.id > %d AND a.id <= %d AND a.period_date <= %s
+                     ORDER BY a.id ASC
+                     LIMIT %d',
+                    'product', 'day', $cursor_id, $max_id, $through_date, $limit + 1
+                ), ARRAY_A);
+            } elseif ($origin_key === self::RAW_ORIGIN) {
+                if ($this->inspect_table('raw')['status'] !== 'available') { throw new RuntimeException('PulseViews raw views table became unavailable.'); }
+                $after_datetime = isset($snapshot['boundary']['after_datetime']) ? (string) $snapshot['boundary']['after_datetime'] : '';
+                $captured_at = isset($snapshot['boundary']['captured_at']) ? (string) $snapshot['boundary']['captured_at'] : '';
+                if ($after_datetime === '' || $captured_at === '') { throw new RuntimeException('Invalid PulseViews raw boundary.'); }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    'SELECT v.id, v.post_id, v.viewed_at
+                     FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->table_name('raw')) . ' AS v
+                     INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = v.post_id AND p.post_type = %s
+                     WHERE v.is_bot = 0 AND v.id > %d AND v.id <= %d AND v.viewed_at > %s AND v.viewed_at <= %s
+                     ORDER BY v.id ASC
+                     LIMIT %d',
+                    'product', $cursor_id, $max_id, $after_datetime, $captured_at, $limit + 1
+                ), ARRAY_A);
+            } else {
+                throw new RuntimeException('Unknown PulseViews origin.');
+            }
+            if (!empty($wpdb->last_error) || !is_array($rows)) { throw new RuntimeException('PulseViews batch query failed.'); }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if (!is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_id = isset($record['post_id']) ? absint($record['post_id']) : 0;
+            if (!$record_id || !$product_id) { return null; }
+            if ($origin_key === self::DAILY_ORIGIN) {
+                $date = isset($record['period_date']) ? (string) $record['period_date'] : '';
+                $views_raw = $record['view_count'] ?? null;
+                if (!preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+                $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+                $errors = DateTime::getLastErrors();
+                if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+                $views = (int) $views_raw;
+                $period_start = $date . ' 00:00:00';
+                $period_end = $date . ' 23:59:59';
+                return ['product_id' => $product_id, 'source_record_key' => 'pulseviews_day_' . $product_id . '_' . $date, 'views' => $views, 'record_type' => 'aggregate', 'period_start' => $period_start, 'period_end' => $period_end, 'cursor' => $record_id];
+            }
+            if ($origin_key === self::RAW_ORIGIN) {
+                $viewed_at = isset($record['viewed_at']) ? (string) $record['viewed_at'] : '';
+                $parsed = DateTime::createFromFormat('!Y-m-d H:i:s', $viewed_at);
+                $errors = DateTime::getLastErrors();
+                if (!$parsed || $parsed->format('Y-m-d H:i:s') !== $viewed_at || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+                return ['product_id' => $product_id, 'source_record_key' => 'pulseviews_view_' . $record_id, 'views' => 1, 'record_type' => 'event', 'period_start' => $viewed_at, 'period_end' => $viewed_at, 'cursor' => $record_id];
+            }
+            return null;
+        }
+
+        public function get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event) {
+            return [
+                'source' => 'pulseviews',
+                'origin' => $origin_key,
+                'overlap_assessment' => 'possible_but_not_proven',
+                'automatic_suppression' => false,
+                'reason' => 'PulseViews event rows have local timestamps but no stable cross-provider event identifier; daily aggregates are matched only on exact product/date/count dimensions.',
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_PulseViews_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 38);

statora-plus/trunk/readme.txt

@@ -5 +5 @@
 Tested up to: 7.1
 Requires PHP: 7.4
-Stable tag: 0.11.46
+Stable tag: 0.11.47
 License: GPLv2 or later
 License URI: https://www.gnu.org/licenses/gpl-2.0.html
@@ -82 +82 @@
 == Changelog ==
 
+= 0.11.47 =
+* Harden historical product-view source queries and validate adapter schema/table selections.
+* Use prepared integer limits and WordPress timezone-aware retry timestamps.
+* Use WordPress URL parsing for Statify source URLs.
+
 = 0.11.46 =
 * Place narrowly scoped Plugin Check security-rule annotations on the database-call lines that use constructor-generated table identifiers.

statora-plus/trunk/statora-plus.php

@@ -3 +3 @@
  * Plugin Name: Statora Plus
  * Description: View key WooCommerce product statistics in one clear dashboard.
- * Version: 0.11.46
+ * Version: 0.11.47
  * Author: Panagiotis Pavlidis
  * Author URI: https://gr.linkedin.com/in/frozenfiregr
@@ -16 +16 @@
 if (!defined('ABSPATH')) { exit; }
 
+
+/**
+ * Audited wpdb boundary for Statora SQL.
+ *
+ * All runtime data values must already be passed through statpl_db_prepare()
+ * with placeholders. Table/column identifiers are not SQL values and must be
+ * generated from the WordPress prefix plus fixed plugin/provider suffixes, or
+ * validated against a strict allowlist before reaching this boundary.
+ *
+ * These wrappers keep direct wpdb access in one reviewable location. They do
+ * not add caching: importer transactions, locks, schema checks and live metric
+ * reads require their existing consistency and freshness semantics.
+ */
+if (!function_exists('statpl_db_prepare')) {
+    function statpl_db_prepare($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'prepare') || !is_string($query)) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- Centralized preparation boundary; callers provide fixed SQL structure, validated identifiers and runtime values as placeholders.
+        return call_user_func_array(array($wpdb, 'prepare'), array_merge(array($query), $args));
+    }
+}
+
+if (!function_exists('statpl_db_query')) {
+    function statpl_db_query($query) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'query') || !is_string($query)) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized execution boundary; query strings are prepared by statpl_db_prepare() or consist solely of fixed DDL/SQL and validated identifiers.
+        return $wpdb->query($query);
+    }
+}
+
+if (!function_exists('statpl_db_get_var')) {
+    function statpl_db_get_var($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'get_var') || !is_string($query)) {
+            return null;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized read boundary; callers use prepared values and validated internal identifiers.
+        return $wpdb->get_var($query, ...$args);
+    }
+}
+
+if (!function_exists('statpl_db_get_row')) {
+    function statpl_db_get_row($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'get_row') || !is_string($query)) {
+            return null;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized read boundary; callers use prepared values and validated internal identifiers.
+        return $wpdb->get_row($query, ...$args);
+    }
+}
+
+if (!function_exists('statpl_db_get_results')) {
+    function statpl_db_get_results($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'get_results') || !is_string($query)) {
+            return null;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized read boundary; callers use prepared values and validated internal identifiers.
+        return $wpdb->get_results($query, ...$args);
+    }
+}
+
+if (!function_exists('statpl_db_get_col')) {
+    function statpl_db_get_col($query, ...$args) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'get_col') || !is_string($query)) {
+            return null;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- Centralized read boundary; callers use prepared values and validated internal identifiers.
+        return $wpdb->get_col($query, ...$args);
+    }
+}
+
+
+if (!function_exists('statpl_db_update')) {
+    function statpl_db_update($table, $data, $where, $format = null, $where_format = null) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'update')) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Centralized CRUD boundary; table identifiers are internal plugin properties and data values use wpdb format handling.
+        return $wpdb->update($table, $data, $where, $format, $where_format);
+    }
+}
+
+if (!function_exists('statpl_db_insert')) {
+    function statpl_db_insert($table, $data, $format = null) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'insert')) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Centralized CRUD boundary; table identifiers are internal plugin properties and data values use wpdb format handling.
+        return $wpdb->insert($table, $data, $format);
+    }
+}
+
+if (!function_exists('statpl_db_delete')) {
+    function statpl_db_delete($table, $where, $where_format = null) {
+        global $wpdb;
+        if (!is_object($wpdb) || !method_exists($wpdb, 'delete')) {
+            return false;
+        }
+        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Centralized CRUD boundary; table identifiers are internal plugin properties and values use wpdb format handling.
+        return $wpdb->delete($table, $where, $where_format);
+    }
+}
+
+/**
+ * Contract implemented by source-specific historical product-view adapters.
+ * Adapters are supplied through the `statpl_historical_view_adapters` filter.
+ *
+ * `discover_origins()` must return only historical product-view origins; general
+ * page views, visits and non-product content must never be advertised here.
+ * `get_origin_snapshot()` must return an immutable, non-empty `boundary` descriptor.
+ * Every `get_product_view_batch()` result must include `boundary_applied => true`;
+ * the adapter must enforce that snapshot boundary in its source query, return no
+ * more than the requested limit, and advance `next_checkpoint` when `has_more` is true.
+ * `normalize_record()` may explicitly return `['skip' => true, 'source_record_key' => ..., 'cursor' => ...]`
+ * for a valid source row that is outside product scope. The core validates the key/cursor,
+ * clears any stale per-row failure, advances the batch cursor, and does not create an event
+ * or failure-ledger entry. Invalid product records must still return null and follow retries.
+ *
+ * Optional adapter extension: `get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event)`.
+ * It may return a small, JSON-serializable evidence array describing source-specific
+ * overlap signals. Its output is audit evidence only: it cannot suppress counts or
+ * alter the generic import decision. Automatic suppression remains limited to the
+ * generic exact-match rule requiring a shared fingerprint and identical dimensions.
+ */
+if (!interface_exists('STATPL_Historical_View_Adapter')) {
+    interface STATPL_Historical_View_Adapter {
+        public function get_adapter_key();
+        public function get_source_key();
+        public function get_display_name();
+        public function get_adapter_version();
+        public function discover_origins();
+        public function get_origin_snapshot($origin_key);
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit);
+        public function normalize_record($origin_key, $record);
+    }
+}
+
 final class STATPL_Core {
-    const VERSION = '0.11.46';
+    const VERSION = '0.11.47';
+    const VIEW_IMPORT_SCHEMA_VERSION = '1.0.0';
+    const VIEW_IMPORT_STATE_SCHEMA_VERSION = '1.1.0';
+    const VIEW_IMPORT_EVENTS_SCHEMA_VERSION = '1.3.0';
+    const VIEW_IMPORT_FAILURES_SCHEMA_VERSION = '1.3.0';
+    const VIEW_SOURCE_SCHEMA_VERSION = '1.3.4';
+    const HISTORY_REPORT_SCHEMA_VERSION = '1.0.0';
     const NONCE_ACTION = 'statpl_record_view';
     private static $instance;
@@ -24 +177 @@
     private $order_events_table;
     private $order_items_table;
-
-    public static function instance() {
+    private $view_imports_table;
+   private $view_import_failures_table;
+
+   private $view_import_state_table;
+   private $view_import_events_table;
+   private $view_sources_table;
+   private $view_source_origins_table;
+   private $view_source_state_table;
+   private $view_source_events_table;
+   private $view_source_failures_table;
+   private $view_source_reconciliation_table;
+   private $view_source_reconciliation_history_table;
+   private $historical_import_report_table;
+   private $historical_view_adapters = [];
+   public static function instance() {
         if (!self::$instance) self::$instance = new self();
         return self::$instance;
@@ -35 +201 @@
         $this->order_events_table = $wpdb->prefix . 'statpl_product_metric_events';
         $this->order_items_table = $wpdb->prefix . 'statpl_order_product_snapshot';
+        $this->view_imports_table = $wpdb->prefix . 'statpl_view_imports';
+        $this->view_import_state_table = $wpdb->prefix . 'statpl_view_import_state';
+        $this->view_import_events_table = $wpdb->prefix . 'statpl_view_import_events';
+        $this->view_import_failures_table = $wpdb->prefix . 'statpl_view_import_failures';
+        $this->view_sources_table = $wpdb->prefix . 'statpl_view_sources';
+        $this->view_source_origins_table = $wpdb->prefix . 'statpl_view_source_origins';
+        $this->view_source_state_table = $wpdb->prefix . 'statpl_view_source_state';
+        $this->view_source_events_table = $wpdb->prefix . 'statpl_view_source_events';
+        $this->view_source_failures_table = $wpdb->prefix . 'statpl_view_source_failures';
+        $this->view_source_reconciliation_table = $wpdb->prefix . 'statpl_view_source_reconciliation';
+        $this->view_source_reconciliation_history_table = $wpdb->prefix . 'statpl_view_source_reconciliation_history';
+        $this->historical_import_report_table = $wpdb->prefix . 'statpl_historical_import_report';
         register_activation_hook(__FILE__, [$this, 'activate']);
+        register_deactivation_hook(__FILE__, [$this, 'deactivate']);
+        add_action('admin_post_statpl_prepare_deactivation', [$this, 'prepare_deactivation']);
         add_action('plugins_loaded', [$this, 'init']);
     }
+    /**
+     * Intercept the Plugins-screen deactivation action and persist the explicit
+     * administrator choice before WordPress invokes the deactivation hook.
+     */
+    public function prepare_deactivation() {
+        if (!current_user_can('activate_plugins')) {
+            wp_die(esc_html__('Δεν έχεις δικαίωμα εκτέλεσης αυτής της ενέργειας.', 'statora-plus'));
+        }
+        check_admin_referer('statpl_prepare_deactivation');
+
+        $choice = isset($_GET['choice']) ? sanitize_key(wp_unslash($_GET['choice'])) : '';
+        if (!in_array($choice, ['retain', 'delete'], true)) {
+            wp_die(esc_html__('Μη έγκυρη επιλογή διατήρησης δεδομένων.', 'statora-plus'));
+        }
+
+        $redirect = isset($_GET['redirect_to']) ? esc_url_raw(wp_unslash($_GET['redirect_to'])) : '';
+        $parts = wp_parse_url($redirect);
+        $query = [];
+        if (!is_array($parts) || empty($parts['path']) || basename($parts['path']) !== 'plugins.php') {
+            wp_die(esc_html__('Μη έγκυρος προορισμός απενεργοποίησης.', 'statora-plus'));
+        }
+        if (!empty($parts['query'])) {
+            parse_str($parts['query'], $query);
+        }
+        if (($query['action'] ?? '') !== 'deactivate' || ($query['plugin'] ?? '') !== plugin_basename(__FILE__)) {
+            wp_die(esc_html__('Η ενέργεια δεν αφορά το Statora Plus.', 'statora-plus'));
+        }
+
+        update_option('statpl_deactivation_choice', $choice, false);
+        wp_safe_redirect($redirect);
+        exit;
+    }
+
+    /** Stop Statora-owned workers and either retain or remove Statora-owned data. */
+    public function deactivate() {
+        global $wpdb;
+
+        $choice = (string) get_option('statpl_deactivation_choice', '');
+        delete_option('statpl_deactivation_choice');
+
+        $hooks = [
+            'statpl_import_batch',
+            'statpl_view_import_batch',
+            'statpl_generic_view_import_batch',
+            'statpl_generic_view_snapshot_retry',
+            'statpl_generic_view_retry_failed_records',
+            'statpl_sync_order',
+            'statpl_reconcile_legacy_aggregate_fingerprints',
+        ];
+        foreach ($hooks as $hook) {
+            wp_clear_scheduled_hook($hook);
+            if (function_exists('as_unschedule_all_actions')) {
+                as_unschedule_all_actions($hook, null, 'statpl-plus');
+            }
+        }
+
+        if ($choice === 'retain') {
+            update_option('statpl_retained_deactivation_at', current_time('mysql'), false);
+            update_option('statpl_data_lifecycle_state', 'retained', false);
+            delete_transient('statpl_order_stats_v1');
+            delete_transient('statpl_global_summary_v2');
+            return;
+        }
+
+        // A missing/invalid choice must never silently destroy data.
+        if ($choice !== 'delete') {
+            update_option('statpl_deactivation_choice_missing', '1', false);
+            return;
+        }
+
+        $tables = [
+            $this->views_table,
+            $this->events_table,
+            $this->order_events_table,
+            $this->order_items_table,
+            $this->view_imports_table,
+            $this->view_import_state_table,
+            $this->view_import_events_table,
+            $this->view_import_failures_table,
+            $this->view_sources_table,
+            $this->view_source_origins_table,
+            $this->view_source_state_table,
+            $this->view_source_events_table,
+            $this->view_source_failures_table,
+            $this->view_source_reconciliation_table,
+            $this->view_source_reconciliation_history_table,
+            $this->historical_import_report_table,
+        ];
+        foreach ($tables as $table) {
+            // Table names are built exclusively from the active WordPress prefix
+            // and fixed Statora suffixes declared in the constructor. Validate the
+            // complete identifier before placing it in a DDL statement; identifiers
+            // cannot be supplied as ordinary prepared-statement value placeholders.
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                continue;
+            }
+            $quoted_table = '`' . $table . '`';
+            // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- DDL identifiers cannot use value placeholders; the identifier is constrained to ASCII letters, digits and underscores and is quoted as one identifier.
+            statpl_db_query('DROP TABLE IF EXISTS ' . $quoted_table);
+        }
+
+        // Remove only Statora's reserved option/transient namespaces.
+        $option_like = $wpdb->esc_like('statpl_') . '%';
+        statpl_db_query(statpl_db_prepare("DELETE FROM {$wpdb->options} WHERE option_name LIKE %s", $option_like));
+        $transient_like = $wpdb->esc_like('_transient_statpl_') . '%';
+        $timeout_like = $wpdb->esc_like('_transient_timeout_statpl_') . '%';
+        statpl_db_query(statpl_db_prepare("DELETE FROM {$wpdb->options} WHERE option_name LIKE %s OR option_name LIKE %s", $transient_like, $timeout_like));
+        if (function_exists('wp_cache_flush_group')) {
+            wp_cache_flush_group('statpl_plus');
+        }
+    }
+
+    /** Rebuild the historical import window after an explicit retain/reactivate cycle. */
+    private function resume_retained_history_gap() {
+        global $wpdb;
+
+        $deactivated_at = (string) get_option('statpl_retained_deactivation_at', '');
+        if ($deactivated_at === '') {
+            return ['status' => 'not_required'];
+        }
+
+        $lock = $this->acquire_generic_advisory_lock('statpl_generic_adapter_discovery');
+        if (empty($lock['acquired'])) {
+            return ['status' => 'lock_unavailable'];
+        }
+
+        $reset = 0;
+        $failed = 0;
+        $scheduled_origins = [];
+        try {
+            $origins = statpl_db_get_results(
+                "SELECT source_id, origin_key, adapter_key FROM {$this->view_source_origins_table} WHERE detection_status = 'available'",
+                ARRAY_A
+            );
+            if (!empty($wpdb->last_error) || !is_array($origins)) {
+                return ['status' => 'database_error'];
+            }
+
+            foreach ($origins as $origin) {
+                if (!$this->generic_advisory_lock_session_is_current($lock)) {
+                    return ['status' => 'lock_session_lost', 'reset' => $reset, 'failed' => $failed];
+                }
+                $adapter = $this->get_historical_view_adapter((string) $origin['adapter_key']);
+                if (!$adapter) {
+                    $failed++;
+                    continue;
+                }
+                try {
+                    $snapshot = $adapter->get_origin_snapshot((string) $origin['origin_key']);
+                } catch (Throwable $exception) {
+                    $failed++;
+                    continue;
+                }
+                if (!$this->generic_advisory_lock_session_is_current($lock)) {
+                    return ['status' => 'lock_session_lost', 'reset' => $reset, 'failed' => $failed];
+                }
+                if (!is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                    $failed++;
+                    continue;
+                }
+                if (!isset($snapshot['captured_at'])) {
+                    $snapshot['captured_at'] = current_time('mysql');
+                }
+                $initial = array_key_exists('initial_checkpoint', $snapshot) ? $snapshot['initial_checkpoint'] : null;
+                if ($initial !== null && !$this->is_valid_generic_historical_cursor($initial)) {
+                    $failed++;
+                    continue;
+                }
+                unset($snapshot['initial_checkpoint']);
+                $saved = $this->update_view_source_origin_state(
+                    (int) $origin['source_id'],
+                    (string) $origin['origin_key'],
+                    [
+                        'snapshot_data' => $snapshot,
+                        'checkpoint_data' => ['cursor' => $initial, 'processed' => 0, 'snapshot_captured_at' => $snapshot['captured_at']],
+                        'status' => 'pending',
+                        'last_error' => null,
+                        'started_at' => null,
+                        'completed_at' => null,
+                    ],
+                    $lock
+                );
+                if (empty($saved['status']) || $saved['status'] !== 'updated') {
+                    $failed++;
+                    continue;
+                }
+                $reset++;
+                $scheduled_origins[] = [(int) $origin['source_id'], (string) $origin['origin_key']];
+            }
+        } finally {
+            $this->release_generic_advisory_lock($lock, 'retained_history_gap');
+        }
+
+        foreach ($scheduled_origins as $scheduled_origin) {
+            $this->schedule_generic_historical_view_import_batch(15, $scheduled_origin[0], $scheduled_origin[1]);
+        }
+
+        // SlimStat uses a separate importer and event ledger. Rewind its cursor to
+        // the beginning while extending both source boundaries; its unique event
+        // ledger prevents already-applied records from being counted twice.
+        $slimstat_state = statpl_db_get_var(statpl_db_prepare(
+            "SELECT source FROM {$this->view_import_state_table} WHERE source = %s",
+            'slimstat'
+        ));
+        if ($slimstat_state === 'slimstat') {
+            $snapshot = $this->get_slimstat_view_snapshot();
+            if (($snapshot['status'] ?? '') === 'available') {
+                $updated = statpl_db_update(
+                    $this->view_import_state_table,
+                    [
+                        'snapshot_max_id' => max((int) $snapshot['snapshot']['active'], (int) $snapshot['snapshot']['archive']),
+                        'snapshot_active_max_id' => (int) $snapshot['snapshot']['active'],
+                        'snapshot_archive_max_id' => (int) $snapshot['snapshot']['archive'],
+                        'last_processed_id' => 0,
+                        'status' => 'pending',
+                        'started_at' => null,
+                        'completed_at' => null,
+                        'updated_at' => current_time('mysql'),
+                    ],
+                    ['source' => 'slimstat'],
+                    ['%d', '%d', '%d', '%d', '%s', '%s', '%s', '%s'],
+                    ['%s']
+                );
+                if ($updated === false) {
+                    $failed++;
+                }
+            } else {
+                $failed++;
+            }
+        }
+
+        if ($failed === 0) {
+            delete_option('statpl_retained_deactivation_at');
+            update_option('statpl_data_lifecycle_state', 'active', false);
+        }
+        return ['status' => $failed === 0 ? 'reset' : 'partial', 'reset' => $reset, 'failed' => $failed];
+    }
+
     public function activate() {
         global $wpdb;
@@ -47 +465 @@
             total_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
             PRIMARY KEY  (product_id)
+        ) $collate;");
+                dbDelta("CREATE TABLE {$this->view_imports_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source VARCHAR(50) NOT NULL,
+            product_id BIGINT(20) UNSIGNED NOT NULL,
+            imported_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            imported_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_product (source, product_id),
+            KEY imported_at (imported_at)
         ) $collate;");
         dbDelta("CREATE TABLE {$this->events_table} (
@@ -59 +487 @@
         // On a fresh install, avoid issuing SHOW INDEX against a table that has not yet been created.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Schema detection is required before the conditional index migration; the identifier is built from the WordPress prefix and a fixed suffix.
-        $events_table_exists = $wpdb->get_var($wpdb->prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($this->order_events_table)));
+        $events_table_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($this->order_events_table)));
         if ($events_table_exists === $this->order_events_table) {
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is built from the WordPress prefix and a fixed plugin suffix; this conditional migration checks the obsolete index.
-            $old_index = $wpdb->get_var($wpdb->prepare("SHOW INDEX FROM {$this->order_events_table} WHERE Key_name = %s", 'order_product_event'));
+            $old_index = statpl_db_get_var(statpl_db_prepare("SHOW INDEX FROM {$this->order_events_table} WHERE Key_name = %s", 'order_product_event'));
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.SchemaChange, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is built from the WordPress prefix and a fixed plugin suffix; this conditional migration removes only the obsolete index.
-            if ($old_index) { $wpdb->query("ALTER TABLE {$this->order_events_table} DROP INDEX order_product_event"); }
+            if ($old_index) { statpl_db_query("ALTER TABLE {$this->order_events_table} DROP INDEX order_product_event"); }
         }
         dbDelta("CREATE TABLE {$this->order_events_table} (
@@ -94 +522 @@
             KEY status_created (order_status, created_at)
         ) $collate;");
-        // Rebuild order snapshots once after an upgrade so completed_at and refund attribution
-        // are populated consistently for orders already present in the store.
+        // dbDelta can fail without throwing (for example during a transient
+        // database outage). Verify the core table structures before advancing
+        // the global DB version; otherwise a partial install would be treated as
+        // current and would not be retried on the next request.
+        $required_core_columns = [
+            $this->views_table => ['product_id', 'total_views'],
+            $this->view_imports_table => ['id', 'source', 'product_id', 'imported_views', 'imported_at'],
+            $this->events_table => ['id', 'product_id', 'viewed_at'],
+            $this->order_events_table => ['id', 'order_id', 'product_id', 'event_type', 'event_ref_id', 'event_at'],
+            $this->order_items_table => ['order_id', 'product_id', 'order_status', 'created_at', 'paid_at', 'completed_at', 'quantity', 'net_quantity', 'net_revenue', 'has_refund'],
+        ];
+        foreach ($required_core_columns as $table => $columns) {
+            if (!$this->verify_historical_table_columns($table, $columns)) {
+                return false;
+            }
+        }
+
+        // Upgrade side effects must run only after every core table has been
+        // verified. Previously these resets happened before verification, so a
+        // partial dbDelta/database outage could repeatedly rewind an in-progress
+        // order import even though the schema upgrade had not succeeded.
         if ($previous_version !== '' && version_compare($previous_version, self::VERSION, '<')) {
             update_option('statpl_import_complete', 0, false);
@@ -102 +549 @@
             delete_transient('statpl_global_summary_v2');
         }
+
         update_option('statpl_db_version', self::VERSION);
-    }
-    public function init() {
-        if (get_option('statpl_db_version') !== self::VERSION) {
-            $this->activate();
-        }
+        if ((string) get_option('statpl_db_version', '') !== self::VERSION) {
+            return false;
+        }
+        return true;
+    }
+    /** Persist a schema marker and verify the stored value before proceeding. */
+    private function persist_schema_version_marker($option_name, $version) {
+        update_option($option_name, $version, false);
+
+        // update_option() can return false for either an unchanged value or a failed write.
+        // The strict read-back is the authoritative persistence check.
+        return get_option($option_name, '') === $version;
+    }
+
+    /** Create the durable, privacy-safe summary ledger for historical import outcomes. */
+    private function maybe_upgrade_historical_import_report_schema() {
+        global $wpdb;
+        if (get_option('statpl_history_report_schema_version', '') === self::HISTORY_REPORT_SCHEMA_VERSION) {
+            return true;
+        }
+        require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+        $collate = $wpdb->get_charset_collate();
+        dbDelta("CREATE TABLE {$this->historical_import_report_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source_key VARCHAR(100) NOT NULL,
+            source_name VARCHAR(191) NOT NULL,
+            origin_key VARCHAR(100) NOT NULL DEFAULT '',
+            source_record_hash CHAR(64) NOT NULL,
+            outcome VARCHAR(20) NOT NULL DEFAULT 'failed',
+            attempts INT(10) UNSIGNED NOT NULL DEFAULT 0,
+            reason_code VARCHAR(100) NOT NULL DEFAULT '',
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_record (source_key, source_record_hash),
+            KEY source_outcome (source_key, outcome),
+            KEY outcome (outcome)
+        ) $collate;");
+        $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($this->historical_import_report_table)));
+        if ($exists !== $this->historical_import_report_table || !$this->verify_historical_table_columns($this->historical_import_report_table, ['id','source_key','source_name','origin_key','source_record_hash','outcome','attempts','reason_code','updated_at'])) {
+            return false;
+        }
+        // Preserve visibility of records imported before this report ledger existed.
+        statpl_db_query("INSERT IGNORE INTO {$this->historical_import_report_table}
+            (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+            SELECT s.source_key, s.display_name, '', e.source_record_hash, 'imported', 0, '', e.updated_at
+            FROM {$this->view_source_events_table} e
+            INNER JOIN {$this->view_sources_table} s ON s.id = e.source_id");
+        if (!empty($wpdb->last_error)) { return false; }
+        statpl_db_query("INSERT IGNORE INTO {$this->historical_import_report_table}
+            (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+            SELECT s.source_key, s.display_name, f.origin_key, f.source_record_hash, IF(f.status = 'retry', 'retry', 'failed'), f.attempts, 'record_import_failed', f.updated_at
+            FROM {$this->view_source_failures_table} f
+            INNER JOIN {$this->view_sources_table} s ON s.id = f.source_id");
+        if (!empty($wpdb->last_error)) { return false; }
+        statpl_db_query("INSERT IGNORE INTO {$this->historical_import_report_table}
+            (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+            SELECT 'slimstat', 'SlimStat', 'slimstat', SHA2(CONCAT('slimstat', CHAR(0), e.source_view_id), 256), 'imported', 0, '', e.imported_at
+            FROM {$this->view_import_events_table} e WHERE e.source = 'slimstat' AND e.counts_applied = 1");
+        if (!empty($wpdb->last_error)) { return false; }
+        statpl_db_query("INSERT IGNORE INTO {$this->historical_import_report_table}
+            (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+            SELECT 'slimstat', 'SlimStat', 'slimstat', SHA2(CONCAT('slimstat', CHAR(0), f.source_view_id), 256), IF(f.status = 'retry', 'retry', 'failed'), f.attempts, 'record_import_failed', f.updated_at
+            FROM {$this->view_import_failures_table} f WHERE f.source = 'slimstat'");
+        if (!empty($wpdb->last_error)) { return false; }
+        return $this->persist_schema_version_marker('statpl_history_report_schema_version', self::HISTORY_REPORT_SCHEMA_VERSION);
+    }
+
+    /** Save one eligible historical record's latest durable outcome; no visitor identifiers are stored. */
+    private function save_historical_import_report_record($source_key, $source_name, $origin_key, $record_hash, $outcome, $attempts = 0, $reason_code = '') {
+        global $wpdb;
+        $source_key = sanitize_key((string) $source_key);
+        $source_name = sanitize_text_field((string) $source_name);
+        $origin_key = sanitize_key((string) $origin_key);
+        $record_hash = strtolower((string) $record_hash);
+        if ($source_key === '' || $source_name === '' || !preg_match('/^[a-f0-9]{64}$/D', $record_hash)
+            || !in_array($outcome, ['imported','retry','failed'], true)) {
+            return false;
+        }
+        $result = statpl_db_query(statpl_db_prepare(
+            "INSERT INTO {$this->historical_import_report_table}
+                (source_key, source_name, origin_key, source_record_hash, outcome, attempts, reason_code, updated_at)
+             VALUES (%s, %s, %s, %s, %s, %d, %s, %s)
+             ON DUPLICATE KEY UPDATE
+                source_name = VALUES(source_name),
+                outcome = VALUES(outcome),
+                attempts = GREATEST(attempts, VALUES(attempts)),
+                reason_code = VALUES(reason_code),
+                updated_at = VALUES(updated_at)",
+            $source_key, $source_name, $origin_key, $record_hash, $outcome,
+            max(0, (int) $attempts), sanitize_key((string) $reason_code), current_time('mysql')
+        ));
+        return $result !== false && empty($wpdb->last_error);
+    }
+
+    /** Resolve a generic source's stable public name for the administrator report. */
+    private function save_generic_historical_report_record($source_id, $origin_key, $record_hash, $outcome, $attempts = 0, $reason_code = '') {
+        global $wpdb;
+        $source = statpl_db_get_row(statpl_db_prepare(
+            "SELECT source_key, display_name FROM {$this->view_sources_table} WHERE id = %d LIMIT 1",
+            absint($source_id)
+        ), ARRAY_A);
+        if (!is_array($source) || !empty($wpdb->last_error)) {
+            return false;
+        }
+        return $this->save_historical_import_report_record(
+            (string) $source['source_key'], (string) $source['display_name'],
+            (string) $origin_key, (string) $record_hash, (string) $outcome,
+            (int) $attempts, (string) $reason_code
+        );
+    }
+
+    /** Aggregate historical import state without exposing source errors or personal data. */
+    private function get_historical_import_report_summary() {
+        global $wpdb;
+        $rows = statpl_db_get_results(
+            "SELECT source_key, source_name, COUNT(*) AS eligible,
+                    SUM(CASE WHEN outcome = 'imported' THEN 1 ELSE 0 END) AS imported,
+                    SUM(CASE WHEN outcome IN ('retry','failed') THEN 1 ELSE 0 END) AS not_imported,
+                    SUM(CASE WHEN outcome = 'retry' THEN 1 ELSE 0 END) AS pending_retries,
+                    SUM(CASE WHEN outcome = 'failed' THEN 1 ELSE 0 END) AS failed,
+                    SUM(CASE WHEN outcome = 'imported' AND attempts > 0 THEN 1 ELSE 0 END) AS retry_resolved,
+                    SUM(CASE WHEN outcome = 'failed' THEN 1 ELSE 0 END) AS final_failures
+             FROM {$this->historical_import_report_table}
+             GROUP BY source_key, source_name ORDER BY source_name ASC",
+            ARRAY_A
+        );
+        if (!empty($wpdb->last_error) || !is_array($rows)) {
+            return ['available' => false, 'sources' => [], 'eligible' => 0, 'imported' => 0, 'not_imported' => 0, 'pending_retries' => 0, 'failed' => 0, 'retry_resolved' => 0];
+        }
+        $summary = ['available' => true, 'sources' => $rows, 'eligible' => 0, 'imported' => 0, 'not_imported' => 0, 'pending_retries' => 0, 'failed' => 0, 'retry_resolved' => 0];
+        foreach ($rows as $row) {
+            foreach (['eligible','imported','not_imported','pending_retries','failed','retry_resolved'] as $key) {
+                $summary[$key] += (int) ($row[$key] ?? 0);
+            }
+        }
+        return $summary;
+    }
+
+    /** Determine the user-facing historical-import state from persisted source and record outcomes. */
+    private function get_historical_import_lifecycle_state() {
+        global $wpdb;
+        $report = $this->get_historical_import_report_summary();
+        if (empty($report['available'])) {
+            return ['state' => 'technical', 'report' => $report];
+        }
+        $slimstat = statpl_db_get_row(statpl_db_prepare(
+            "SELECT status FROM {$this->view_import_state_table} WHERE source = %s LIMIT 1", 'slimstat'
+        ), ARRAY_A);
+        $sources = statpl_db_get_results("SELECT status FROM {$this->view_sources_table}", ARRAY_A);
+        if (!empty($wpdb->last_error) || !is_array($sources)) {
+            return ['state' => 'importing', 'report' => $report];
+        }
+        $probe = (string) get_option('statpl_history_slimstat_probe', 'not_checked');
+        $discovery = (string) get_option('statpl_history_discovery_status', 'not_checked');
+        $slimstat_pending = is_array($slimstat) && in_array((string) ($slimstat['status'] ?? ''), ['pending','running'], true);
+        $technical = in_array($probe, ['missing_tables','incompatible_schema','database_error'], true)
+            || ($slimstat_pending && $probe === 'not_installed')
+            || in_array($discovery, ['provider_error','invalid_registry','lock_unavailable','lock_session_lost'], true);
+        if (in_array($discovery, ['busy','not_checked','unknown'], true)) {
+            return ['state' => 'importing', 'report' => $report];
+        }
+        $has_source = is_array($slimstat) || !empty($sources);
+        $active = false;
+        foreach ($sources as $source) {
+            if (in_array((string) ($source['status'] ?? ''), ['detected','importing','retry_wait'], true)) {
+                $active = true;
+            }
+            if (in_array((string) ($source['status'] ?? ''), ['needs_attention','partial'], true)) {
+                $technical = true;
+            }
+        }
+        if ($slimstat_pending && !$technical) {
+            $active = true;
+        }
+        $unavailable_active_origins = statpl_db_get_var(
+            "SELECT COUNT(*) FROM {$this->view_source_origins_table} WHERE detection_status = 'available' AND status = 'unavailable'"
+        );
+        if (empty($wpdb->last_error) && (int) $unavailable_active_origins > 0) {
+            $technical = true;
+        }
+        if ($active || (int) ($report['pending_retries'] ?? 0) > 0) {
+            return ['state' => 'importing', 'report' => $report];
+        }
+        if (!$has_source) {
+            return ['state' => $technical ? 'technical' : 'none', 'report' => $report];
+        }
+        if ((int) $report['failed'] > 0) {
+            return ['state' => ((int) $report['imported'] > 0) ? 'partial' : 'technical', 'report' => $report];
+        }
+        if ($technical) {
+            return ['state' => ((int) $report['imported'] > 0) ? 'partial' : 'technical', 'report' => $report];
+        }
+        if ((int) $report['eligible'] === 0) {
+            return ['state' => 'none', 'report' => $report];
+        }
+        return ['state' => 'success', 'report' => $report];
+    }
+
+    /** Render the same concise historical-import notice above both dashboard views. */
+    private function render_historical_import_notice() {
+        $lifecycle = $this->get_historical_import_lifecycle_state();
+        $state = (string) ($lifecycle['state'] ?? 'importing');
+
+        // The in-progress notice remains visible while work is active. A terminal
+        // notice is presented only once for the lifetime of the current Statora
+        // data set; the marker is a Statora-owned option and is removed by the
+        // explicit data-deletion path. Retention/reactivation preserves it.
+        if ($state !== 'importing') {
+            $notice_marker = 'statpl_history_final_notice_shown';
+            if (get_option($notice_marker, '') !== '') {
+                return;
+            }
+            // add_option() is atomic for a unique option_name. Only the request
+            // that successfully creates the marker may render the final notice.
+            if (!add_option($notice_marker, $state, '', false)) {
+                return;
+            }
+            // Start the short report-access window when the terminal notice is
+            // first rendered, not when the administrator later opens the report.
+            if (in_array($state, ['partial','technical'], true)) {
+                update_option('statpl_history_final_notice_at', time(), false);
+            }
+        }
+
+        $report_url = admin_url('admin.php?page=statpl-history-report');
+        $messages = [
+            'importing' => ['title' => 'Επεξεργασία ιστορικού', 'body' => 'Η αρχική εισαγωγή των ιστορικών προβολών προϊόντων βρίσκεται σε εξέλιξη. Τα στατιστικά ενδέχεται να μην είναι ακόμη πλήρη μέχρι να ολοκληρωθεί η διαδικασία.'],
+            'success' => ['title' => 'Το Statora Plus είναι έτοιμο!', 'body' => 'Η εισαγωγή των προηγούμενων καταγεγραμμένων προβολών για τα προϊόντα του καταστήματός σας ολοκληρώθηκε επιτυχώς.'],
+            'partial' => ['title' => 'Το Statora Plus είναι έτοιμο!', 'body' => 'Η εισαγωγή των προηγούμενων καταγεγραμμένων προβολών για τα προϊόντα του καταστήματός σας ολοκληρώθηκε μερικώς.'],
+            'none' => ['title' => 'Το Statora Plus είναι έτοιμο!', 'body' => 'Δεν βρέθηκαν διαθέσιμες προηγούμενες καταγεγραμμένες προβολές προϊόντων για εισαγωγή.'],
+            'technical' => ['title' => 'Το Statora Plus είναι έτοιμο!', 'body' => 'Δεν ήταν δυνατή η εισαγωγή των προηγούμενων καταγεγραμμένων προβολών των προϊόντων σας λόγω τεχνικού προβλήματος.'],
+        ];
+        $message = $messages[$state] ?? $messages['importing'];
+        echo '<div class="statpl-history-notice statpl-history-notice-' . esc_attr($state) . '" role="status" aria-live="polite">';
+        echo '<button type="button" class="statpl-history-notice-close" aria-label="Κλείσιμο ειδοποίησης">&times;</button>';
+        if ($state === 'importing') { echo '<span class="statpl-history-notice-icon dashicons dashicons-info-outline" aria-hidden="true"></span>'; }
+        echo '<strong>' . esc_html($message['title']) . '</strong>';
+        echo '<p>' . esc_html($message['body']) . '</p>';
+        if ($state !== 'importing') {
+            if ($state === 'none') {
+                echo '<p>Το Statora Plus ξεκινά την καταγραφή των προβολών των προϊόντων σας από τώρα και λειτουργεί αυτόνομα.</p>';
+            } elseif ($state === 'success') {
+                echo '<p>Από εδώ και στο εξής, το Statora Plus καταγράφει αυτόνομα τις νέες προβολές των προϊόντων σας.</p>';
+            } else {
+                echo '<p>Το Statora Plus συνεχίζει να καταγράφει αυτόνομα τις νέες προβολές των προϊόντων σας.</p>';
+            }
+            echo '<p><strong>Δεν απαιτείται κάποια άλλη ενέργεια εκ μέρους σας.</strong></p>';
+        }
+        if (in_array($state, ['partial','technical'], true)) {
+            echo '<a class="statpl-history-report-link" href="' . esc_url($report_url) . '">Περισσότερες πληροφορίες →</a>';
+        }
+        echo '</div>';
+    }
+
+    /** Settings page with an administrator-friendly, privacy-safe import summary. */
+    public function render_historical_import_report_page() {
+        if (!current_user_can('manage_woocommerce')) {
+            wp_die(esc_html__('Δεν έχεις δικαίωμα προβολής αυτής της σελίδας.', 'statora-plus'));
+        }
+        $notice_state = (string) get_option('statpl_history_final_notice_shown', '');
+        $notice_time = absint(get_option('statpl_history_final_notice_at', 0));
+        $report_window_seconds = 15 * MINUTE_IN_SECONDS;
+        $report_is_available = in_array($notice_state, ['partial','technical'], true)
+            && $notice_time > 0
+            && time() >= $notice_time
+            && (time() - $notice_time) < $report_window_seconds;
+        if (!$report_is_available) {
+            wp_safe_redirect(admin_url('admin.php?page=statpl-product-metrics'));
+            exit;
+        }
+        $report = $this->get_historical_import_report_summary();
+        $lifecycle = $this->get_historical_import_lifecycle_state();
+        echo '<div class="wrap"><h1>Αρχική εγκατάσταση και ιστορικό προβολών</h1>';
+        if (($lifecycle['state'] ?? '') === 'technical') {
+            echo '<p>Δεν ήταν δυνατή η ολοκλήρωση της ανάγνωσης μίας διαθέσιμης πηγής ιστορικών προβολών. Το Statora Plus συνεχίζει αυτόνομα την καταγραφή νέων προβολών προϊόντων.</p>';
+            $slimstat_probe = (string) get_option('statpl_history_slimstat_probe', '');
+            if (in_array($slimstat_probe, ['missing_tables','incompatible_schema','database_error'], true)) {
+                echo '<p><strong>SlimStat:</strong> Δεν ήταν δυνατή η ανάγνωση των ιστορικών δεδομένων του.</p>';
+            }
+        } elseif (($lifecycle['state'] ?? '') === 'partial') {
+            echo '<p>Η εισαγωγή ολοκληρώθηκε με μερικό αποτέλεσμα. Οι εγγραφές που εισήχθησαν επιτυχώς διατηρούνται και η αυτόνομη καταγραφή συνεχίζεται.</p>';
+        }
+        if (empty($report['available'])) {
+            echo '<p>Η αναλυτική αναφορά δεν είναι προσωρινά διαθέσιμη. Τα στατιστικά του καταστήματος δεν επηρεάζονται.</p></div>';
+            return;
+        }
+        echo '<p>Συγκεντρωτικά αποτελέσματα εισαγωγής ιστορικών προβολών προϊόντων.</p>';
+        echo '<table class="widefat striped"><thead><tr><th>Πηγή</th><th>Επιλέξιμες εγγραφές</th><th>Εισήχθησαν</th><th>Δεν εισήχθησαν</th><th>Σε επαναπροσπάθεια</th><th>Επιλύθηκαν με επαναπροσπάθεια</th><th>Οριστικές αποτυχίες</th><th>Αιτία αποτυχίας</th></tr></thead><tbody>';
+        if (empty($report['sources'])) {
+            echo '<tr><td colspan="8">Δεν υπάρχουν διαθέσιμα ιστορικά δεδομένα προς αναφορά.</td></tr>';
+        } else {
+            foreach ($report['sources'] as $row) {
+                echo '<tr><td>' . esc_html((string) $row['source_name']) . '</td><td>' . esc_html((string) (int) $row['eligible']) . '</td><td>' . esc_html((string) (int) $row['imported']) . '</td><td>' . esc_html((string) (int) $row['not_imported']) . '</td><td>' . esc_html((string) (int) $row['pending_retries']) . '</td><td>' . esc_html((string) (int) $row['retry_resolved']) . '</td><td>' . esc_html((string) (int) $row['final_failures']) . '</td><td>' . ((int) $row['failed'] > 0 ? 'Ορισμένες εγγραφές δεν μπόρεσαν να καταγραφούν μετά από επαναπροσπάθειες.' : '—') . '</td></tr>';
+            }
+        }
+        echo '</tbody></table>';
+        if ((int) $report['failed'] > 0) {
+            echo '<h2>Τι σημαίνουν τα αποτελέσματα</h2><p>Ορισμένες ιστορικές εγγραφές δεν ήταν δυνατό να εισαχθούν. Οι επιτυχημένες εισαγωγές διατηρούνται και το Statora Plus συνεχίζει κανονικά την αυτόνομη καταγραφή νέων προβολών.</p>';
+        }
+        echo '<p>Η αναφορά περιέχει μόνο συγκεντρωτικά αποτελέσματα. Δεν αποθηκεύονται ή εμφανίζονται προσωπικά στοιχεία επισκεπτών.</p></div>';
+    }
+
+    /** Verify every required column before persisting a schema-version marker. */
+    private function verify_historical_table_columns($table, $required_columns) {
+        global $wpdb;
+
+        if (!is_object($wpdb) || !isset($wpdb->last_error) || !is_string($table) || !is_array($required_columns)) {
+            return false;
+        }
+
+        // Only Statora-owned tables may be inspected by this helper. Validate the
+        // complete identifier here rather than relying on each caller to do so.
+        $allowed_tables = [
+            $this->views_table,
+            $this->events_table,
+            $this->order_events_table,
+            $this->order_items_table,
+            $this->view_imports_table,
+            $this->view_import_state_table,
+            $this->view_import_events_table,
+            $this->view_import_failures_table,
+            $this->view_sources_table,
+            $this->view_source_origins_table,
+            $this->view_source_state_table,
+            $this->view_source_events_table,
+            $this->view_source_failures_table,
+            $this->view_source_reconciliation_table,
+            $this->view_source_reconciliation_history_table,
+            $this->historical_import_report_table,
+        ];
+        if (!in_array($table, $allowed_tables, true) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+            return false;
+        }
+        foreach ($required_columns as $column) {
+            if (!is_string($column) || !preg_match('/^[A-Za-z0-9_]+$/D', $column)) {
+                return false;
+            }
+        }
+
+        // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is restricted to the explicit Statora-owned table allowlist and quoted as one identifier.
+        $rows = statpl_db_get_results("SHOW COLUMNS FROM `{$table}`", ARRAY_A);
+        if ($wpdb->last_error !== '' || !is_array($rows)) {
+            return false;
+        }
+
+        $found = [];
+        foreach ($rows as $row) {
+            if (isset($row['Field'])) {
+                $found[$row['Field']] = true;
+            }
+        }
+
+        foreach ($required_columns as $column) {
+            if (!isset($found[$column])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private function maybe_upgrade_view_import_schema() {
+    global $wpdb;
+
+    $schema_version = get_option('statpl_view_import_schema_version', '');
+
+    if ($schema_version === self::VIEW_IMPORT_SCHEMA_VERSION) {
+        return;
+    }
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    $collate = $wpdb->get_charset_collate();
+
+    dbDelta("CREATE TABLE {$this->view_imports_table} (
+        id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+        source VARCHAR(50) NOT NULL,
+        product_id BIGINT(20) UNSIGNED NOT NULL,
+        imported_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+        imported_at DATETIME NOT NULL,
+        PRIMARY KEY  (id),
+        UNIQUE KEY source_product (source, product_id),
+        KEY imported_at (imported_at)
+    ) $collate;");
+
+    $table_exists = statpl_db_get_var(
+        statpl_db_prepare(
+            'SHOW TABLES LIKE %s',
+            $wpdb->esc_like($this->view_imports_table)
+        )
+    );
+
+    if ($table_exists === $this->view_imports_table && $this->verify_historical_table_columns($this->view_imports_table, ['id', 'source', 'product_id', 'imported_views', 'imported_at'])) {
+        if (!$this->persist_schema_version_marker('statpl_view_import_schema_version', self::VIEW_IMPORT_SCHEMA_VERSION)) { return false; }
+    }
+}
+private function maybe_upgrade_view_import_state_schema() {
+    global $wpdb;
+
+    $schema_version = get_option('statpl_view_import_state_schema_version', '');
+
+    if ($schema_version === self::VIEW_IMPORT_STATE_SCHEMA_VERSION) {
+        return;
+    }
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    $collate = $wpdb->get_charset_collate();
+
+    dbDelta("CREATE TABLE {$this->view_import_state_table} (
+        source VARCHAR(50) NOT NULL,
+            snapshot_max_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            snapshot_active_max_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            snapshot_archive_max_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            last_processed_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (source)
+    ) $collate;");
+
+    $table_exists = statpl_db_get_var(
+        statpl_db_prepare(
+            'SHOW TABLES LIKE %s',
+            $wpdb->esc_like($this->view_import_state_table)
+        )
+    );
+
+    if ($table_exists === $this->view_import_state_table && $this->verify_historical_table_columns($this->view_import_state_table, ['source', 'snapshot_max_id', 'snapshot_active_max_id', 'snapshot_archive_max_id', 'last_processed_id', 'status', 'updated_at'])) {
+        if (!$this->persist_schema_version_marker('statpl_view_import_state_schema_version', self::VIEW_IMPORT_STATE_SCHEMA_VERSION)) { return false; }
+    }
+}
+
+private function maybe_upgrade_view_import_events_schema() {
+    global $wpdb;
+
+    $schema_version = get_option('statpl_view_import_events_schema_version', '');
+
+    if ($schema_version === self::VIEW_IMPORT_EVENTS_SCHEMA_VERSION) {
+        return;
+    }
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    $collate = $wpdb->get_charset_collate();
+
+    dbDelta("CREATE TABLE {$this->view_import_events_table} (
+        id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source VARCHAR(50) NOT NULL,
+            source_view_id BIGINT(20) UNSIGNED NOT NULL,
+            product_id BIGINT(20) UNSIGNED NOT NULL,
+            imported_at DATETIME NOT NULL,
+            counts_applied TINYINT(1) UNSIGNED NOT NULL DEFAULT 1,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_view (source, source_view_id),
+            KEY product_id (product_id)
+    ) $collate;");
+
+    $table_exists = statpl_db_get_var(
+        statpl_db_prepare(
+            'SHOW TABLES LIKE %s',
+            $wpdb->esc_like($this->view_import_events_table)
+        )
+    );
+
+    $column_exists = false;
+
+    if ($table_exists === $this->view_import_events_table) {
+        // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The table identifier is built from the WordPress prefix and a fixed plugin suffix.
+        $column_exists = statpl_db_get_var(
+            statpl_db_prepare(
+                "SHOW COLUMNS FROM {$this->view_import_events_table} LIKE %s",
+                'counts_applied'
+            )
+        );
+    }
+
+    if (
+        $table_exists === $this->view_import_events_table
+        && 'counts_applied' === $column_exists
+        && $this->verify_historical_table_columns($this->view_import_events_table, ['id', 'source', 'source_view_id', 'product_id', 'imported_at', 'counts_applied'])
+    ) {
+        if (!$this->persist_schema_version_marker('statpl_view_import_events_schema_version', self::VIEW_IMPORT_EVENTS_SCHEMA_VERSION)) { return false; }
+    }
+}
+
+private function maybe_upgrade_view_import_failures_schema() {
+    global $wpdb;
+
+    $schema_version = get_option('statpl_view_import_failures_schema_version', '');
+
+    if ($schema_version === self::VIEW_IMPORT_FAILURES_SCHEMA_VERSION) {
+        return;
+    }
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    $collate = $wpdb->get_charset_collate();
+
+    dbDelta("CREATE TABLE {$this->view_import_failures_table} (
+        id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+        source VARCHAR(50) NOT NULL,
+        source_view_id BIGINT(20) UNSIGNED NOT NULL,
+        product_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+        attempts INT(10) UNSIGNED NOT NULL DEFAULT 0,
+        last_error TEXT NOT NULL,
+        status VARCHAR(20) NOT NULL DEFAULT 'retry',
+        updated_at DATETIME NOT NULL,
+        PRIMARY KEY  (id),
+        UNIQUE KEY source_view (source, source_view_id),
+        KEY status (status)
+    ) $collate;");
+
+    $table_exists = statpl_db_get_var(
+        statpl_db_prepare(
+            'SHOW TABLES LIKE %s',
+            $wpdb->esc_like($this->view_import_failures_table)
+        )
+    );
+
+    if ($table_exists === $this->view_import_failures_table && $this->verify_historical_table_columns($this->view_import_failures_table, ['id', 'source', 'source_view_id', 'product_id', 'attempts', 'last_error', 'status', 'updated_at'])) {
+        if (!$this->persist_schema_version_marker('statpl_view_import_failures_schema_version', self::VIEW_IMPORT_FAILURES_SCHEMA_VERSION)) { return false; }
+    }
+}
+
+private function maybe_upgrade_view_source_schema() {
+    global $wpdb;
+
+    $schema_version = self::VIEW_SOURCE_SCHEMA_VERSION;
+    if (get_option('statpl_view_source_schema_version', '') === $schema_version) {
+        return true;
+    }
+
+    $collate = $wpdb->get_charset_collate();
+
+    $tables = [
+        $this->view_sources_table,
+        $this->view_source_origins_table,
+        $this->view_source_state_table,
+        $this->view_source_events_table,
+        $this->view_source_failures_table,
+        $this->view_source_reconciliation_table,
+        $this->view_source_reconciliation_history_table,
+    ];
+
+    $definitions = [
+        $this->view_sources_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'source_key' => ['varchar(100)', 'NO', null, false],
+                'adapter_key' => ['varchar(100)', 'YES', null, false],
+                'display_name' => ['varchar(191)', 'NO', null, false],
+                'adapter_version' => ['varchar(32)', 'NO', null, false],
+                'granularity' => ['varchar(20)', 'NO', null, false],
+                'status' => ['varchar(20)', 'NO', 'detected', false],
+                'created_at' => ['datetime', 'NO', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'source_key' => [true, ['source_key']],
+                'status' => [false, ['status']],
+            ],
+        ],
+        $this->view_source_origins_table => [
+            'columns' => [
+                'source_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'origin_key' => ['varchar(100)', 'NO', null, false],
+                'adapter_key' => ['varchar(100)', 'NO', null, false],
+                'capabilities' => ['longtext', 'YES', null, false],
+                'snapshot_data' => ['longtext', 'YES', null, false],
+                'checkpoint_data' => ['longtext', 'YES', null, false],
+                'detection_status' => ['varchar(20)', 'NO', 'unknown', false],
+                'status' => ['varchar(20)', 'NO', 'pending', false],
+                'last_error' => ['text', 'YES', null, false],
+                'started_at' => ['datetime', 'YES', null, false],
+                'completed_at' => ['datetime', 'YES', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['source_id', 'origin_key']],
+                'status' => [false, ['status']],
+            ],
+        ],
+        $this->view_source_state_table => [
+            'columns' => [
+                'source_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'snapshot_data' => ['longtext', 'YES', null, false],
+                'checkpoint_data' => ['longtext', 'YES', null, false],
+                'status' => ['varchar(20)', 'NO', 'pending', false],
+                'last_error' => ['text', 'YES', null, false],
+                'started_at' => ['datetime', 'YES', null, false],
+                'completed_at' => ['datetime', 'YES', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['source_id']],
+                'status' => [false, ['status']],
+            ],
+        ],
+        $this->view_source_events_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'source_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'source_record_key' => ['varchar(191)', 'NO', null, false],
+                'source_record_hash' => ['char(64)', 'NO', null, false],
+                'product_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'record_type' => ['varchar(20)', 'NO', 'event', false],
+                'period_start' => ['datetime', 'YES', null, false],
+                'period_end' => ['datetime', 'YES', null, false],
+                'observed_views' => ['bigint(20) unsigned', 'NO', '0', false],
+                'applied_views' => ['bigint(20) unsigned', 'NO', '0', false],
+                'source_fingerprint' => ['char(64)', 'YES', null, false],
+                'status' => ['varchar(20)', 'NO', 'pending', false],
+                'created_at' => ['datetime', 'NO', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'source_record' => [true, ['source_id', 'source_record_hash']],
+                'product_id' => [false, ['product_id']],
+                'source_product' => [false, ['source_id', 'product_id']],
+                'source_fingerprint' => [false, ['source_fingerprint']],
+                'product_record_period' => [false, ['product_id', 'record_type', 'period_start', 'period_end']],
+                'status' => [false, ['status']],
+            ],
+        ],
+        $this->view_source_reconciliation_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'event_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'status' => ['varchar(30)', 'NO', 'unprocessed', false],
+                'reason_code' => ['varchar(100)', 'NO', null, false],
+                'reason' => ['text', 'YES', null, false],
+                'matched_event_id' => ['bigint(20) unsigned', 'YES', null, false],
+                'evidence' => ['longtext', 'YES', null, false],
+                'algorithm_version' => ['varchar(32)', 'NO', null, false],
+                'created_at' => ['datetime', 'NO', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'event_id' => [true, ['event_id']],
+                'status' => [false, ['status']],
+                'matched_event_id' => [false, ['matched_event_id']],
+            ],
+        ],
+        $this->view_source_reconciliation_history_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'event_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'previous_status' => ['varchar(30)', 'YES', null, false],
+                'new_status' => ['varchar(30)', 'NO', null, false],
+                'reason_code' => ['varchar(100)', 'NO', null, false],
+                'reason' => ['text', 'YES', null, false],
+                'matched_event_id' => ['bigint(20) unsigned', 'YES', null, false],
+                'evidence' => ['longtext', 'YES', null, false],
+                'algorithm_version' => ['varchar(32)', 'NO', null, false],
+                'created_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'event_id' => [false, ['event_id']],
+                'created_at' => [false, ['created_at']],
+            ],
+        ],
+        $this->view_source_failures_table => [
+            'columns' => [
+                'id' => ['bigint(20) unsigned', 'NO', null, true],
+                'source_id' => ['bigint(20) unsigned', 'NO', null, false],
+                'origin_key' => ['varchar(100)', 'NO', null, false],
+                'source_record_key' => ['varchar(191)', 'NO', null, false],
+                'source_record_hash' => ['char(64)', 'NO', null, false],
+                'product_id' => ['bigint(20) unsigned', 'NO', '0', false],
+                'attempts' => ['int(10) unsigned', 'NO', '0', false],
+                'last_error' => ['text', 'NO', null, false],
+                'status' => ['varchar(20)', 'NO', 'retry', false],
+                'next_retry_at' => ['datetime', 'YES', null, false],
+                'retry_checkpoint' => ['longtext', 'YES', null, false],
+                'updated_at' => ['datetime', 'NO', null, false],
+            ],
+            'indexes' => [
+                'PRIMARY' => [true, ['id']],
+                'source_record' => [true, ['source_id', 'source_record_hash']],
+                'status_retry' => [false, ['status', 'next_retry_at']],
+                'source_origin' => [false, ['source_id', 'origin_key']],
+                'product_id' => [false, ['product_id']],
+            ],
+        ],
+    ];
+
+    $sql = [
+        "CREATE TABLE {$this->view_sources_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source_key VARCHAR(100) NOT NULL,
+            adapter_key VARCHAR(100) NULL DEFAULT NULL,
+            display_name VARCHAR(191) NOT NULL,
+            adapter_version VARCHAR(32) NOT NULL,
+            granularity VARCHAR(20) NOT NULL,
+            status VARCHAR(20) NOT NULL DEFAULT 'detected',
+            created_at DATETIME NOT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_key (source_key),
+            KEY status (status)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_origins_table} (
+            source_id BIGINT(20) UNSIGNED NOT NULL,
+            origin_key VARCHAR(100) NOT NULL,
+            adapter_key VARCHAR(100) NOT NULL,
+            capabilities LONGTEXT NULL DEFAULT NULL,
+            snapshot_data LONGTEXT NULL DEFAULT NULL,
+            checkpoint_data LONGTEXT NULL DEFAULT NULL,
+            detection_status VARCHAR(20) NOT NULL DEFAULT 'unknown',
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
+            last_error TEXT NULL DEFAULT NULL,
+            started_at DATETIME NULL DEFAULT NULL,
+            completed_at DATETIME NULL DEFAULT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (source_id, origin_key),
+            KEY status (status)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_state_table} (
+            source_id BIGINT(20) UNSIGNED NOT NULL,
+            snapshot_data LONGTEXT NULL DEFAULT NULL,
+            checkpoint_data LONGTEXT NULL DEFAULT NULL,
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
+            last_error TEXT NULL DEFAULT NULL,
+            started_at DATETIME NULL DEFAULT NULL,
+            completed_at DATETIME NULL DEFAULT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (source_id),
+            KEY status (status)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_events_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source_id BIGINT(20) UNSIGNED NOT NULL,
+            source_record_key VARCHAR(191) NOT NULL,
+            source_record_hash CHAR(64) NOT NULL,
+            product_id BIGINT(20) UNSIGNED NOT NULL,
+            record_type VARCHAR(20) NOT NULL DEFAULT 'event',
+            period_start DATETIME NULL DEFAULT NULL,
+            period_end DATETIME NULL DEFAULT NULL,
+            observed_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            applied_views BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            source_fingerprint CHAR(64) NULL DEFAULT NULL,
+            status VARCHAR(20) NOT NULL DEFAULT 'pending',
+            created_at DATETIME NOT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_record (source_id, source_record_hash),
+            KEY product_id (product_id),
+            KEY source_product (source_id, product_id),
+            KEY source_fingerprint (source_fingerprint),
+            KEY product_record_period (product_id, record_type, period_start, period_end),
+            KEY status (status)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_failures_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            source_id BIGINT(20) UNSIGNED NOT NULL,
+            origin_key VARCHAR(100) NOT NULL,
+            source_record_key VARCHAR(191) NOT NULL,
+            source_record_hash CHAR(64) NOT NULL,
+            product_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
+            attempts INT(10) UNSIGNED NOT NULL DEFAULT 0,
+            last_error TEXT NOT NULL,
+            status VARCHAR(20) NOT NULL DEFAULT 'retry',
+            next_retry_at DATETIME NULL DEFAULT NULL,
+            retry_checkpoint LONGTEXT NULL DEFAULT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY source_record (source_id, source_record_hash),
+            KEY status_retry (status, next_retry_at),
+            KEY source_origin (source_id, origin_key),
+            KEY product_id (product_id)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_reconciliation_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            event_id BIGINT(20) UNSIGNED NOT NULL,
+            status VARCHAR(30) NOT NULL DEFAULT 'unprocessed',
+            reason_code VARCHAR(100) NOT NULL,
+            reason TEXT NULL DEFAULT NULL,
+            matched_event_id BIGINT(20) UNSIGNED NULL DEFAULT NULL,
+            evidence LONGTEXT NULL DEFAULT NULL,
+            algorithm_version VARCHAR(32) NOT NULL,
+            created_at DATETIME NOT NULL,
+            updated_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            UNIQUE KEY event_id (event_id),
+            KEY status (status),
+            KEY matched_event_id (matched_event_id)
+        ) ENGINE=InnoDB $collate;",
+        "CREATE TABLE {$this->view_source_reconciliation_history_table} (
+            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
+            event_id BIGINT(20) UNSIGNED NOT NULL,
+            previous_status VARCHAR(30) NULL DEFAULT NULL,
+            new_status VARCHAR(30) NOT NULL,
+            reason_code VARCHAR(100) NOT NULL,
+            reason TEXT NULL DEFAULT NULL,
+            matched_event_id BIGINT(20) UNSIGNED NULL DEFAULT NULL,
+            evidence LONGTEXT NULL DEFAULT NULL,
+            algorithm_version VARCHAR(32) NOT NULL,
+            created_at DATETIME NOT NULL,
+            PRIMARY KEY  (id),
+            KEY event_id (event_id),
+            KEY created_at (created_at)
+        ) ENGINE=InnoDB $collate;",
+    ];
+
+    $fail = static function ($message) {
+        // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Preserve an actionable migration failure in the PHP error log when schema setup cannot complete.
+        error_log('[Statora Plus] View-source schema migration failed: ' . $message);
+        return false;
+    };
+
+    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
+
+    try {
+        foreach ($sql as $statement) {
+            dbDelta($statement);
+        }
+    } catch (Throwable $e) {
+        return $fail($e->getMessage());
+    }
+
+    // Convert legacy detection values out of the processing-status column.
+    // Existing processing states are preserved; only legacy detection labels are migrated.
+    $legacy_status_migration = statpl_db_query(
+        "UPDATE {$this->view_source_origins_table}
+         SET detection_status = CASE
+                 WHEN status IN ('available', 'missing_table', 'incompatible_schema', 'database_error')
+                     THEN status
+                 ELSE 'unknown'
+             END,
+             status = 'pending'
+         WHERE status IN ('detected', 'available', 'missing_table', 'incompatible_schema', 'database_error')"
+    );
+
+    if ($legacy_status_migration === false || $wpdb->last_error !== '') {
+        return $fail('Could not migrate legacy origin detection statuses: ' . $wpdb->last_error);
+    }
+
+    foreach ($tables as $table) {
+        // The migration metadata is the allowlist for identifiers used by the
+        // SHOW COLUMNS / SHOW INDEX statements below. Reject anything outside it.
+        if (
+            !is_string($table)
+            || !array_key_exists($table, $definitions)
+            || !preg_match('/^[A-Za-z0-9_]+$/D', $table)
+        ) {
+            return $fail('Invalid internal table identifier during schema verification.');
+        }
+
+        $found_table = statpl_db_get_var(
+            statpl_db_prepare(
+                'SHOW TABLES LIKE %s',
+                $wpdb->esc_like($table)
+            )
+        );
+
+        if ($wpdb->last_error !== '') {
+            return $fail('Could not inspect table existence for ' . $table . ': ' . $wpdb->last_error);
+        }
+
+        if ($found_table !== $table) {
+            return $fail('Required table was not created: ' . $table);
+        }
+
+        $table_status = statpl_db_get_row(
+            statpl_db_prepare(
+                'SHOW TABLE STATUS LIKE %s',
+                $wpdb->esc_like($table)
+            ),
+            ARRAY_A
+        );
+
+        if ($wpdb->last_error !== '') {
+            return $fail('Could not inspect table engine for ' . $table . ': ' . $wpdb->last_error);
+        }
+
+        if (!$table_status || !isset($table_status['Engine']) || strcasecmp($table_status['Engine'], 'InnoDB') !== 0) {
+            return $fail('Table engine is not InnoDB: ' . $table);
+        }
+
+        // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Identifier is built from the trusted WordPress prefix and fixed plugin suffix.
+        $column_rows = statpl_db_get_results("SHOW COLUMNS FROM `{$table}`", ARRAY_A);
+
+        if ($wpdb->last_error !== '') {
+            return $fail('Could not inspect columns for ' . $table . ': ' . $wpdb->last_error);
+        }
+
+        if (!is_array($column_rows)) {
+            return $fail('Invalid column metadata for ' . $table);
+        }
+
+        $actual_columns = [];
+        foreach ($column_rows as $column) {
+            $actual_columns[$column['Field']] = $column;
+        }
+
+        $expected_columns = $definitions[$table]['columns'];
+
+        if (count($actual_columns) !== count($expected_columns)) {
+            return $fail('Unexpected column count in ' . $table);
+        }
+
+        foreach ($expected_columns as $name => $expected) {
+            if (!isset($actual_columns[$name])) {
+                return $fail('Missing column ' . $table . '.' . $name);
+            }
+
+            $actual = $actual_columns[$name];
+            $actual_type = strtolower((string) $actual['Type']);
+            $actual_null = strtoupper((string) $actual['Null']);
+            $actual_default = $actual['Default'];
+            $actual_extra = strtolower(trim((string) $actual['Extra']));
+            $actual_extra = preg_replace('/\\s+/', ' ', $actual_extra);
+            $expected_extra = $expected[3] ? 'auto_increment' : '';
+
+            if ($actual_type !== $expected[0]) {
+                return $fail('Wrong type for ' . $table . '.' . $name . ': ' . $actual_type);
+            }
+
+            if ($actual_null !== $expected[1]) {
+                return $fail('Wrong NULL definition for ' . $table . '.' . $name);
+            }
+
+            if ($expected[2] === null) {
+                if ($actual_default !== null) {
+                    return $fail('Unexpected default for ' . $table . '.' . $name);
+                }
+            } elseif ((string) $actual_default !== $expected[2]) {
+                return $fail('Wrong default for ' . $table . '.' . $name);
+            }
+
+            if ($actual_extra !== $expected_extra) {
+                return $fail('Wrong Extra definition for ' . $table . '.' . $name . ': ' . $actual_extra);
+            }
+        }
+
+        // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Identifier is built from the trusted WordPress prefix and fixed plugin suffix.
+        $index_rows = statpl_db_get_results("SHOW INDEX FROM `{$table}`", ARRAY_A);
+
+        if ($wpdb->last_error !== '') {
+            return $fail('Could not inspect indexes for ' . $table . ': ' . $wpdb->last_error);
+        }
+
+        if (!is_array($index_rows)) {
+            return $fail('Invalid index metadata for ' . $table);
+        }
+
+        $actual_indexes = [];
+        foreach ($index_rows as $index) {
+            $key_name = $index['Key_name'];
+
+            if (!isset($actual_indexes[$key_name])) {
+                $actual_indexes[$key_name] = [
+                    'unique' => ((int) $index['Non_unique'] === 0),
+                    'columns' => [],
+                ];
+            } elseif ($actual_indexes[$key_name]['unique'] !== ((int) $index['Non_unique'] === 0)) {
+                return $fail('Inconsistent uniqueness metadata for index ' . $table . '.' . $key_name);
+            }
+
+            $sequence = (string) $index['Seq_in_index'];
+            if (!preg_match('/^[1-9][0-9]*$/D', $sequence)) {
+                return $fail('Invalid Seq_in_index for ' . $table . '.' . $key_name);
+            }
+
+            $sequence = (int) $sequence;
+            if (isset($actual_indexes[$key_name]['columns'][$sequence])) {
+                return $fail('Duplicate Seq_in_index for ' . $table . '.' . $key_name);
+            }
+
+            if (!array_key_exists('Sub_part', $index) || $index['Sub_part'] !== null) {
+                return $fail('Unexpected index prefix length for ' . $table . '.' . $key_name);
+            }
+
+            $actual_indexes[$key_name]['columns'][$sequence] = $index['Column_name'];
+        }
+
+        foreach ($actual_indexes as $key_name => &$index_data) {
+            ksort($index_data['columns']);
+            $positions = array_keys($index_data['columns']);
+
+            if ($positions !== range(1, count($positions))) {
+                return $fail('Non-contiguous Seq_in_index for ' . $table . '.' . $key_name);
+            }
+
+            $index_data['columns'] = array_values($index_data['columns']);
+        }
+        unset($index_data);
+
+        $expected_indexes = $definitions[$table]['indexes'];
+
+        if (count($actual_indexes) !== count($expected_indexes)) {
+            return $fail('Unexpected index count in ' . $table);
+        }
+
+        foreach ($expected_indexes as $name => $expected) {
+            if (!isset($actual_indexes[$name])) {
+                return $fail('Missing index ' . $table . '.' . $name);
+            }
+
+            if (
+                $actual_indexes[$name]['unique'] !== $expected[0]
+                || $actual_indexes[$name]['columns'] !== $expected[1]
+            ) {
+                return $fail('Incorrect index definition for ' . $table . '.' . $name);
+            }
+        }
+    }
+
+    update_option('statpl_view_source_schema_version', $schema_version, false);
+
+    if (get_option('statpl_view_source_schema_version', '') !== $schema_version) {
+        return $fail('Could not persist the verified view-source schema version.');
+    }
+
+    return true;
+}
+
+    /**
+     * Reclassify legacy aggregate matches that relied on the synthetic
+     * product/date/count fingerprint. This is audit-only: totals and
+     * applied_views are deliberately not modified because the old records
+     * cannot prove whether the underlying views were actually duplicated.
+     */
+    private function migrate_legacy_aggregate_fingerprint_matches() {
+        global $wpdb;
+
+        $complete_option = 'statpl_legacy_aggregate_fp_migration_v1_complete';
+        $cursor_option = 'statpl_legacy_aggregate_fp_migration_v1_cursor';
+        if (get_option($complete_option, '') === '1') {
+            return true;
+        }
+
+        $lock_name = 'statpl_legacy_agg_' . substr(hash('sha256', $wpdb->prefix), 0, 40);
+        $migration_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($migration_lock['acquired'])) {
+            $this->schedule_legacy_aggregate_reconciliation_migration(60);
+            return false;
+        }
+
+        $batch_size = 100;
+        $cursor = max(0, (int) get_option($cursor_option, 0));
+        $processed = 0;
+        $failed = false;
+        $migration_transaction_started = false;
+        $migration_transaction_committed = false;
+
+        try {
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                "SELECT r.event_id, r.status, r.reason_code, r.reason, r.matched_event_id,
+                        r.evidence, r.algorithm_version,
+                        e.source_id, e.product_id, e.record_type, e.observed_views,
+                        e.period_start, e.period_end, e.source_fingerprint,
+                        m.source_id AS matched_source_id,
+                        m.record_type AS matched_record_type,
+                        m.source_fingerprint AS matched_source_fingerprint
+                 FROM {$this->view_source_reconciliation_table} r
+                 INNER JOIN {$this->view_source_events_table} e ON e.id = r.event_id
+                 INNER JOIN {$this->view_source_events_table} m ON m.id = r.matched_event_id
+                 WHERE r.event_id > %d
+                   AND r.status = 'matched_exact'
+                   AND r.reason_code = 'shared_fingerprint_exact_match'
+                   AND e.record_type = 'aggregate'
+                   AND m.record_type = 'aggregate'
+                   AND e.source_id <> m.source_id
+                 ORDER BY r.event_id ASC
+                 LIMIT %d",
+                $cursor,
+                $batch_size
+            ), ARRAY_A);
+
+            if (!is_array($rows)) {
+                $failed = true;
+                return false;
+            }
+
+            foreach ($rows as $row) {
+                $event_id = (int) $row['event_id'];
+                $expected_fingerprint = '';
+                if ($row['period_start'] !== null && $row['period_end'] !== null) {
+                    $expected_fingerprint = hash(
+                        'sha256',
+                        "statpl-product-day-aggregate-v1\0"
+                        . (int) $row['product_id'] . "\0"
+                        . (string) $row['period_start'] . "\0"
+                        . (string) $row['period_end'] . "\0"
+                        . (int) $row['observed_views']
+                    );
+                }
+
+                $is_legacy_synthetic_match = $expected_fingerprint !== ''
+                    && is_string($row['source_fingerprint'])
+                    && is_string($row['matched_source_fingerprint'])
+                    && hash_equals($expected_fingerprint, strtolower($row['source_fingerprint']))
+                    && hash_equals($expected_fingerprint, strtolower($row['matched_source_fingerprint']));
+
+                if ($is_legacy_synthetic_match) {
+                    $evidence = json_decode((string) $row['evidence'], true);
+                    if (!is_array($evidence)) {
+                        $evidence = ['legacy_evidence_raw' => (string) $row['evidence']];
+                    }
+                    $evidence['legacy_reclassification'] = [
+                        'migration' => 'legacy_aggregate_fingerprint_v1',
+                        'previous_status' => 'matched_exact',
+                        'new_status' => 'legacy_exact_unverified',
+                        'reason' => 'The previous synthetic fingerprint represented product, date and count, not a shared view-event identity. The old exact-match decision is therefore unverified.',
+                        'totals_changed' => false,
+                        'applied_views_changed' => false,
+                    ];
+                    $encoded_evidence = wp_json_encode($evidence);
+                    if (!is_string($encoded_evidence)) {
+                        $failed = true;
+                        return false;
+                    }
+
+                    if (!$this->generic_advisory_lock_session_is_current($migration_lock)) {
+                        $failed = true;
+                        return false;
+                    }
+
+                    $migration_transaction_started = false;
+                    $migration_transaction_committed = false;
+                    $transaction_started = (statpl_db_query('START TRANSACTION') !== false);
+                    if (!$transaction_started) {
+                        $failed = true;
+                        return false;
+                    }
+
+                    $migration_transaction_started = true;
+                    if (!$this->generic_advisory_lock_session_is_current($migration_lock)) {
+                        // Lock ownership and connection identity are separate checks.
+                        // Roll back only when this is still the original DB session.
+                        if ($this->generic_db_session_matches_lock($migration_lock)) {
+                            statpl_db_query('ROLLBACK');
+                            $migration_transaction_started = false;
+                        }
+                        $failed = true;
+                        return false;
+                    }
+                    $updated = statpl_db_update(
+                        $this->view_source_reconciliation_table,
+                        [
+                            'status' => 'legacy_exact_unverified',
+                            'reason_code' => 'legacy_aggregate_fingerprint_unverified',
+                            'reason' => 'Legacy exact match based on product/date/count only; actual shared view identity was not established. Totals were intentionally left unchanged pending a controlled reconciliation decision.',
+                            'evidence' => $encoded_evidence,
+                            'algorithm_version' => '1.2.0',
+                            'updated_at' => current_time('mysql'),
+                        ],
+                        ['event_id' => $event_id, 'status' => 'matched_exact']
+                    );
+                    $history = $updated === 1 ? statpl_db_insert(
+                        $this->view_source_reconciliation_history_table,
+                        [
+                            'event_id' => $event_id,
+                            'previous_status' => 'matched_exact',
+                            'new_status' => 'legacy_exact_unverified',
+                            'reason_code' => 'legacy_aggregate_fingerprint_unverified',
+                            'reason' => 'Reclassified because the legacy aggregate fingerprint did not prove shared view-event identity. No totals or applied_views were changed.',
+                            'matched_event_id' => (int) $row['matched_event_id'],
+                            'evidence' => $encoded_evidence,
+                            'algorithm_version' => '1.2.0',
+                            'created_at' => current_time('mysql'),
+                        ]
+                    ) : false;
+
+                    if ($updated !== 1 || $history !== 1
+                        || !$this->generic_advisory_lock_session_is_current($migration_lock)
+                        || statpl_db_query('COMMIT') === false) {
+                        // Roll back only if the original lock-owning session is still current.
+                        // A reconnect implicitly abandons the old transaction; never issue
+                        // transaction control against an unverified replacement session.
+                        if ($migration_transaction_started && $this->generic_db_session_matches_lock($migration_lock)) {
+                            statpl_db_query('ROLLBACK');
+                            $migration_transaction_started = false;
+                        }
+                        $failed = true;
+                        return false;
+                    }
+                    $migration_transaction_committed = true;
+                    $migration_transaction_started = false;
+                }
+
+                $cursor = $event_id;
+                // Persist the cursor only while this exact MySQL session still owns
+                // the migration lock. A PHP-level check followed by update_option()
+                // would leave a reconnect race between the check and the write.
+                $cursor_persisted = statpl_db_query(statpl_db_prepare(
+                    "INSERT INTO {$wpdb->options} (option_name, option_value, autoload)
+                     SELECT %s, %s, 'no'
+                     WHERE IS_USED_LOCK(%s) = CONNECTION_ID()
+                     ON DUPLICATE KEY UPDATE option_value = IF(
+                         IS_USED_LOCK(%s) = CONNECTION_ID(),
+                         VALUES(option_value),
+                         option_value
+                     )",
+                    $cursor_option,
+                    (string) $cursor,
+                    $lock_name,
+                    $lock_name
+                ));
+                if (!in_array($cursor_persisted, [0, 1, 2], true)
+                    || !$this->generic_advisory_lock_session_is_current($migration_lock)) {
+                    $failed = true;
+                    return false;
+                }
+                $persisted_cursor = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                    $cursor_option
+                ));
+                if (!empty($wpdb->last_error) || (int) $persisted_cursor !== $cursor) {
+                    $failed = true;
+                    return false;
+                }
+                $processed++;
+            }
+
+            if (count($rows) < $batch_size) {
+                // Completion is also lock-owner guarded so a stale/reconnected
+                // worker cannot mark an unfinished migration complete.
+                $complete_persisted = statpl_db_query(statpl_db_prepare(
+                    "INSERT INTO {$wpdb->options} (option_name, option_value, autoload)
+                     SELECT %s, '1', 'no'
+                     WHERE IS_USED_LOCK(%s) = CONNECTION_ID()
+                     ON DUPLICATE KEY UPDATE option_value = IF(
+                         IS_USED_LOCK(%s) = CONNECTION_ID(), '1', option_value
+                     )",
+                    $complete_option,
+                    $lock_name,
+                    $lock_name
+                ));
+                $persisted_completion = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                    $complete_option
+                ));
+                $completion_verified = in_array($complete_persisted, [0, 1, 2], true)
+                    && $this->generic_advisory_lock_session_is_current($migration_lock)
+                    && empty($wpdb->last_error)
+                    && (string) $persisted_completion === '1';
+                if (!$completion_verified) {
+                    $failed = true;
+                }
+                return $completion_verified;
+            }
+
+            $this->schedule_legacy_aggregate_reconciliation_migration(30);
+            return true;
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Legacy aggregate reconciliation audit migration failed: ' . $exception->getMessage());
+            }
+            $failed = true;
+            return false;
+        } finally {
+            if ($migration_transaction_started && !$migration_transaction_committed
+                && $this->generic_db_session_matches_lock($migration_lock)) {
+                statpl_db_query('ROLLBACK');
+                $migration_transaction_started = false;
+            }
+            $this->release_generic_advisory_lock($migration_lock, 'legacy_aggregate_fingerprint_migration');
+            if ($failed) {
+                $this->schedule_legacy_aggregate_reconciliation_migration(60);
+                if (defined('WP_DEBUG') && WP_DEBUG) {
+                    $this->debug_log('[Statora Plus] Legacy aggregate reconciliation audit migration was rescheduled after a failed batch.');
+                }
+            }
+        }
+    }
+
+    /**
+     * Schedule the audit migration outside the normal frontend initialization path.
+     * Action Scheduler is preferred; WP-Cron remains the compatibility fallback.
+     */
+    public function schedule_legacy_aggregate_reconciliation_migration($delay = 15) {
+        if (get_option('statpl_legacy_aggregate_fp_migration_v1_complete', '') === '1') {
+            return;
+        }
+
+        $delay = max(5, (int) $delay);
+        $hook = 'statpl_reconcile_legacy_aggregate_fingerprints';
+        $args = [];
+        $group = 'statpl-plus';
+
+        if (function_exists('as_schedule_single_action') && !did_action('action_scheduler_init')) {
+            add_action('action_scheduler_init', [$this, 'schedule_legacy_aggregate_reconciliation_migration'], 10, 0);
+            return;
+        }
+
+        if (
+            function_exists('as_has_scheduled_action')
+            && did_action('action_scheduler_init')
+            && as_has_scheduled_action($hook, $args, $group)
+        ) {
+            return;
+        }
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $action_id = as_schedule_single_action(time() + $delay, $hook, $args, $group);
+            if ($action_id) {
+                return;
+            }
+        }
+
+        if (!wp_next_scheduled($hook, $args)) {
+            wp_schedule_single_event(time() + $delay, $hook, $args);
+        }
+    }
+
+    public function init_legacy_aggregate_reconciliation_migration() {
+        $this->migrate_legacy_aggregate_fingerprint_matches();
+    }
+
+     public function init() {
+        // Register runtime hooks before touching the database. If MySQL is
+        // temporarily unavailable during plugins_loaded, frontend/AJAX and
+        // WooCommerce hooks must still exist for the remainder of this request.
         add_action('wp_enqueue_scripts', [$this, 'enqueue_frontend']);
         add_action('wp_ajax_statpl_record_view', [$this, 'record_view']);
@@ -113 +1875 @@
         add_action('admin_menu', [$this, 'admin_menu']);
         add_action('admin_enqueue_scripts', [$this, 'enqueue_admin_styles']);
+        add_action('admin_enqueue_scripts', [$this, 'enqueue_deactivation_prompt']);
         add_action('admin_notices', [$this, 'woocommerce_notice']);
+        add_action('admin_footer', [$this, 'enqueue_historical_notice_script']);
         add_action('woocommerce_order_status_cancelled', [$this, 'record_cancel_event'], 10, 2);
         add_action('woocommerce_order_refunded', [$this, 'record_refund_event'], 10, 2);
-        // Invalidate cached aggregates when order data or status changes.
         foreach (['woocommerce_new_order', 'woocommerce_update_order', 'woocommerce_order_status_changed', 'woocommerce_order_payment_status_changed', 'woocommerce_saved_order_items'] as $hook) {
             add_action($hook, [$this, 'invalidate_order_stats_cache'], 10, 3);
         }
         add_action('woocommerce_order_refunded', [$this, 'invalidate_order_stats_cache'], 20, 2);
-        // A refund changes net quantity/revenue in the order snapshot as well as refund-event history.
         add_action('woocommerce_order_refunded', [$this, 'queue_order_snapshot'], 30, 2);
         add_action('woocommerce_before_delete_order', [$this, 'delete_order_snapshot'], 10, 1);
@@ -128 +1890 @@
         }
         add_action('statpl_import_batch', [$this, 'run_import_batch']);
+        add_action('statpl_view_import_batch', [$this, 'run_slimstat_view_import_batch']);
+        add_action('statpl_generic_view_import_batch', [$this, 'run_generic_historical_view_import_batch'], 10, 2);
+        add_action('statpl_generic_view_snapshot_retry', [$this, 'retry_generic_historical_view_snapshot'], 10, 2);
+        add_action('statpl_generic_view_retry_failed_records', [$this, 'retry_generic_historical_view_failures'], 10, 2);
         add_action('statpl_sync_order', [$this, 'sync_order_snapshot'], 10, 1);
-        if (!get_option('statpl_import_complete')) { $this->schedule_import_batch(); }
-    }
+        add_action('statpl_reconcile_legacy_aggregate_fingerprints', [$this, 'init_legacy_aggregate_reconciliation_migration']);
+
+        global $wpdb;
+        // Do not interpret failed option/table reads as missing state. A simple
+        // round-trip probe distinguishes a usable connection from a DB outage.
+        try {
+            $database_ready = isset($wpdb) && is_object($wpdb)
+                && (string) statpl_db_get_var('SELECT 1') === '1'
+                && empty($wpdb->last_error);
+        } catch (Throwable $exception) {
+            $database_ready = false;
+        }
+        if (!$database_ready) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Database unavailable during initialization; schema upgrades and historical discovery will retry on the next request. Runtime hooks remain registered.');
+            }
+            return;
+        }
+
+        try {
+            if (get_option('statpl_db_version') !== self::VERSION) {
+                // Core tables must be verified before historical schema upgrades
+                // or adapter discovery can run. A failed dbDelta pass must leave
+                // the version marker unchanged so the next request retries it.
+                if (!$this->activate()) {
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('[Statora Plus] Core schema verification failed; initialization will retry on the next request.');
+                    }
+                    return;
+                }
+            }
+            $this->maybe_upgrade_view_import_schema();
+            $this->maybe_upgrade_view_import_failures_schema();
+            $this->maybe_upgrade_view_import_state_schema();
+            $this->maybe_upgrade_view_import_events_schema();
+            $this->maybe_upgrade_view_source_schema();
+            $this->maybe_upgrade_historical_import_report_schema();
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Schema initialization interrupted; version markers remain subject to verification and initialization will retry on the next request.');
+            }
+            return;
+        }
+
+        // Schema helpers intentionally leave their version markers unchanged
+        // when verification fails. Do not let discovery/workers query partially
+        // initialized tables; the next request will retry the outstanding steps.
+        $historical_schema_ready =
+            get_option('statpl_view_import_schema_version', '') === self::VIEW_IMPORT_SCHEMA_VERSION
+            && get_option('statpl_view_import_failures_schema_version', '') === self::VIEW_IMPORT_FAILURES_SCHEMA_VERSION
+            && get_option('statpl_view_import_state_schema_version', '') === self::VIEW_IMPORT_STATE_SCHEMA_VERSION
+            && get_option('statpl_view_import_events_schema_version', '') === self::VIEW_IMPORT_EVENTS_SCHEMA_VERSION
+            && get_option('statpl_view_source_schema_version', '') === self::VIEW_SOURCE_SCHEMA_VERSION
+            && get_option('statpl_history_report_schema_version', '') === self::HISTORY_REPORT_SCHEMA_VERSION;
+        if (!$historical_schema_ready) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Historical schema is not fully verified; historical discovery and recovery are deferred until a later request.');
+            }
+            return;
+        }
+
+        // Schedule the audit migration outside the normal request path. The worker
+        // uses bounded batches and a connection-scoped lock for safe continuation.
+        $this->schedule_legacy_aggregate_reconciliation_migration(15);
+
+        // Keep each startup subsystem isolated. A scheduler or adapter-provider
+        // failure in one subsystem must not prevent the remaining durable work
+        // from being discovered and recovered on this request.
+        if (!get_option('statpl_import_complete')) {
+            try {
+                $this->schedule_import_batch();
+            } catch (Throwable $exception) {
+                if (defined('WP_DEBUG') && WP_DEBUG) {
+                    $this->debug_log('[Statora Plus] Core import scheduling failed; it will be retried on a later request.');
+                }
+            }
+        }
+
+        // SlimStat remains on its existing, independent initialization path.
+        // Contain unexpected failures at the call site so they cannot block
+        // generic adapter discovery or recovery.
+        try {
+            $slimstat_result = $this->initialize_slimstat_view_import();
+            if (isset($slimstat_result['status']) && $slimstat_result['status'] !== 'already_initialized') {
+                update_option('statpl_history_slimstat_probe', sanitize_key((string) $slimstat_result['status']), false);
+            } elseif (($slimstat_result['status'] ?? '') === 'already_initialized') {
+                $slimstat_state_status = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT status FROM {$this->view_import_state_table} WHERE source = %s", 'slimstat'
+                ));
+                if (in_array((string) $slimstat_state_status, ['pending','running'], true)) {
+                    $slimstat_probe_result = $this->get_slimstat_view_snapshot();
+                    update_option('statpl_history_slimstat_probe', sanitize_key((string) ($slimstat_probe_result['status'] ?? 'database_error')), false);
+                }
+            }
+            if (
+                is_array($slimstat_result)
+                && isset($slimstat_result['status'])
+                && in_array($slimstat_result['status'], ['initialized', 'already_initialized'], true)
+            ) {
+                try {
+                    $this->schedule_slimstat_view_import_batch();
+                } catch (Throwable $exception) {
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('[Statora Plus] SlimStat import scheduling failed; its existing recovery path will retry.');
+                    }
+                }
+            }
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] SlimStat initialization failed; generic historical sources will continue independently.');
+            }
+        }
+
+        // Discovery failure must not suppress recovery of already persisted
+        // work. Conversely, recovery is attempted even if discovery throws.
+        try {
+            $generic_result = $this->discover_historical_view_adapters();
+            update_option('statpl_history_discovery_status', sanitize_key((string) ($generic_result['status'] ?? 'unknown')), false);
+            if (!empty($generic_result['registered'])) {
+                try {
+                    $this->schedule_generic_historical_view_import_batch(15);
+                } catch (Throwable $exception) {
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('[Statora Plus] Generic historical import scheduling failed; durable work will be recovered later.');
+                    }
+                }
+            }
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Generic adapter discovery failed; persisted historical work recovery will still run.');
+            }
+        }
+
+        if (get_option('statpl_retained_deactivation_at', '') !== '') {
+            $gap_result = $this->resume_retained_history_gap();
+            if (($gap_result['status'] ?? '') === 'reset') {
+                try {
+                    $this->schedule_slimstat_view_import_batch(15);
+                } catch (Throwable $exception) {
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('[Statora Plus] Retained history recovery scheduling failed; it will be retried on a later request.');
+                    }
+                }
+            }
+        }
+
+        try {
+            $this->recover_unscheduled_generic_historical_work();
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('[Statora Plus] Generic historical work recovery failed; it will be retried on a later request.');
+            }
+        }
+        $lifecycle = $this->get_historical_import_lifecycle_state();
+        update_option('statpl_history_import_state', sanitize_key((string) ($lifecycle['state'] ?? 'importing')), false);
+    }
+
     public function woocommerce_notice() {
         if (!current_user_can('manage_options') || class_exists('WooCommerce')) return;
@@ -163 +2084 @@
         $now = current_time('mysql');
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is built from the WordPress prefix and a fixed plugin suffix; this atomic view-count write must not be cached.
-        $wpdb->query($wpdb->prepare(
+        statpl_db_query(statpl_db_prepare(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- Internal table identifier uses the WordPress prefix plus a fixed plugin suffix; product ID is prepared.
             "INSERT INTO {$this->views_table} (product_id, total_views) VALUES (%d, 1)
@@ -169 +2090 @@
         ));
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Event writes must be persisted immediately and cannot be cached.
-        $wpdb->insert($this->events_table, ['product_id' => $product_id, 'viewed_at' => $now], ['%d','%s']);
+        statpl_db_insert($this->events_table, ['product_id' => $product_id, 'viewed_at' => $now], ['%d','%s']);
         setcookie($cookie, '1', time() + 1200, COOKIEPATH ?: '/', COOKIE_DOMAIN, is_ssl(), true);
         $_COOKIE[$cookie] = '1';
@@ -175 +2096 @@
         $cutoff = gmdate('Y-m-d H:i:s', time() - 172800);
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- The identifier is internal and the cutoff is prepared; this cleanup deletes expired rows, so caching is not applicable.
-        $wpdb->query($wpdb->prepare("DELETE FROM {$this->events_table} WHERE viewed_at < %s", get_date_from_gmt($cutoff)));
+        statpl_db_query(statpl_db_prepare("DELETE FROM {$this->events_table} WHERE viewed_at < %s", get_date_from_gmt($cutoff)));
         wp_send_json_success(['counted' => true]);
     }
@@ -187 +2108 @@
         // This prevents a later snapshot sync from making an older cancellation appear to happen today.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; the query values are prepared.
-        $event_at = $wpdb->get_var($wpdb->prepare(
+        $event_at = statpl_db_get_var(statpl_db_prepare(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; both query values are prepared.
             "SELECT MIN(event_at) FROM {$this->order_events_table} WHERE order_id = %d AND event_type = %s AND event_ref_id = 0",
@@ -280 +2201 @@
         // from being counted more than once in the store overview.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all event values are prepared.
-        $wpdb->query($wpdb->prepare(
+        statpl_db_query(statpl_db_prepare(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; all event values are prepared.
             "INSERT INTO {$this->order_events_table} (order_id, product_id, event_type, event_ref_id, event_at) VALUES (%d, 0, %s, %d, %s) ON DUPLICATE KEY UPDATE event_at=LEAST(event_at, VALUES(event_at))",
@@ -288 +2209 @@
         foreach (array_keys($product_ids) as $product_id) {
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all event values are prepared.
-            $wpdb->query($wpdb->prepare(
+            statpl_db_query(statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; all event values are prepared.
                 "INSERT INTO {$this->order_events_table} (order_id, product_id, event_type, event_ref_id, event_at) VALUES (%d, %d, %s, %d, %s) ON DUPLICATE KEY UPDATE event_at=LEAST(event_at, VALUES(event_at))",
@@ -309 +2230 @@
         // Product ID 0 is reserved for order-level dashboard aggregation.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all event values are prepared.
-        $wpdb->query($wpdb->prepare(
+        statpl_db_query(statpl_db_prepare(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; all event values are prepared.
             "INSERT INTO {$this->order_events_table} (order_id, product_id, event_type, event_ref_id, event_at) VALUES (%d, 0, %s, 0, %s) ON DUPLICATE KEY UPDATE event_at=LEAST(event_at, VALUES(event_at))",
@@ -316 +2237 @@
         foreach ($this->order_product_ids($order) as $product_id) {
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all event values are prepared.
-            $wpdb->query($wpdb->prepare(
+            statpl_db_query(statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; all event values are prepared.
                 "INSERT INTO {$this->order_events_table} (order_id, product_id, event_type, event_ref_id, event_at) VALUES (%d, %d, %s, 0, %s) ON DUPLICATE KEY UPDATE event_at=LEAST(event_at, VALUES(event_at))",
@@ -325 +2246 @@
         delete_transient('statpl_global_summary_v2');
     }
+    /** Add a two-choice confirmation dialog to this plugin's Plugins-screen action. */
+    public function enqueue_deactivation_prompt($hook_suffix) {
+        if ($hook_suffix !== 'plugins.php' || !current_user_can('activate_plugins')) {
+            return;
+        }
+        wp_enqueue_script('jquery-core');
+        $config = [
+            'plugin' => plugin_basename(__FILE__),
+            'endpoint' => admin_url('admin-post.php'),
+            'nonce' => wp_create_nonce('statpl_prepare_deactivation'),
+            'title' => 'Απενεργοποίηση Statora Plus',
+            'message' => 'Τι θέλεις να γίνει με τα στατιστικά και τα δεδομένα του Statora Plus;',
+            'retain' => 'Ναι, διατήρηση όλων των δεδομένων',
+            'delete' => 'Όχι, διαγραφή όλων των δεδομένων',
+            'cancel' => 'Ακύρωση',
+            'warning' => 'Η διαγραφή δεν μπορεί να αναιρεθεί.',
+        ];
+        wp_add_inline_script('jquery-core', 'window.StatoraDeactivatePrompt = ' . wp_json_encode($config) . ';', 'before');
+        $js = <<<'STATPL_DEACTIVATION_JS'
+(function () {
+    var cfg = window.StatoraDeactivatePrompt;
+    if (!cfg) return;
+    function findDeactivateLink(target) {
+        var link = target.closest('a');
+        if (!link) return null;
+        try {
+            var url = new URL(link.href, window.location.href);
+            if (url.searchParams.get('action') !== 'deactivate' || url.searchParams.get('plugin') !== cfg.plugin) return null;
+            return link;
+        } catch (e) { return null; }
+    }
+    document.addEventListener('click', function (event) {
+        var link = findDeactivateLink(event.target);
+        if (!link) return;
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        if (document.getElementById('statpl-deactivation-dialog')) return;
+        var dialog = document.createElement('div');
+        dialog.id = 'statpl-deactivation-dialog';
+        dialog.style.cssText = 'position:fixed;inset:0;z-index:100000;background:rgba(0,0,0,.55);display:flex;align-items:center;justify-content:center;padding:20px';
+        var panel = document.createElement('div');
+        panel.style.cssText = 'background:#fff;max-width:520px;width:100%;padding:24px;border-radius:6px;box-shadow:0 8px 32px rgba(0,0,0,.25);font:14px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif';
+        var title = document.createElement('h2'); title.textContent = cfg.title; title.style.marginTop = '0';
+        var message = document.createElement('p'); message.textContent = cfg.message;
+        var warning = document.createElement('p'); warning.textContent = cfg.warning; warning.style.color = '#b32d2e';
+        var actions = document.createElement('div'); actions.style.cssText = 'display:flex;flex-wrap:wrap;gap:8px;margin-top:20px';
+        function button(label, choice, primary) {
+            var b = document.createElement('button'); b.type = 'button'; b.textContent = label;
+            b.className = primary ? 'button button-primary' : 'button';
+            b.addEventListener('click', function () {
+                if (!choice) { dialog.remove(); return; }
+                var destination = new URL(cfg.endpoint, window.location.href);
+                destination.searchParams.set('action', 'statpl_prepare_deactivation');
+                destination.searchParams.set('choice', choice);
+                destination.searchParams.set('_wpnonce', cfg.nonce);
+                destination.searchParams.set('redirect_to', link.href);
+                window.location.assign(destination.toString());
+            });
+            actions.appendChild(b);
+        }
+        button(cfg.retain, 'retain', true);
+        button(cfg.delete, 'delete', false);
+        button(cfg.cancel, '', false);
+        panel.appendChild(title); panel.appendChild(message); panel.appendChild(warning); panel.appendChild(actions);
+        dialog.appendChild(panel); document.body.appendChild(dialog);
+        dialog.addEventListener('click', function (e) { if (e.target === dialog) dialog.remove(); });
+    }, true);
+})();
+STATPL_DEACTIVATION_JS;
+        wp_add_inline_script('jquery-core', $js, 'after');
+    }
+
     public function enqueue_admin_styles($hook_suffix) {
         if ('toplevel_page_statpl-product-metrics' !== $hook_suffix) {
@@ -333 +2326 @@
         $css = <<<'STATPL_CSS'
         .statpl-table-scroll{overflow-x:auto}
-        .statpl-stock-not-tracked{color:#646970}
+        .statpl-stock-not-tracked{color:#646970}.statpl-product-visibility{display:inline-block;margin-left:7px;color:#646970;font-size:12px;font-weight:400}
         .statpl-metrics-wrap .nav-tab{border-color:#c9d7ff;background:#f2f6ff;color:#3155F5;font-weight:600}
         .statpl-metrics-wrap .nav-tab-active{background:#fff;color:#1d2327;border-bottom-color:#fff;border-top:3px solid #3155F5}
@@ -351 +2344 @@
         .statpl-metrics-wrap .notice-success.inline p{color:#263b8f}
         .statpl-metrics-wrap .statpl-overview-note{color:#505b6b}
+        .statpl-history-notice{position:relative;box-sizing:border-box;margin:15px 0;padding:14px 42px 14px 14px;border:1px solid #c5e2a9;border-radius:6px;background:#DDF2C8;color:#000}.statpl-history-notice-importing{background:#D9EEFF;border-color:#b8dcf5}.statpl-history-notice-icon{color:#2271b1;margin-right:6px;vertical-align:middle}.statpl-history-notice p{margin:8px 0;color:#000}.statpl-history-notice strong{color:#000}.statpl-history-notice-close{position:absolute;top:5px;right:8px;padding:0 5px;border:0;background:transparent;color:#44515e;font-size:22px;line-height:1.2;cursor:pointer}.statpl-history-report-link{display:inline-block;margin-top:3px;color:#0073aa;text-decoration:none}.statpl-history-report-link:hover{text-decoration:underline}
         .statpl-metrics-wrap .statpl-metrics-toolbar{display:flex;justify-content:space-between;align-items:center;gap:16px;flex-wrap:wrap;margin:18px 0 12px}.statpl-metrics-wrap .statpl-sort-form{display:flex;align-items:center;gap:8px}.statpl-metrics-wrap .statpl-metrics-search{display:flex;justify-content:flex-end;align-items:center;gap:8px;margin:0}.statpl-metrics-wrap .statpl-metrics-search input[type=search]{width:min(375px,100%)}.statpl-metrics-wrap .statpl-metrics-search input[type=submit],.statpl-metrics-wrap .button-primary{background:#3155F5!important;border-color:#3155F5!important;color:#fff!important}
         .statpl-metrics-wrap .widefat{border-color:#c9d7ff;border-collapse:separate;border-spacing:0}
@@ -366 +2360 @@
 
     public function admin_menu() {
+        // The detailed import report is intentionally not a permanent menu item.
+        // It is reachable only through the temporary notice link for partial or
+        // technical outcomes, and only during the 15-minute access window.
         add_menu_page('Statora Plus', 'Statora Plus', 'manage_woocommerce', 'statpl-product-metrics', [$this, 'render_page'], 'dashicons-chart-bar', 56);
+    }
+
+    /** Add the silent 20-second dismissal behavior; manual close cancels the timer. */
+    public function enqueue_historical_notice_script() {
+        // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- This is a read-only admin-screen routing check; it does not process form data or perform a state-changing action. Mutating admin actions use their own nonce verification.
+        if (!isset($_GET['page']) || !in_array(sanitize_key(wp_unslash($_GET['page'])), ['statpl-product-metrics','statpl-history-report'], true)) { return; }
+        echo '<script>(function(){var n=document.querySelector(".statpl-history-notice");if(!n)return;var t=window.setTimeout(function(){if(n.parentNode)n.parentNode.removeChild(n);},20000);var b=n.querySelector(".statpl-history-notice-close");if(b)b.addEventListener("click",function(){window.clearTimeout(t);if(n.parentNode)n.parentNode.removeChild(n);});})();</script>';
     }
     /** Bulk-load view counts for a product set to avoid two or more queries per product. */
@@ -376 +2380 @@
         return $this->today_start_datetime()->format('Y-m-d H:i:s');
     }
-    /** Return a displayable stock quantity without double-counting parent and variation stock. */
+    /**
+     * Return stock quantity and WooCommerce availability without double-counting
+     * parent-managed and variation-managed inventory.
+     */
     private function stock_summary_for_product($product) {
-        if (!$product) return ['managed' => false, 'quantity' => null];
+        if (!$product) {
+            return ['managed' => false, 'quantity' => null, 'in_stock' => false];
+        }
+
+        // WooCommerce's native availability API treats both instock and
+        // onbackorder as purchasable, and respects its stock-status filters.
+        $in_stock = (bool) $product->is_in_stock();
+
+        // When the parent manages stock, its quantity is authoritative.
+        // Do not add variation quantities to it.
         if ($product->managing_stock()) {
             $quantity = $product->get_stock_quantity();
-            return ['managed' => true, 'quantity' => is_numeric($quantity) ? (float) $quantity : 0.0];
-        }
+            return [
+                'managed' => true,
+                'quantity' => is_numeric($quantity) ? (float) $quantity : 0.0,
+                'in_stock' => $in_stock,
+            ];
+        }
+
+        // Otherwise, sum only variations that explicitly manage their own stock.
         if ($product->is_type('variable')) {
             $managed_any = false;
@@ -388 +2410 @@
             foreach ($product->get_children() as $variation_id) {
                 $variation = wc_get_product($variation_id);
-                if (!$variation || !$variation->managing_stock()) continue;
+                if (!$variation || !$variation->managing_stock()) {
+                    continue;
+                }
                 $managed_any = true;
                 $quantity = $variation->get_stock_quantity();
-                if (is_numeric($quantity)) $total += (float) $quantity;
-            }
-            if ($managed_any) return ['managed' => true, 'quantity' => $total];
-        }
-        return ['managed' => false, 'quantity' => null];
+                if (is_numeric($quantity)) {
+                    $total += (float) $quantity;
+                }
+            }
+            if ($managed_any) {
+                return ['managed' => true, 'quantity' => $total, 'in_stock' => $in_stock];
+            }
+        }
+
+        return ['managed' => false, 'quantity' => null, 'in_stock' => $in_stock];
     }
 
@@ -411 +2440 @@
         $placeholders = implode(',', array_fill(0, count($ids), '%d'));
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all query values are prepared.
-        $totals = $wpdb->get_results(
-            $wpdb->prepare(
+        $totals = statpl_db_get_results(
+            statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, WordPress.DB.PreparedSQLPlaceholders.UnfinishedPrepare, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated; the IN placeholders are generated from the count of integer IDs, and every ID is passed to prepare() as a value.
                 "SELECT product_id, total_views FROM {$this->views_table} WHERE product_id IN ($placeholders)",
@@ -428 +2457 @@
         $since = $this->today_start_mysql();
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; all query values are prepared.
-        $recent = $wpdb->get_results(
-            $wpdb->prepare(
+        $recent = statpl_db_get_results(
+            statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated; the date and every product ID are passed to prepare() as values. The IN placeholders are generated from the count of integer IDs.
                 "SELECT product_id, COUNT(*) AS views_today FROM {$this->events_table} WHERE viewed_at >= %s AND product_id IN ($placeholders) GROUP BY product_id",
@@ -471 +2500 @@
         // Replace a snapshot atomically so readers never see a half-written order.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Transaction control is required for an atomic snapshot replacement and cannot be cached.
-        if ($wpdb->query('START TRANSACTION') === false) return false;
+        if (statpl_db_query('START TRANSACTION') === false) return false;
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- This write replaces the stored order snapshot inside a transaction; it must execute immediately and must not be cached.
-        $deleted = $wpdb->delete($this->order_items_table, ['order_id' => $order_id], ['%d']);
+        $deleted = statpl_db_delete($this->order_items_table, ['order_id' => $order_id], ['%d']);
         if ($deleted === false) {
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Transaction rollback is required after a failed write; caching is not applicable.
-            $wpdb->query('ROLLBACK');
+            statpl_db_query('ROLLBACK');
             return false;
         }
@@ -539 +2568 @@
         foreach ($by_product as $pid => $row) {
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- These rows are the authoritative refreshed order snapshot; writes must execute immediately and must not be cached.
-            $inserted = $wpdb->insert($this->order_items_table, [
+            $inserted = statpl_db_insert($this->order_items_table, [
                 'order_id'=>(int)$order_id, 'product_id'=>(int)$pid, 'order_status'=>$order->get_status(),
                 'created_at'=>$created_at, 'paid_at'=>$paid_at, 'completed_at'=>$completed_at,
@@ -547 +2576 @@
             if ($inserted === false) {
                 // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Transaction rollback is required after a failed write; caching is not applicable.
-                $wpdb->query('ROLLBACK');
+                statpl_db_query('ROLLBACK');
                 return false;
             }
         }
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Transaction commit is required to persist the completed snapshot atomically.
-        if ($wpdb->query('COMMIT') === false) {
-            $wpdb->query('ROLLBACK');
+        if (statpl_db_query('COMMIT') === false) {
+            statpl_db_query('ROLLBACK');
             return false;
         }
@@ -574 +2603 @@
         global $wpdb;
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Deleting a removed order snapshot is a required write; caching is not applicable.
-        $wpdb->delete($this->order_items_table, ['order_id'=>absint($order_id)], ['%d']);
+        statpl_db_delete($this->order_items_table, ['order_id'=>absint($order_id)], ['%d']);
         delete_transient('statpl_order_stats_v1');
         delete_transient('statpl_global_summary_v2');
     }
+    /**
+     * Discover source-specific adapters registered by compatible analytics plugins.
+     * This registry is intentionally explicit: Statora Plus does not guess the
+     * meaning of arbitrary third-party database tables.
+     */
+    public function discover_historical_view_adapters() {
+        global $wpdb;
+
+        // Discovery mutates the persisted source/origin inventory and schedules
+        // snapshot/import work. Serialize it across concurrent WordPress requests
+        // so two provider scans cannot race while reconciling the same origins.
+        // Acquire the lock before clearing the request-local registry: a request
+        // that cannot enter discovery must not discard a still-valid registry.
+        $lock_name = 'statpl_generic_adapter_discovery';
+        $discovery_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($discovery_lock['acquired'])) {
+            $status = isset($discovery_lock['status']) ? $discovery_lock['status'] : 'lock_unavailable';
+            if ($status !== 'lock_busy_or_unavailable') {
+                $this->log_generic_historical_scheduler_error(
+                    'adapter_discovery_lock',
+                    isset($discovery_lock['error']) ? $discovery_lock['error'] : $status
+                );
+            }
+            return ['status' => $status === 'lock_busy_or_unavailable' ? 'busy' : 'lock_unavailable', 'registered' => 0, 'rejected' => 0];
+        }
+
+        try {
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'lock_session_lost', 'registered' => 0, 'rejected' => 0];
+            }
+            return $this->discover_historical_view_adapters_locked($discovery_lock);
+        } finally {
+            // Never attempt to release a connection-scoped lock through a replacement session.
+            $this->release_generic_advisory_lock($discovery_lock, 'adapter_discovery');
+        }
+    }
+
+    /** Perform provider discovery while holding the global discovery lock. */
+    private function discover_historical_view_adapters_locked($discovery_lock) {
+        // Invalidate request-local adapter objects before asking providers to
+        // rebuild the registry. If a provider throws, retaining objects from an
+        // earlier discovery pass could execute an adapter whose plugin is no
+        // longer available or whose registration is now failing. Persisted
+        // adapter identity/snapshot/checkpoint remain untouched in the database.
+        $this->historical_view_adapters = [];
+
+        // A third-party provider callback can throw while the registry filter is
+        // being assembled. Contain that failure here so it cannot interrupt
+        // Statora Plus initialization or the independent live-view tracker.
+        try {
+            $provided = apply_filters('statpl_historical_view_adapters', []);
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: historical adapter registry filter failed: ' . $exception->getMessage());
+            }
+            return ['status' => 'provider_error', 'registered' => 0, 'rejected' => 1];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+            return ['status' => 'lock_session_lost', 'registered' => 0, 'rejected' => 0];
+        }
+        if (!is_array($provided)) {
+            return ['status' => 'invalid_registry', 'registered' => 0, 'rejected' => 0];
+        }
+
+        // A successful discovery pass is authoritative; the registry was
+        // cleared before invoking third-party provider callbacks above.
+
+        $registered = 0;
+        $rejected = 0;
+        $seen_adapter_keys = [];
+        // A source_key is a persistent namespace, so two different adapter
+        // identities must not claim it during the same discovery pass—even if
+        // the first adapter currently reports no origins and therefore has no
+        // origin row from which the database conflict check could detect it.
+        $seen_source_keys = [];
+
+        foreach ($provided as $adapter) {
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+            }
+            if (!is_object($adapter) || !$this->is_valid_historical_view_adapter($adapter)) {
+                $rejected++;
+                continue;
+            }
+
+            try {
+                $adapter_key = sanitize_key((string) $adapter->get_adapter_key());
+                $source_key = sanitize_key((string) $adapter->get_source_key());
+                $display_name = sanitize_text_field((string) $adapter->get_display_name());
+                $adapter_version = sanitize_text_field((string) $adapter->get_adapter_version());
+
+                // Adapter metadata methods are third-party callbacks. They may
+                // perform database work or trigger a reconnect; never continue
+                // discovery writes under an assumed connection after invoking them.
+                if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                }
+
+                if (
+                    $adapter_key === ''
+                    || $source_key === ''
+                    || $display_name === ''
+                    || $adapter_version === ''
+                    || strlen($adapter_key) > 100
+                    || strlen($source_key) > 100
+                    || strlen($display_name) > 191
+                    || strlen($adapter_version) > 32
+                    || isset($seen_adapter_keys[$adapter_key])
+                ) {
+                    $rejected++;
+                    continue;
+                }
+
+                // SlimStat already has a mature, separately tested import pipeline.
+                // It must not be registered a second time through this generic path.
+                if ($source_key === 'slimstat' || $adapter_key === 'slimstat') {
+                    continue;
+                }
+
+                if (isset($seen_source_keys[$source_key]) && $seen_source_keys[$source_key] !== $adapter_key) {
+                    $rejected++;
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('Statora Plus: rejected adapter "' . $adapter_key . '" because source_key "' . $source_key . '" was already claimed by another adapter in this discovery pass.');
+                    }
+                    continue;
+                }
+                $seen_source_keys[$source_key] = $adapter_key;
+
+                // A source_key is the persistent namespace for all of its origins.
+                // Do not allow a different adapter identity to append a second set
+                // of origins to an existing source, even when the origin_key values
+                // do not overlap. The discovery advisory lock makes this check and
+                // the subsequent registration one serialized discovery operation.
+                global $wpdb;
+                $conflicting_adapter_key = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT origins.adapter_key
+                     FROM {$this->view_source_origins_table} AS origins
+                     INNER JOIN {$this->view_sources_table} AS sources
+                       ON sources.id = origins.source_id
+                     WHERE sources.source_key = %s
+                       AND (sources.adapter_key <> %s OR origins.adapter_key <> %s)
+                     LIMIT 1",
+                    $source_key,
+                    $adapter_key,
+                    $adapter_key
+                ));
+                if (!empty($wpdb->last_error)) {
+                    $rejected++;
+                    $this->log_generic_historical_scheduler_error(
+                        'adapter_identity_lookup',
+                        $wpdb->last_error
+                    );
+                    continue;
+                }
+                if ($conflicting_adapter_key !== null && $conflicting_adapter_key !== '') {
+                    $rejected++;
+                    if (defined('WP_DEBUG') && WP_DEBUG) {
+                        $this->debug_log('Statora Plus: rejected adapter "' . $adapter_key . '" because source_key "' . $source_key . '" is already bound to another adapter identity.');
+                    }
+                    continue;
+                }
+
+                $origins = $adapter->discover_origins();
+                if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                }
+                if (!is_array($origins)) {
+                    $rejected++;
+                    continue;
+                }
+
+                $valid_origins = [];
+                $seen_origin_keys = [];
+                $origin_declaration_invalid = false;
+                foreach ($origins as $origin) {
+                    if (!is_array($origin)) {
+                        $rejected++;
+                        $origin_declaration_invalid = true;
+                        continue;
+                    }
+
+                    $origin_key = isset($origin['origin_key'])
+                        ? sanitize_key((string) $origin['origin_key'])
+                        : '';
+                    $capabilities = isset($origin['capabilities']) && is_array($origin['capabilities'])
+                        ? $origin['capabilities']
+                        : [];
+                    $detection_status = isset($origin['detection_status'])
+                        ? (string) $origin['detection_status']
+                        : 'unknown';
+
+                    // Only explicit product-view capability qualifies as a source.
+                    if (
+                        $origin_key === ''
+                        || strlen($origin_key) > 100
+                        || isset($seen_origin_keys[$origin_key])
+                        || empty($capabilities['product_views'])
+                        || !in_array($detection_status, ['unknown', 'available', 'missing_table', 'incompatible_schema', 'database_error'], true)
+                    ) {
+                        $rejected++;
+                        $origin_declaration_invalid = true;
+                        continue;
+                    }
+
+                    // Sanitization can collapse distinct provider values to the
+                    // same key. Register each origin only once per discovery pass
+                    // so duplicate declarations cannot overwrite capabilities or
+                    // schedule duplicate snapshot/import initialization work.
+                    $seen_origin_keys[$origin_key] = true;
+                    $valid_origins[] = [
+                        'origin_key' => $origin_key,
+                        'capabilities' => $capabilities,
+                        'detection_status' => $detection_status,
+                    ];
+                }
+
+                if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                }
+                $source_result = $this->register_view_source(
+                    $source_key,
+                    $display_name,
+                    $adapter_version,
+                    'event',
+                    'detected',
+                    $adapter_key
+                );
+
+                if (empty($source_result['source_id'])) {
+                    $rejected++;
+                    continue;
+                }
+
+                // A successful discovery response is authoritative for the
+                // adapter's current origin inventory. If the provider returns a
+                // temporarily incomplete (or empty) list, preserve omitted
+                // origins and their cursors but take them out of active work.
+                // Do not infer omissions from a malformed/partially rejected
+                // declaration list, because that is not a trustworthy inventory.
+                $seen_adapter_keys[$adapter_key] = true;
+                if (!$origin_declaration_invalid) {
+                    $missing_origins = $this->mark_missing_generic_historical_origins_unavailable(
+                        $source_result['source_id'],
+                        $adapter_key,
+                        array_column($valid_origins, 'origin_key'),
+                        $discovery_lock
+                    );
+                    if (empty($missing_origins['status']) || $missing_origins['status'] !== 'updated') {
+                        // Do not register or schedule this adapter's newly reported
+                        // origins against a partially reconciled inventory. Keep the
+                        // previous persisted inventory intact and retry on the next
+                        // discovery pass after the database is healthy.
+                        $rejected++;
+                        $this->log_generic_historical_scheduler_error(
+                            'origin_inventory_reconciliation',
+                            isset($missing_origins['error']) ? $missing_origins['error'] : 'Origin inventory reconciliation did not commit.'
+                        );
+                        continue;
+                    }
+                }
+
+                if (!$valid_origins) {
+                    if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                    }
+                    $this->refresh_generic_historical_source_status($source_result['source_id']);
+                    continue;
+                }
+
+                $registered_origins = [];
+                $origin_registration_failures = 0;
+                $adapter_mismatch_detected = false;
+                foreach ($valid_origins as $origin) {
+                    if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                    }
+                    // Isolate each origin completely. A provider/database exception
+                    // while registering one origin must not prevent sibling origins
+                    // from being registered and scheduled in this discovery pass.
+                    try {
+                        $origin_result = $this->register_view_source_origin(
+                            $source_result['source_id'],
+                            $origin['origin_key'],
+                            $adapter_key,
+                            $origin['capabilities'],
+                            $origin['detection_status']
+                        );
+                    } catch (Throwable $exception) {
+                        $origin_result = [
+                            'status' => 'origin_exception',
+                            'error' => $exception->getMessage(),
+                        ];
+                        if (defined('WP_DEBUG') && WP_DEBUG) {
+                            $this->debug_log('Statora Plus: origin registration failed for "' . $origin['origin_key'] . '": ' . $exception->getMessage());
+                        }
+                    }
+
+                    if (!empty($origin_result['status']) && $origin_result['status'] === 'registered') {
+                        $registered_origins[] = $origin;
+                    } elseif (!empty($origin_result['status']) && $origin_result['status'] === 'adapter_mismatch') {
+                        $adapter_mismatch_detected = true;
+                        $origin_registration_failures++;
+                    } else {
+                        $origin_registration_failures++;
+                    }
+                }
+                if ($adapter_mismatch_detected) {
+                    // Preserve the established identity and cursor of the mismatched
+                    // origin, but do not let that isolated conflict block sibling
+                    // origins that were registered successfully with this adapter.
+                    $this->refresh_generic_historical_source_status($source_result['source_id']);
+                }
+
+                if ($registered_origins) {
+                    $this->historical_view_adapters[$adapter_key] = $adapter;
+                    $snapshot_result = $this->initialize_generic_historical_view_snapshots(
+                        $source_result['source_id'],
+                        $adapter_key,
+                        $registered_origins,
+                        $discovery_lock
+                    );
+                    if (($snapshot_result['status'] ?? '') === 'lock_session_lost'
+                        || !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                    }
+                    $this->refresh_generic_historical_source_status($source_result['source_id']);
+                    $registered++;
+                    if (!empty($snapshot_result['failed']) || $origin_registration_failures > 0) {
+                        $rejected++;
+                    }
+                    foreach ($registered_origins as $origin) {
+                        if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                            return ['status' => 'lock_session_lost', 'registered' => $registered, 'rejected' => $rejected];
+                        }
+                        if ($origin['detection_status'] === 'available') {
+                            $this->schedule_generic_historical_view_import_batch(15, $source_result['source_id'], $origin['origin_key']);
+                        }
+                    }
+                } else {
+                    $rejected++;
+                }
+            } catch (Throwable $exception) {
+                $rejected++;
+                if (defined('WP_DEBUG') && WP_DEBUG) {
+                    $this->debug_log('Statora Plus: historical adapter discovery failed: ' . $exception->getMessage());
+                }
+            }
+        }
+
+        return [
+            'status' => 'completed',
+            'registered' => $registered,
+            'rejected' => $rejected,
+        ];
+    }
+
+    /** Persist snapshot and its initial checkpoint together, exactly once per origin. */
+    private function save_generic_historical_snapshot_if_empty($source_id, $origin_key, $snapshot, $checkpoint) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = is_string($origin_key) ? trim($origin_key) : '';
+        if (!$source_id || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+            || !is_array($snapshot) || empty($snapshot) || !is_array($checkpoint)) {
+            return ['status' => 'invalid_input'];
+        }
+
+        $snapshot_json = wp_json_encode($snapshot);
+        $checkpoint_json = wp_json_encode($checkpoint);
+        if (!is_string($snapshot_json) || !is_string($checkpoint_json)) {
+            return ['status' => 'encoding_error'];
+        }
+
+        $result = statpl_db_query(statpl_db_prepare(
+            "UPDATE {$this->view_source_origins_table}
+             SET snapshot_data = %s, checkpoint_data = %s, status = %s,
+                 started_at = %s, last_error = NULL, updated_at = %s
+             WHERE source_id = %d AND origin_key = %s
+               AND snapshot_data IS NULL AND checkpoint_data IS NULL",
+            $snapshot_json,
+            $checkpoint_json,
+            'snapshot_ready',
+            current_time('mysql'),
+            current_time('mysql'),
+            $source_id,
+            $origin_key
+        ));
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return ['status' => 'database_error', 'error' => $wpdb->last_error];
+        }
+        if ($result === 1) {
+            return ['status' => 'updated', 'source_id' => $source_id, 'origin_key' => $origin_key];
+        }
+
+        $existing = $this->get_view_source_origin_state($source_id, $origin_key);
+        if ($existing['status'] !== 'found') {
+            return $existing;
+        }
+        if (is_array($existing['snapshot']) && !empty($existing['snapshot'])
+            && is_array($existing['checkpoint'])) {
+            return [
+                'status' => 'already_initialized',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'snapshot' => $existing['snapshot'],
+                'checkpoint' => $existing['checkpoint'],
+            ];
+        }
+        return ['status' => 'initialization_conflict', 'source_id' => $source_id, 'origin_key' => $origin_key];
+    }
+
+    /**
+     * Capture an immutable upper-bound snapshot for every detected generic origin.
+     * Existing snapshots are never overwritten, so retries/re-discovery cannot move
+     * the historical import boundary forward and accidentally include live traffic.
+     */
+    private function initialize_generic_historical_view_snapshots($source_id, $adapter_key, $origins, $discovery_lock = null) {
+        $adapter = $this->get_historical_view_adapter($adapter_key);
+        if (!$adapter) {
+            return ['status' => 'adapter_unavailable', 'failed' => 1];
+        }
+
+        $initialized = 0;
+        $skipped = 0;
+        $failed = 0;
+
+        foreach ($origins as $origin) {
+            if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return [
+                    'status' => 'lock_session_lost',
+                    'initialized' => $initialized,
+                    'skipped' => $skipped,
+                    'failed' => $failed,
+                ];
+            }
+            if (!is_array($origin) || empty($origin['origin_key'])) {
+                $failed++;
+                continue;
+            }
+            if (($origin['detection_status'] ?? '') !== 'available') {
+                $skipped++;
+                continue;
+            }
+
+            $state = $this->get_view_source_origin_state($source_id, $origin['origin_key']);
+            if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return [
+                    'status' => 'lock_session_lost',
+                    'initialized' => $initialized,
+                    'skipped' => $skipped,
+                    'failed' => $failed,
+                ];
+            }
+            if (empty($state['status']) || $state['status'] !== 'found') {
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Could not read the stored origin state while initializing its historical snapshot.',
+                    null,
+                    8,
+                    $discovery_lock);
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                }
+                continue;
+            }
+            if (is_array($state['snapshot']) && !empty($state['snapshot'])) {
+                // A persisted snapshot is already valid; clear any stale
+                // initialization failure only while this discovery worker still
+                // owns the lock that serializes snapshot-ledger changes.
+                if (!$this->clear_generic_historical_view_failure($source_id, $origin['origin_key'], 'snapshot_initialization', $discovery_lock)) {
+                    $failed++;
+                    $this->schedule_generic_historical_snapshot_retry(60, $source_id, $origin['origin_key']);
+                    continue;
+                }
+                $skipped++;
+                continue;
+            }
+
+            try {
+                $snapshot = $adapter->get_origin_snapshot($origin['origin_key']);
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                if (!is_array($snapshot) || empty($snapshot)) {
+                    $failed++;
+                    if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return [
+                            'status' => 'lock_session_lost',
+                            'initialized' => $initialized,
+                            'skipped' => $skipped,
+                            'failed' => $failed,
+                        ];
+                    }
+                    $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Adapter returned an empty or invalid historical snapshot.',
+                    null,
+                    8,
+                    $discovery_lock);
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                    }
+                    continue;
+                }
+
+                // Adapter snapshots must declare their own stable boundary. The core
+                // records the capture time but does not guess source-specific cursors.
+                if (!isset($snapshot['captured_at'])) {
+                    $snapshot['captured_at'] = current_time('mysql');
+                }
+                if (!isset($snapshot['boundary']) || !is_array($snapshot['boundary']) || empty($snapshot['boundary'])) {
+                    $failed++;
+                    if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return [
+                            'status' => 'lock_session_lost',
+                            'initialized' => $initialized,
+                            'skipped' => $skipped,
+                            'failed' => $failed,
+                        ];
+                    }
+                    $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Adapter snapshot did not provide the required immutable boundary descriptor.',
+                    null,
+                    8,
+                    $discovery_lock);
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                    }
+                    continue;
+                }
+
+                $initial_checkpoint = array_key_exists('initial_checkpoint', $snapshot)
+                    ? $snapshot['initial_checkpoint']
+                    : null;
+                // A null initial cursor is valid (many sources begin at the start
+                // of their history). Non-null cursors must be JSON-safe scalar/array
+                // values within the same storage limit used for subsequent cursors.
+                if ($initial_checkpoint !== null && !$this->is_valid_generic_historical_cursor($initial_checkpoint)) {
+                    $failed++;
+                    if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return [
+                            'status' => 'lock_session_lost',
+                            'initialized' => $initialized,
+                            'skipped' => $skipped,
+                            'failed' => $failed,
+                        ];
+                    }
+                    $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Adapter snapshot contained an invalid initial checkpoint. Expected null or a JSON-safe scalar/array cursor no larger than 60 KB.',
+                    null,
+                    8,
+                    $discovery_lock);
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                    }
+                    continue;
+                }
+
+                $checkpoint = [
+                    'cursor' => $initial_checkpoint,
+                    'processed' => 0,
+                    'snapshot_captured_at' => $snapshot['captured_at'],
+                ];
+                unset($snapshot['initial_checkpoint']);
+
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                $saved = $this->save_generic_historical_snapshot_if_empty(
+                    $source_id,
+                    $origin['origin_key'],
+                    $snapshot,
+                    $checkpoint
+                );
+                if (empty($saved['status']) || !in_array($saved['status'], ['updated', 'already_initialized'], true)) {
+                    $failed++;
+                    if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                        return [
+                            'status' => 'lock_session_lost',
+                            'initialized' => $initialized,
+                            'skipped' => $skipped,
+                            'failed' => $failed,
+                        ];
+                    }
+                    $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    'Could not persist the immutable snapshot and initial checkpoint: ' . (isset($saved['status']) ? $saved['status'] : 'unknown error'),
+                    null,
+                    8,
+                    $discovery_lock);
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                    }
+                    continue;
+                }
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                $failure_cleared = $this->clear_generic_historical_view_failure($source_id, $origin['origin_key'], 'snapshot_initialization', $discovery_lock);
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                if (!$failure_cleared) {
+                    $failed++;
+                    $this->schedule_generic_historical_snapshot_retry(60, $source_id, $origin['origin_key']);
+                    continue;
+                }
+                if ($saved['status'] === 'updated') {
+                    $initialized++;
+                } else {
+                    $skipped++;
+                }
+            } catch (Throwable $exception) {
+                if (is_array($discovery_lock) && !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return [
+                        'status' => 'lock_session_lost',
+                        'initialized' => $initialized,
+                        'skipped' => $skipped,
+                        'failed' => $failed,
+                    ];
+                }
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin['origin_key'],
+                    'snapshot_initialization',
+                    0,
+                    $exception->getMessage(),
+                    null,
+                    8,
+                    $discovery_lock);
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_snapshot_retry($failure['retry_delay'], $source_id, $origin['origin_key']);
+                }
+                if (defined('WP_DEBUG') && WP_DEBUG) {
+                    $this->debug_log('Statora Plus: historical origin snapshot failed: ' . $exception->getMessage());
+                }
+            }
+        }
+
+        return [
+            'status' => $failed ? 'partial' : 'completed',
+            'initialized' => $initialized,
+            'skipped' => $skipped,
+            'failed' => $failed,
+        ];
+    }
+
+    /**
+     * Preserve origins omitted by a successful adapter discovery pass without
+     * allowing stale origins to continue importing. Their immutable adapter
+     * identity, snapshot, checkpoint, events and failure ledger are untouched.
+     */
+    private function mark_missing_generic_historical_origins_unavailable($source_id, $adapter_key, $discovered_origin_keys, $discovery_lock = null) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $adapter_key = sanitize_key((string) $adapter_key);
+        if (!$source_id || $adapter_key === '' || !is_array($discovered_origin_keys)) {
+            return ['status' => 'invalid_input', 'updated' => 0];
+        }
+
+        $discovered = [];
+        foreach ($discovered_origin_keys as $origin_key) {
+            $origin_key = sanitize_key((string) $origin_key);
+            if ($origin_key !== '') {
+                $discovered[$origin_key] = true;
+            }
+        }
+
+        if (!is_array($discovery_lock) || !$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+            return ['status' => 'lock_session_lost', 'updated' => 0, 'error' => 'Discovery lock session is no longer current.'];
+        }
+
+        $transaction_started = false;
+        $transaction_committed = false;
+        try {
+            // Reconciliation is one logical inventory operation. Keep it atomic so
+            // a database error halfway through cannot leave only part of the omitted
+            // origins marked unavailable. A later discovery can safely retry it.
+            $begin_result = statpl_db_query('START TRANSACTION');
+            if ($begin_result === false || $wpdb->last_error !== '') {
+                return ['status' => 'database_error', 'updated' => 0, 'error' => $wpdb->last_error];
+            }
+            $transaction_started = true;
+
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'lock_session_lost', 'updated' => 0, 'error' => 'Discovery lock session changed before origin inventory read.'];
+            }
+            $existing = statpl_db_get_results(
+                statpl_db_prepare(
+                    "SELECT origin_key, status
+                     FROM {$this->view_source_origins_table}
+                     WHERE source_id = %d AND adapter_key = %s
+                     FOR UPDATE",
+                    $source_id,
+                    $adapter_key
+                ),
+                ARRAY_A
+            );
+            if (!empty($wpdb->last_error) || !is_array($existing)) {
+                return ['status' => 'database_error', 'updated' => 0, 'error' => $wpdb->last_error !== '' ? $wpdb->last_error : 'Origin inventory query returned an invalid result.'];
+            }
+
+            $updated = 0;
+            foreach ($existing as $row) {
+                if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                    return ['status' => 'lock_session_lost', 'updated' => 0, 'error' => 'Discovery lock session changed during origin inventory reconciliation.'];
+                }
+                $origin_key = isset($row['origin_key']) ? (string) $row['origin_key'] : '';
+                if ($origin_key === '' || isset($discovered[$origin_key])) {
+                    continue;
+                }
+
+                // Terminal lifecycle states are retained. Detection becomes unknown
+                // until the provider declares this origin again; active work becomes
+                // unavailable so stale adapter inventories cannot process it.
+                $updates = [
+                    'detection_status' => 'unknown',
+                    'updated_at' => current_time('mysql'),
+                ];
+                $formats = ['%s', '%s'];
+                if (in_array($row['status'] ?? '', ['pending', 'snapshot_ready', 'importing', 'retry_wait'], true)) {
+                    $updates['status'] = 'unavailable';
+                    $updates['last_error'] = 'This origin was not declared by the adapter during the latest successful discovery pass; its saved snapshot and checkpoint were preserved.';
+                    $formats = ['%s', '%s', '%s', '%s'];
+                }
+
+                $result = statpl_db_update(
+                    $this->view_source_origins_table,
+                    $updates,
+                    ['source_id' => $source_id, 'origin_key' => $origin_key],
+                    $formats,
+                    ['%d', '%s']
+                );
+                if ($result === false || $wpdb->last_error !== '') {
+                    return ['status' => 'database_error', 'updated' => 0, 'error' => $wpdb->last_error !== '' ? $wpdb->last_error : 'Origin reconciliation update failed.'];
+                }
+                $updated++;
+            }
+
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'lock_session_lost', 'updated' => 0, 'error' => 'Discovery lock session changed before origin inventory commit.'];
+            }
+            $commit_result = statpl_db_query('COMMIT');
+            if ($commit_result === false || $wpdb->last_error !== '') {
+                return ['status' => 'database_error', 'updated' => 0, 'error' => $wpdb->last_error !== '' ? $wpdb->last_error : 'Origin reconciliation commit failed.'];
+            }
+            $transaction_committed = true;
+            if (!$this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                return ['status' => 'commit_outcome_unknown', 'updated' => 0, 'error' => 'Origin inventory commit completed but discovery lock session could not be confirmed.'];
+            }
+            return ['status' => 'updated', 'updated' => $updated];
+        } catch (Throwable $exception) {
+            return ['status' => 'database_error', 'updated' => 0, 'error' => $exception->getMessage()];
+        } finally {
+            // Includes thrown exceptions and ambiguous failures before COMMIT.
+            // A rollback after a successful commit is intentionally avoided.
+            if ($transaction_started && !$transaction_committed && $this->generic_advisory_lock_session_is_current($discovery_lock)) {
+                try {
+                    statpl_db_query('ROLLBACK');
+                } catch (Throwable $rollback_exception) {
+                    $this->log_generic_historical_scheduler_error('origin_inventory_rollback', $rollback_exception->getMessage());
+                }
+            }
+        }
+    }
+
+    /** Validate the minimum public adapter contract without trusting a provider. */
+    private function is_valid_historical_view_adapter($adapter) {
+        foreach ([
+            'get_adapter_key',
+            'get_source_key',
+            'get_display_name',
+            'get_adapter_version',
+            'discover_origins',
+            'get_origin_snapshot',
+            'get_product_view_batch',
+            'normalize_record',
+        ] as $method) {
+            if (!is_callable([$adapter, $method])) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Recompute the persisted status of one generic source from all its origins.
+     * This is intentionally called only by the generic pipeline; the independent
+     * SlimStat lifecycle and its status model are left untouched.
+     */
+    private function refresh_generic_historical_source_status($source_id) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        if (!$source_id) {
+            return ['status' => 'invalid_source'];
+        }
+
+        // Serialize aggregate status calculation and persistence per source.
+        // Use the shared lock contract so the owning connection is captured
+        // atomically and RELEASE_LOCK is never attempted on a replacement session.
+        $status_lock_name = 'statpl_status_' . substr(md5((string) $source_id), 0, 32);
+        $status_lock = $this->acquire_generic_advisory_lock($status_lock_name);
+        if (empty($status_lock['acquired'])) {
+            if (($status_lock['status'] ?? '') === 'lock_busy_or_unavailable' && empty($status_lock['error'])) {
+                return ['status' => 'status_lock_busy'];
+            }
+            return ['status' => 'database_error', 'error' => (string) ($status_lock['error'] ?? 'Unable to acquire source status lock.')];
+        }
+
+        try {
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        $origins = statpl_db_get_results(statpl_db_prepare(
+            "SELECT detection_status, status FROM {$this->view_source_origins_table} WHERE source_id = %d",
+            $source_id
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error)) {
+            return ['status' => 'database_error', 'error' => $wpdb->last_error];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        if (!is_array($origins) || !$origins) {
+            return ['status' => 'no_origins'];
+        }
+
+        $available_origins = array_values(array_filter($origins, function ($origin) {
+            // Detection describes what the provider reported on its last pass;
+            // lifecycle status additionally records whether this exact persisted
+            // adapter identity is currently safe to execute. A replacement
+            // adapter can be detected as available while its origin remains
+            // deliberately unavailable because it cannot inherit the old cursor.
+            return isset($origin['detection_status'], $origin['status'])
+                && $origin['detection_status'] === 'available'
+                && $origin['status'] !== 'unavailable';
+        }));
+        $available = count($available_origins);
+        $available_completed = count(array_filter($available_origins, function ($origin) {
+            return isset($origin['status']) && $origin['status'] === 'completed';
+        }));
+        // Only available origins participate in import lifecycle aggregation.
+        // An unavailable/detected sibling must never keep an otherwise finished
+        // source stuck in importing or retry_wait.
+        $available_statuses = array_column($available_origins, 'status');
+
+        // A source remains actively importing while ANY available origin is
+        // still progressing. A blocked sibling origin must not make the whole
+        // source appear terminal before the remaining origins finish.
+        if (in_array('importing', $available_statuses, true) || in_array('snapshot_ready', $available_statuses, true) || in_array('pending', $available_statuses, true)) {
+            $source_status = 'importing';
+        } elseif (in_array('retry_wait', $available_statuses, true)) {
+            $source_status = 'retry_wait';
+        } elseif (in_array('needs_attention', $available_statuses, true)) {
+            $source_status = 'needs_attention';
+        } elseif ($available === 0) {
+            $source_status = 'unavailable';
+        } elseif ($available_completed === $available) {
+            // A source with unavailable origins is only partial, never fully complete.
+            $source_status = ($available === count($origins)) ? 'completed' : 'partial';
+        } elseif (in_array('completed', $available_statuses, true)) {
+            $source_status = 'partial';
+        } else {
+            $source_status = 'detected';
+        }
+
+        // Status reconciliation is not a source-registration/content update.
+        // Keep updated_at reserved for genuine source changes; otherwise the
+        // recovery scanner would generate needless writes on every request.
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        // Bind source-status persistence to the same MySQL session that owns
+        // this status lock. A PHP-side check alone leaves a reconnect race between
+        // validation and UPDATE; the SQL predicate closes that window.
+        if (empty($status_lock['lock_name']) || !$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        $updated = statpl_db_query(statpl_db_prepare(
+            "UPDATE {$this->view_sources_table}
+             SET status = %s
+             WHERE id = %d AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+            $source_status,
+            $source_id,
+            (string) $status_lock['lock_name']
+        ));
+        if ($updated === false || $wpdb->last_error !== '') {
+            return ['status' => 'database_error', 'error' => $wpdb->last_error];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+
+        // Do not treat an accepted UPDATE as durable source-state convergence.
+        // The row may have been unchanged (0 affected rows), or an ambiguous
+        // acknowledgement may have occurred. Read the aggregate status back and
+        // require an exact match before reporting success to callers.
+        $persisted_status = statpl_db_get_var(statpl_db_prepare(
+            "SELECT status FROM {$this->view_sources_table} WHERE id = %d",
+            $source_id
+        ));
+        if ($wpdb->last_error !== '') {
+            return ['status' => 'database_error', 'error' => $wpdb->last_error];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($status_lock)) {
+            return ['status' => 'status_lock_lost'];
+        }
+        if ($persisted_status === null) {
+            // The source may have been removed after the bounded scan selected it.
+            // Treat that as a vanished work item, not as a database failure.
+            return ['status' => 'source_missing'];
+        }
+        if (!is_string($persisted_status) || $persisted_status !== $source_status) {
+            return [
+                'status' => 'state_unverified',
+                'expected_status' => $source_status,
+                'persisted_status' => is_string($persisted_status) ? $persisted_status : null,
+            ];
+        }
+
+        return ['status' => 'updated', 'source_status' => $source_status];
+        } finally {
+            // Release only if the original connection still owns this lock.
+            $this->release_generic_advisory_lock($status_lock, 'source_status_reconciliation');
+        }
+    }
+
+    /** Retry adapter discovery and snapshot initialization after a bounded delay. */
+    public function retry_generic_historical_view_snapshot($source_id = 0, $origin_key = '') {
+        $source_id = absint($source_id);
+        $origin_key = sanitize_key((string) $origin_key);
+        if (!$source_id || $origin_key === '') {
+            return ['status' => 'invalid_input'];
+        }
+
+        // Discovery re-resolves the provider in this request and retries only origins
+        // whose immutable snapshot has not yet been persisted. Existing snapshots are
+        // protected by save_generic_historical_snapshot_if_empty().
+        $result = $this->discover_historical_view_adapters();
+        $state = $this->get_view_source_origin_state($source_id, $origin_key);
+        if (!empty($state['status']) && $state['status'] === 'found'
+            && is_array($state['snapshot']) && !empty($state['snapshot'])) {
+            // The discovery worker owns the snapshot failure ledger lifecycle. This
+            // follow-up request has no discovery lock context, so it must not delete
+            // the ledger row outside that ownership boundary.
+            $this->schedule_generic_historical_view_import_batch(15, $source_id, $origin_key);
+            $this->refresh_generic_historical_source_status($source_id);
+            return ['status' => 'snapshot_ready', 'discovery' => $result];
+        }
+
+        $this->refresh_generic_historical_source_status($source_id);
+        return ['status' => 'snapshot_still_unavailable', 'discovery' => $result];
+    }
+
+    /** Schedule bounded retries for transient snapshot/provider initialization failures. */
+    private function schedule_generic_historical_snapshot_retry($delay, $source_id, $origin_key) {
+        $args = [absint($source_id), sanitize_key((string) $origin_key)];
+        $hook = 'statpl_generic_view_snapshot_retry';
+        $requested_timestamp = time() + max(1, (int) $delay);
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $existing_timestamp = false;
+            if (function_exists('as_next_scheduled_action')) {
+                try {
+                    $existing_timestamp = as_next_scheduled_action($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_lookup', $exception->getMessage());
+                }
+            }
+
+            // A newly discovered transient failure may have a shorter backoff than
+            // an older snapshot retry. Keep the earliest deadline, not merely any
+            // existing action, so stale long delays cannot postpone recovery.
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp && function_exists('as_unschedule_all_actions')) {
+                try {
+                    as_unschedule_all_actions($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_unschedule', $exception->getMessage());
+                    return true;
+                }
+            } elseif ($existing_timestamp) {
+                return true;
+            } elseif (function_exists('as_has_scheduled_action')) {
+                try {
+                    if (as_has_scheduled_action($hook, $args, 'statpl-plus')) {
+                        // Without a reliable timestamp/removal API, retain the
+                        // existing action rather than creating an uncontrolled duplicate.
+                        return true;
+                    }
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_presence_check', $exception->getMessage());
+                }
+            }
+
+            try {
+                $action_id = as_schedule_single_action($requested_timestamp, $hook, $args, 'statpl-plus');
+                if ($action_id) {
+                    return true;
+                }
+            } catch (Throwable $exception) {
+                $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            }
+            // Action Scheduler can be unavailable or fail transiently. Fall back to WP-Cron.
+        }
+
+        // WP-Cron follows the same earliest-deadline rule. If replacing a later
+        // event fails, retain it rather than creating a duplicate with uncertain order.
+        try {
+            $existing_timestamp = wp_next_scheduled($hook, $args);
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp) {
+                $unscheduled = wp_unschedule_event((int) $existing_timestamp, $hook, $args);
+                if (!$unscheduled || is_wp_error($unscheduled)) {
+                    $this->log_generic_historical_scheduler_error(
+                        $hook . '_unschedule',
+                        is_wp_error($unscheduled) ? $unscheduled->get_error_message() : 'Could not replace the later WP-Cron event.'
+                    );
+                    return true;
+                }
+            }
+            $scheduled = wp_schedule_single_event($requested_timestamp, $hook, $args);
+            if (!$scheduled || is_wp_error($scheduled)) {
+                $this->log_generic_historical_scheduler_error($hook, is_wp_error($scheduled) ? $scheduled->get_error_message() : 'WP-Cron rejected the event.');
+                return false;
+            }
+            return true;
+        } catch (Throwable $exception) {
+            $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            return false;
+        }
+    }
+
+    /** Requeue persisted generic-import work after a previous scheduler outage. */
+    private function recover_unscheduled_generic_historical_work() {
+        global $wpdb;
+
+        $origins = statpl_db_get_results(
+            "SELECT source_id, origin_key, snapshot_data, status, detection_status
+             FROM {$this->view_source_origins_table}
+             WHERE detection_status = 'available'
+               AND status IN ('pending', 'snapshot_ready', 'importing', 'retry_wait')
+             ORDER BY updated_at ASC
+             LIMIT 50",
+            ARRAY_A
+        );
+        if (!is_array($origins) || !empty($wpdb->last_error)) {
+            $this->log_generic_historical_scheduler_error('recovery_scan', !empty($wpdb->last_error) ? $wpdb->last_error : 'Unable to read pending origins.');
+            return 0;
+        }
+
+        $requeued = 0;
+        foreach ($origins as $origin) {
+            $source_id = absint($origin['source_id'] ?? 0);
+            $origin_key = sanitize_key((string) ($origin['origin_key'] ?? ''));
+            if (!$source_id || $origin_key === '') {
+                continue;
+            }
+
+            if (empty($origin['snapshot_data'])) {
+                $scheduled = $this->schedule_generic_historical_snapshot_retry(300, $source_id, $origin_key);
+            } else {
+                $scheduled = $this->schedule_generic_historical_view_import_batch(300, $source_id, $origin_key);
+            }
+            if ($scheduled) {
+                $requeued++;
+            }
+        }
+
+        // Retry rows are durable in the failure ledger. Recreate their worker
+        // trigger independently of the main import cursor.
+        $retry_origins = statpl_db_get_results(
+            "SELECT source_id, origin_key, MIN(next_retry_at) AS next_retry_at
+             FROM {$this->view_source_failures_table}
+             WHERE status = 'retry'
+               AND retry_checkpoint IS NOT NULL
+               AND retry_checkpoint <> ''
+             GROUP BY source_id, origin_key
+             ORDER BY MIN(next_retry_at) ASC
+             LIMIT 50",
+            ARRAY_A
+        );
+        if (is_array($retry_origins) && empty($wpdb->last_error)) {
+            foreach ($retry_origins as $retry_origin) {
+                $source_id = absint($retry_origin['source_id'] ?? 0);
+                $origin_key = sanitize_key((string) ($retry_origin['origin_key'] ?? ''));
+                if (!$source_id || $origin_key === '') {
+                    continue;
+                }
+                $next_timestamp = !empty($retry_origin['next_retry_at']) ? strtotime((string) $retry_origin['next_retry_at']) : false;
+                $delay = $next_timestamp !== false ? max(1, $next_timestamp - current_time('timestamp')) : 300;
+                if ($this->schedule_generic_historical_failure_retry(min(86400, $delay), $source_id, $origin_key)) {
+                    $requeued++;
+                }
+            }
+        } elseif (!empty($wpdb->last_error)) {
+            $this->log_generic_historical_scheduler_error('retry_recovery_scan', $wpdb->last_error);
+        }
+
+        // Serialize the cursor read, bounded page, and cursor write. Per-source
+        // locks protect each aggregate update; this scan-level lock additionally
+        // prevents concurrent requests from moving the persistent cursor backwards.
+        // Use the shared lock helper so acquisition, ownership checks and release
+        // follow the same connection-identity contract as the other workers.
+        $scan_lock_name = 'statpl_srcscan_' . substr(md5((string) $wpdb->prefix), 0, 32);
+        $scan_lock = $this->acquire_generic_advisory_lock($scan_lock_name);
+        if (empty($scan_lock['acquired'])) {
+            $scan_status = sanitize_key((string) ($scan_lock['status'] ?? 'lock_unavailable'));
+            if ($scan_status !== 'lock_busy_or_unavailable') {
+                $this->log_generic_historical_scheduler_error(
+                    'source_status_scan_lock',
+                    (string) ($scan_lock['error'] ?? $scan_status)
+                );
+            }
+        } else {
+            try {
+                if (!$this->generic_advisory_lock_session_is_current($scan_lock)) {
+                    $this->log_generic_historical_scheduler_error(
+                        'source_status_scan_lock',
+                        'The MySQL connection changed immediately after acquiring the source-status scan lock; this scan was skipped.'
+                    );
+                } else {
+                    // Source-status reconciliation is durable work even when every
+                    // origin is already completed. A persistent keyset cursor ensures
+                    // that a busy or failing source cannot pin the first page and
+                    // starve later sources when more than 50 sources exist.
+                    $cursor_option = 'statpl_generic_status_recovery_cursor';
+                    // The cursor is written directly with SQL while proving lock
+                    // ownership. Read it directly too: get_option() may return a
+                    // stale object-cache value because direct SQL bypasses the
+                    // WordPress options cache.
+                    $cursor_value = statpl_db_get_var(statpl_db_prepare(
+                        "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                        $cursor_option
+                    ));
+                    if ($wpdb->last_error !== '') {
+                        $this->log_generic_historical_scheduler_error('source_status_recovery_cursor', $wpdb->last_error);
+                        $cursor_value = '0';
+                    }
+                    $source_cursor = absint($cursor_value);
+                    $sources = statpl_db_get_results(statpl_db_prepare(
+                        "SELECT sources.id FROM {$this->view_sources_table} AS sources
+                         WHERE sources.id > %d
+                           AND EXISTS (
+                               SELECT 1 FROM {$this->view_source_origins_table} AS origins
+                               WHERE origins.source_id = sources.id
+                           )
+                         ORDER BY sources.id ASC
+                         LIMIT 50",
+                        $source_cursor
+                    ), ARRAY_A);
+
+                    if (!is_array($sources) || !empty($wpdb->last_error)) {
+                        $this->log_generic_historical_scheduler_error(
+                            'source_status_recovery_scan',
+                            !empty($wpdb->last_error) ? $wpdb->last_error : 'Unable to read generic sources for status reconciliation.'
+                        );
+                    } elseif ($this->generic_advisory_lock_session_is_current($scan_lock)) {
+                        // Wrap to the beginning only after reaching the end of the source set.
+                        $wrapped_to_start = false;
+                        if (!$sources && $source_cursor > 0) {
+                            $source_cursor = 0;
+                            $wrapped_to_start = true;
+                            $sources = statpl_db_get_results(
+                                "SELECT sources.id FROM {$this->view_sources_table} AS sources
+                                 WHERE EXISTS (
+                                     SELECT 1 FROM {$this->view_source_origins_table} AS origins
+                                     WHERE origins.source_id = sources.id
+                                 )
+                                 ORDER BY sources.id ASC
+                                 LIMIT 50",
+                                ARRAY_A
+                            );
+                            if (!is_array($sources) || !empty($wpdb->last_error)) {
+                                $this->log_generic_historical_scheduler_error(
+                                    'source_status_recovery_scan',
+                                    !empty($wpdb->last_error) ? $wpdb->last_error : 'Unable to restart generic source status scan.'
+                                );
+                                $sources = false;
+                            }
+                        }
+
+                        if (is_array($sources) && $sources) {
+                            $last_scanned_source_id = $source_cursor;
+                            $scan_page_completed = true;
+                            foreach ($sources as $source) {
+                                // If wpdb transparently reconnects, the connection-scoped
+                                // scan lock is gone. Stop and leave the cursor unchanged;
+                                // already attempted rows are safe to revisit.
+                                if (!$this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                    $scan_page_completed = false;
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_scan_lock',
+                                        'The MySQL connection changed during source reconciliation; the cursor was not advanced.'
+                                    );
+                                    break;
+                                }
+
+                                $source_id = absint($source['id'] ?? 0);
+                                if (!$source_id) {
+                                    continue;
+                                }
+                                $last_scanned_source_id = max($last_scanned_source_id, $source_id);
+                                try {
+                                    $reconciliation = $this->refresh_generic_historical_source_status($source_id);
+                                    if (!in_array($reconciliation['status'] ?? '', ['updated', 'status_lock_busy', 'source_missing'], true)) {
+                                        $this->log_generic_historical_scheduler_error(
+                                            'source_status_recovery',
+                                            'Source ' . $source_id . ' status reconciliation did not verify: ' . sanitize_key((string) ($reconciliation['status'] ?? 'unknown'))
+                                        );
+                                    }
+                                } catch (Throwable $exception) {
+                                    // One corrupt or temporarily failing source must not prevent
+                                    // the cursor from reaching the remaining sources.
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_recovery',
+                                        'Source ' . $source_id . ' reconciliation threw: ' . $exception->getMessage()
+                                    );
+                                }
+                            }
+
+                            // Advance only after the complete bounded page was attempted
+                            // and the original scan-lock session is still alive. A source
+                            // failure or lock contention is attempted work, not a reason
+                            // to starve later IDs; a lost scan session is different.
+                            if ($scan_page_completed && $this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                // Persist the cursor only in a SQL statement that proves
+                                // this exact connection still owns the scan lock. A PHP-
+                                // level check followed by update_option() is insufficient:
+                                // wpdb may reconnect between those calls and a stale scan
+                                // could overwrite the cursor of a newer lock owner.
+                                $cursor_persisted = statpl_db_query(statpl_db_prepare(
+                                    "INSERT INTO {$wpdb->options} (option_name, option_value, autoload)
+                                     SELECT %s, %s, 'no'
+                                     WHERE IS_USED_LOCK(%s) = CONNECTION_ID()
+                                     ON DUPLICATE KEY UPDATE option_value = IF(
+                                         IS_USED_LOCK(%s) = CONNECTION_ID(),
+                                         VALUES(option_value),
+                                         option_value
+                                     )",
+                                    $cursor_option,
+                                    (string) $last_scanned_source_id,
+                                    $scan_lock_name,
+                                    $scan_lock_name
+                                ));
+                                if (!in_array($cursor_persisted, [0, 1, 2], true)) {
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_recovery_cursor',
+                                        !empty($wpdb->last_error) ? $wpdb->last_error : 'Could not persist the source-status recovery cursor while owning the scan lock.'
+                                    );
+                                }
+                                if (!$this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_recovery_cursor',
+                                        'The MySQL connection changed while persisting the cursor; the next scan will safely re-evaluate the cursor.'
+                                    );
+                                } else {
+                                    $persisted_cursor_value = statpl_db_get_var(statpl_db_prepare(
+                                        "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                                        $cursor_option
+                                    ));
+                                    $persisted_cursor = absint($persisted_cursor_value);
+                                    if (!empty($wpdb->last_error) || $persisted_cursor !== $last_scanned_source_id) {
+                                        $this->log_generic_historical_scheduler_error('source_status_recovery_cursor', 'Could not verify the source-status recovery cursor.');
+                                    }
+                                }
+                            }
+                        } elseif (is_array($sources) && !$sources && $wrapped_to_start) {
+                            if ($this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                // Reset only while the current session still owns the
+                                // scan lock; the predicate is checked atomically by SQL.
+                                $reset_result = statpl_db_query(statpl_db_prepare(
+                                    "INSERT INTO {$wpdb->options} (option_name, option_value, autoload)
+                                     SELECT %s, '0', 'no'
+                                     WHERE IS_USED_LOCK(%s) = CONNECTION_ID()
+                                     ON DUPLICATE KEY UPDATE option_value = IF(
+                                         IS_USED_LOCK(%s) = CONNECTION_ID(), '0', option_value
+                                     )",
+                                    $cursor_option,
+                                    $scan_lock_name,
+                                    $scan_lock_name
+                                ));
+                                if ($reset_result === false || !empty($wpdb->last_error)) {
+                                    $this->log_generic_historical_scheduler_error(
+                                        'source_status_recovery_cursor',
+                                        !empty($wpdb->last_error) ? $wpdb->last_error : 'Could not reset the source-status recovery cursor.'
+                                    );
+                                } elseif ($this->generic_advisory_lock_session_is_current($scan_lock)) {
+                                    $reset_cursor = statpl_db_get_var(statpl_db_prepare(
+                                        "SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1",
+                                        $cursor_option
+                                    ));
+                                    if (!empty($wpdb->last_error) || absint($reset_cursor) !== 0) {
+                                        $this->log_generic_historical_scheduler_error(
+                                            'source_status_recovery_cursor',
+                                            'Could not verify the reset source-status recovery cursor.'
+                                        );
+                                    }
+                                }
+                            }
+                        }
+                    } else {
+                        $this->log_generic_historical_scheduler_error(
+                            'source_status_scan_lock',
+                            'The MySQL connection changed while reading the source-status page; this page was discarded.'
+                        );
+                    }
+                }
+            } catch (Throwable $exception) {
+                $this->log_generic_historical_scheduler_error('source_status_recovery_scan', $exception->getMessage());
+            } finally {
+                $this->release_generic_advisory_lock($scan_lock, 'source_status_recovery_scan');
+            }
+        }
+
+        return $requeued;
+    }
+
+    /** Write diagnostic messages only when WordPress debugging is enabled. */
+    private function debug_log($message) {
+        if (defined('WP_DEBUG') && WP_DEBUG) {
+            // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- This diagnostic logger writes only when the site owner explicitly enables WP_DEBUG.
+            error_log((string) $message);
+        }
+    }
+
+    /** Log scheduler failures without allowing diagnostics to interrupt tracking. */
+    private function log_generic_historical_scheduler_error($hook, $message) {
+        $this->debug_log('[Statora Plus] Historical scheduler failure for ' . sanitize_key((string) $hook) . ': ' . sanitize_text_field((string) $message));
+    }
+
+    /** Schedule retries for deferred records independently from the main import cursor. */
+    private function schedule_generic_historical_failure_retry($delay, $source_id, $origin_key) {
+        $args = [absint($source_id), sanitize_key((string) $origin_key)];
+        $hook = 'statpl_generic_view_retry_failed_records';
+        $requested_timestamp = time() + max(1, (int) $delay);
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $existing_timestamp = false;
+            if (function_exists('as_next_scheduled_action')) {
+                try {
+                    $existing_timestamp = as_next_scheduled_action($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_lookup', $exception->getMessage());
+                }
+            }
+
+            // Keep an earlier/equal action, but replace a later one. Otherwise a
+            // newly-created short-backoff failure could wait behind an older,
+            // long-backoff retry for the same source-origin.
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp && function_exists('as_unschedule_all_actions')) {
+                try {
+                    as_unschedule_all_actions($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    // The existing action may still be queued. Retain it rather
+                    // than create a duplicate whose execution order is unknown.
+                    $this->log_generic_historical_scheduler_error($hook . '_unschedule', $exception->getMessage());
+                    return true;
+                }
+            } elseif (function_exists('as_has_scheduled_action')) {
+                try {
+                    if (as_has_scheduled_action($hook, $args, 'statpl-plus')) {
+                        // Without reliable timestamp/removal APIs, retain the
+                        // existing action rather than duplicate the worker.
+                        return true;
+                    }
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_presence_check', $exception->getMessage());
+                }
+            }
+            try {
+                $action_id = as_schedule_single_action($requested_timestamp, $hook, $args, 'statpl-plus');
+                if ($action_id) {
+                    return true;
+                }
+            } catch (Throwable $exception) {
+                $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            }
+            // Fall through to WP-Cron if Action Scheduler did not accept the action.
+        }
+
+        try {
+            $existing_timestamp = wp_next_scheduled($hook, $args);
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp) {
+                wp_unschedule_event((int) $existing_timestamp, $hook, $args);
+            }
+            $scheduled = wp_schedule_single_event($requested_timestamp, $hook, $args);
+            if (!$scheduled || is_wp_error($scheduled)) {
+                $this->log_generic_historical_scheduler_error($hook, is_wp_error($scheduled) ? $scheduled->get_error_message() : 'WP-Cron rejected the event.');
+                return false;
+            }
+            return true;
+        } catch (Throwable $exception) {
+            $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            return false;
+        }
+    }
+
+    /** Acquire a connection-scoped advisory lock and capture its owning session. */
+    private function acquire_generic_advisory_lock($lock_name) {
+        global $wpdb;
+        try {
+            $row = statpl_db_get_row(statpl_db_prepare(
+                'SELECT CONNECTION_ID() AS connection_id, GET_LOCK(%s, 0) AS lock_acquired',
+                (string) $lock_name
+            ), ARRAY_A);
+        } catch (Throwable $exception) {
+            return ['acquired' => false, 'status' => 'lock_error', 'error' => $exception->getMessage()];
+        }
+        if (!is_array($row) || !empty($wpdb->last_error) || (string) ($row['lock_acquired'] ?? '') !== '1' || empty($row['connection_id'])) {
+            return ['acquired' => false, 'status' => 'lock_busy_or_unavailable', 'error' => (string) $wpdb->last_error];
+        }
+        return ['acquired' => true, 'connection_id' => (string) $row['connection_id'], 'lock_name' => (string) $lock_name];
+    }
+
+    /** Roll back an open import transaction only on its original DB session. */
+    private function rollback_generic_import_transaction(&$transaction_open, $origin_lock) {
+        global $wpdb;
+        if (!$transaction_open) {
+            return true;
+        }
+        // Never issue transaction control on a transparently reconnected session.
+        // The caller may retry once from finally if this attempt fails.
+        for ($attempt = 0; $attempt < 1; $attempt++) {
+            if (!$this->generic_db_session_matches_lock($origin_lock)) {
+                return false;
+            }
+            $result = statpl_db_query('ROLLBACK');
+            if ($result !== false) {
+                $transaction_open = false;
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /** Confirm the current wpdb connection is the session that acquired a lock, regardless of lock ownership. */
+    private function generic_db_session_matches_lock($lock) {
+        global $wpdb;
+        if (!is_array($lock) || empty($lock['acquired']) || empty($lock['connection_id'])) {
+            return false;
+        }
+        try {
+            $connection_id = statpl_db_get_var('SELECT CONNECTION_ID()');
+        } catch (Throwable $exception) {
+            return false;
+        }
+        return $connection_id !== null
+            && empty($wpdb->last_error)
+            && (string) $connection_id === (string) $lock['connection_id'];
+    }
+
+    /** Confirm the current wpdb session still owns the lock-acquiring connection. */
+    private function generic_advisory_lock_session_is_current($lock) {
+        global $wpdb;
+        if (!is_array($lock) || empty($lock['acquired']) || empty($lock['connection_id'])) {
+            return false;
+        }
+        try {
+            // Session identity alone is insufficient: code running on the same
+            // connection could have released or replaced the named lock. Verify
+            // both the connection and the actual lock owner in one SQL read.
+            $row = statpl_db_get_row(statpl_db_prepare(
+                'SELECT CONNECTION_ID() AS connection_id, IS_USED_LOCK(%s) AS lock_owner',
+                (string) $lock['lock_name']
+            ), ARRAY_A);
+        } catch (Throwable $exception) {
+            return false;
+        }
+        return is_array($row)
+            && empty($wpdb->last_error)
+            && (string) ($row['connection_id'] ?? '') === (string) $lock['connection_id']
+            && (string) ($row['lock_owner'] ?? '') === (string) $lock['connection_id'];
+    }
+
+    /** Release only on the original session; a lost session releases its own locks server-side. */
+    private function release_generic_advisory_lock($lock, $context = '') {
+        global $wpdb;
+        if (!$this->generic_advisory_lock_session_is_current($lock)) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: advisory lock session changed before release' . ($context !== '' ? ' (' . sanitize_key($context) . ')' : '') . '.');
+            }
+            return false;
+        }
+        try {
+            $released = statpl_db_get_var(statpl_db_prepare('SELECT RELEASE_LOCK(%s)', (string) $lock['lock_name']));
+            if ((string) $released === '1' && empty($wpdb->last_error)) {
+                return true;
+            }
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: advisory lock release failed' . ($context !== '' ? ' (' . sanitize_key($context) . ')' : '') . ': ' . $exception->getMessage());
+            }
+            return false;
+        }
+        if (defined('WP_DEBUG') && WP_DEBUG) {
+            $this->debug_log('Statora Plus: advisory lock release was not confirmed' . ($context !== '' ? ' (' . sanitize_key($context) . ')' : '') . '.');
+        }
+        return false;
+    }
+
+    /** Replay due failed records from their saved immutable batch checkpoint. */
+    public function retry_generic_historical_view_failures($source_id = 0, $origin_key = '') {
+        global $wpdb;
+        $source_id = absint($source_id);
+        $origin_key = sanitize_key((string) $origin_key);
+        if (!$source_id || $origin_key === '') {
+            return ['status' => 'invalid_input'];
+        }
+
+        $now = current_time('mysql');
+        $failure = statpl_db_get_row(statpl_db_prepare(
+            "SELECT retry_checkpoint, next_retry_at FROM {$this->view_source_failures_table}
+             WHERE source_id = %d AND origin_key = %s AND status = 'retry' AND next_retry_at <= %s
+               AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''
+             ORDER BY next_retry_at ASC, id ASC LIMIT 1",
+            $source_id,
+            $origin_key,
+            $now
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error)) {
+            $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+            return ['status' => 'failure_lookup_error'];
+        }
+        if (!$failure) {
+            $next = statpl_db_get_var(statpl_db_prepare(
+                "SELECT MIN(next_retry_at) FROM {$this->view_source_failures_table}
+                 WHERE source_id = %d AND origin_key = %s AND status = 'retry'
+                   AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''",
+                $source_id,
+                $origin_key
+            ));
+            if (!empty($wpdb->last_error)) {
+                // A failed deadline lookup is not evidence that the retry queue is
+                // empty. Preserve the worker trigger and avoid status aggregation
+                // from an incomplete view of the durable failure ledger.
+                $this->log_generic_historical_scheduler_error('retry_ledger_next_deadline', $wpdb->last_error);
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'failure_ledger_deadline_failed'];
+            }
+            if ($next) {
+                $next_timestamp = strtotime((string) $next);
+                $delay = ($next_timestamp !== false) ? max(1, $next_timestamp - current_time('timestamp')) : 300;
+                $this->schedule_generic_historical_failure_retry(min(86400, $delay), $source_id, $origin_key);
+            }
+            $this->refresh_generic_historical_source_status($source_id);
+            return ['status' => 'no_due_failures'];
+        }
+
+        $lock_name = 'statpl_generic_' . substr(hash('sha256', $wpdb->prefix . ':' . $source_id . ':' . $origin_key), 0, 40);
+        $origin_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($origin_lock['acquired'])) {
+            $this->schedule_generic_historical_failure_retry(30, $source_id, $origin_key);
+            return ['status' => 'worker_already_running'];
+        }
+
+        try {
+            // The initial lookup above only determines whether this worker appears
+            // eligible. Re-read the durable row after acquiring the same origin lock
+            // used by the main importer: another worker may have resolved or changed
+            // this retry while we were waiting. Never replay a stale checkpoint.
+            if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+                $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+                return ['status' => 'origin_lock_session_lost'];
+            }
+            $locked_failure = statpl_db_get_row(statpl_db_prepare(
+                "SELECT retry_checkpoint, next_retry_at FROM {$this->view_source_failures_table}
+                 WHERE source_id = %d AND origin_key = %s AND status = 'retry'
+                   AND next_retry_at <= %s AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''
+                 ORDER BY next_retry_at ASC, id ASC LIMIT 1",
+                $source_id,
+                $origin_key,
+                current_time('mysql')
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error)) {
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'failure_lookup_error'];
+            }
+            if (!$locked_failure) {
+                return ['status' => 'retry_no_longer_due'];
+            }
+
+            $retry_checkpoint = json_decode($locked_failure['retry_checkpoint'], true);
+            if (!is_array($retry_checkpoint) || !$retry_checkpoint) {
+                // Corrupt replay metadata is not silently discarded or counted as a view.
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'invalid_retry_checkpoint'];
+            }
+
+            if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+                $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+                return ['status' => 'origin_lock_session_lost'];
+            }
+            $result = $this->process_generic_historical_view_import_batch($source_id, $origin_key, $retry_checkpoint, $origin_lock);
+        } finally {
+            $this->release_generic_advisory_lock($origin_lock, 'retry_origin');
+        }
+
+        // The processing lock above protects replay itself. Reacquire the same
+        // origin lock before reconciling ledger counts and origin status: the main
+        // importer may have started immediately after the replay lock was released.
+        // Re-reading under the lock prevents this worker from applying stale status
+        // decisions over a newer main-import checkpoint/state transition.
+        $post_origin_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($post_origin_lock['acquired'])) {
+            $this->schedule_generic_historical_failure_retry(30, $source_id, $origin_key);
+            return ['status' => 'post_processing_lock_busy'];
+        }
+
+        try {
+        if (!$this->generic_advisory_lock_session_is_current($post_origin_lock)) {
+            $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+            return ['status' => 'post_processing_lock_session_lost'];
+        }
+        $remaining_value = statpl_db_get_var(statpl_db_prepare(
+            "SELECT COUNT(*) FROM {$this->view_source_failures_table}
+             WHERE source_id = %d AND origin_key = %s AND status = 'retry'
+               AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''",
+            $source_id,
+            $origin_key
+        ));
+        if (!empty($wpdb->last_error) || $remaining_value === null) {
+            // A failed count must never be interpreted as an empty ledger. Keep
+            // the worker alive and let the next pass re-read durable retry rows.
+            $this->log_generic_historical_scheduler_error('retry_ledger_count', $wpdb->last_error ?: 'Retry ledger count returned NULL.');
+            $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+            return ['status' => 'failure_ledger_count_failed'];
+        }
+        $remaining = (int) $remaining_value;
+        if ($remaining > 0) {
+            $next = statpl_db_get_var(statpl_db_prepare(
+                "SELECT MIN(next_retry_at) FROM {$this->view_source_failures_table}
+                 WHERE source_id = %d AND origin_key = %s AND status = 'retry'
+                   AND retry_checkpoint IS NOT NULL AND retry_checkpoint <> ''",
+                $source_id,
+                $origin_key
+            ));
+            if (!empty($wpdb->last_error)) {
+                $this->log_generic_historical_scheduler_error('retry_ledger_deadline', $wpdb->last_error);
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'failure_ledger_deadline_failed', 'remaining' => $remaining];
+            }
+            $next_timestamp = $next ? strtotime((string) $next) : false;
+            $delay = ($next_timestamp !== false) ? max(1, $next_timestamp - current_time('timestamp')) : 300;
+            $this->schedule_generic_historical_failure_retry(min(86400, $delay), $source_id, $origin_key);
+        } else {
+            $blocked_value = statpl_db_get_var(statpl_db_prepare(
+                "SELECT COUNT(*) FROM {$this->view_source_failures_table}
+                 WHERE source_id = %d AND origin_key = %s AND status = 'blocked'",
+                $source_id,
+                $origin_key
+            ));
+            if (!empty($wpdb->last_error) || $blocked_value === null) {
+                $this->log_generic_historical_scheduler_error('blocked_ledger_count', $wpdb->last_error ?: 'Blocked ledger count returned NULL.');
+                $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                return ['status' => 'failure_ledger_count_failed'];
+            }
+            $blocked = (int) $blocked_value;
+            $current_state = $this->get_view_source_origin_state($source_id, $origin_key);
+            $origin_status = $current_state['origin_status'] ?? '';
+            if (in_array($origin_status, ['pending', 'snapshot_ready', 'importing', 'retry_wait'], true)) {
+                // The retry worker cannot infer whether the main scan has reached
+                // the immutable snapshot boundary. This remains true when some
+                // records are already blocked: the main cursor may still have
+                // later batches to import. Resume the main scan and let its own
+                // has_more result, together with the durable ledger counts, decide
+                // whether the final state is completed or needs_attention.
+                $updates = [
+                    'status' => 'importing',
+                    'completed_at' => null,
+                ];
+                if ($blocked === 0) {
+                    $updates['last_error'] = null;
+                }
+                $origin_state_result = $this->update_view_source_origin_state($source_id, $origin_key, $updates, $post_origin_lock);
+                if (!in_array($origin_state_result['status'] ?? '', ['updated'], true)) {
+                    // Do not treat a failed/ambiguous state transition as a
+                    // successful retry finalization. Keep recovery scheduled.
+                    $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+                    return [
+                        'status' => 'origin_state_recovery_failed',
+                        'origin_state' => $origin_state_result,
+                        'result' => $result,
+                        'remaining' => $remaining,
+                    ];
+                }
+                $this->schedule_generic_historical_view_import_batch(5, $source_id, $origin_key);
+            } elseif ($blocked > 0 && $origin_status !== 'needs_attention') {
+                // Only a non-progressing, nonterminal origin may be finalized here.
+                // Never downgrade an already-finalized attention state.
+                $origin_state_result = $this->update_view_source_origin_state($source_id, $origin_key, [
+                    'status' => 'needs_attention',
+                    'last_error' => 'Some historical records could not be recovered after three total attempts.',
+                ], $post_origin_lock);
+                if (!in_array($origin_state_result['status'] ?? '', ['updated'], true)) {
+                    $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+                    return [
+                        'status' => 'origin_state_recovery_failed',
+                        'origin_state' => $origin_state_result,
+                        'result' => $result,
+                        'remaining' => $remaining,
+                    ];
+                }
+            }
+        }
+
+        // Ledger reconciliation may itself encounter a reconnect after the
+        // post-processing lock was acquired. Never aggregate source status unless
+        // this request still owns that exact MySQL lock session.
+        if ($this->generic_advisory_lock_session_is_current($post_origin_lock)) {
+            $this->refresh_generic_historical_source_status($source_id);
+        } else {
+            $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+            return ['status' => 'post_processing_session_lost', 'result' => $result, 'remaining' => $remaining];
+        }
+        return ['status' => 'retry_processed', 'result' => $result, 'remaining' => $remaining];
+        } finally {
+            $this->release_generic_advisory_lock($post_origin_lock, 'retry_post_processing');
+        }
+    }
+
+    /** Return a discovered adapter instance for later snapshot/import workers. */
+    private function get_historical_view_adapter($adapter_key) {
+        $adapter_key = sanitize_key((string) $adapter_key);
+        return isset($this->historical_view_adapters[$adapter_key])
+            ? $this->historical_view_adapters[$adapter_key]
+            : null;
+    }
+
+    /** Schedule the generic historical importer without overlapping scheduled runs. */
+    private function schedule_generic_historical_view_import_batch($delay = 10, $source_id = 0, $origin_key = '') {
+        $args = [(int) $source_id, (string) $origin_key];
+        $hook = 'statpl_generic_view_import_batch';
+        $requested_timestamp = time() + max(1, (int) $delay);
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $existing_timestamp = false;
+            if (function_exists('as_next_scheduled_action')) {
+                try {
+                    $existing_timestamp = as_next_scheduled_action($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_lookup', $exception->getMessage());
+                }
+            }
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp && function_exists('as_unschedule_all_actions')) {
+                try {
+                    as_unschedule_all_actions($hook, $args, 'statpl-plus');
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_unschedule', $exception->getMessage());
+                    return true;
+                }
+            } elseif ($existing_timestamp) {
+                return true;
+            } elseif (function_exists('as_has_scheduled_action')) {
+                try {
+                    if (as_has_scheduled_action($hook, $args, 'statpl-plus')) {
+                        // Without reliable timing/removal APIs, retain the existing action.
+                        return true;
+                    }
+                } catch (Throwable $exception) {
+                    $this->log_generic_historical_scheduler_error($hook . '_presence_check', $exception->getMessage());
+                }
+            }
+            try {
+                $action_id = as_schedule_single_action($requested_timestamp, $hook, $args, 'statpl-plus');
+                if ($action_id) {
+                    return true;
+                }
+            } catch (Throwable $exception) {
+                $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            }
+            // Fall through to WP-Cron if Action Scheduler did not accept the action.
+        }
+
+        try {
+            $existing_timestamp = wp_next_scheduled($hook, $args);
+            if ($existing_timestamp && (int) $existing_timestamp <= $requested_timestamp) {
+                return true;
+            }
+            if ($existing_timestamp) {
+                wp_unschedule_event((int) $existing_timestamp, $hook, $args);
+            }
+            $scheduled = wp_schedule_single_event($requested_timestamp, $hook, $args);
+            if (!$scheduled || is_wp_error($scheduled)) {
+                $this->log_generic_historical_scheduler_error($hook, is_wp_error($scheduled) ? $scheduled->get_error_message() : 'WP-Cron rejected the event.');
+                return false;
+            }
+            return true;
+        } catch (Throwable $exception) {
+            $this->log_generic_historical_scheduler_error($hook, $exception->getMessage());
+            return false;
+        }
+    }
+
+    /** Persist a generic-source failure with bounded exponential retry metadata. */
+    private function record_generic_historical_view_failure($source_id, $origin_key, $record_key, $product_id, $error, $retry_checkpoint = null, $max_attempts = 8, $lock_context = null) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        if (!$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return ['attempts' => 0, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'lock_session_lost'];
+        }
+        $record_key = substr((string) $record_key, 0, 191);
+        if ($record_key === '') {
+            $record_key = 'batch:' . substr(hash('sha256', (string) $origin_key), 0, 32);
+        }
+        $record_hash = hash('sha256', (string) $origin_key . "\0" . $record_key);
+        $existing = statpl_db_get_row(statpl_db_prepare(
+            "SELECT id, attempts, status, next_retry_at, retry_checkpoint, last_error FROM {$this->view_source_failures_table} WHERE source_id = %d AND source_record_hash = %s LIMIT 1",
+            $source_id,
+            $record_hash
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error)) {
+            $this->log_generic_historical_scheduler_error('failure_ledger_lookup', $wpdb->last_error);
+            return ['attempts' => 0, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'ledger_lookup_failed'];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return ['attempts' => 0, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'lock_session_lost'];
+        }
+        $now = current_time('mysql');
+        if ($existing && isset($existing['status']) && $existing['status'] === 'blocked') {
+            // The ledger row may have been committed even if the corresponding
+            // origin-state update failed on the previous pass. Repair that
+            // derived state on every subsequent locked observation without
+            // incrementing attempts or rewriting the durable failure record.
+            $existing_origin_status = empty($existing['retry_checkpoint']) ? 'needs_attention' : 'retry_wait';
+            $origin_state_saved = $this->update_view_source_origin_state($source_id, $origin_key, [
+                'last_error' => substr((string) ($existing['last_error'] ?? ''), 0, 2000),
+                'status' => $existing_origin_status,
+            ], $lock_context);
+            if (empty($origin_state_saved['status']) || $origin_state_saved['status'] !== 'updated') {
+                $this->log_generic_historical_scheduler_error('failure_origin_state_recovery', $origin_state_saved['error'] ?? ($origin_state_saved['status'] ?? 'Unable to recover origin state from the existing blocked failure record.'));
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                return ['attempts' => (int) $existing['attempts'], 'blocked' => true, 'persisted' => true, 'retry_delay' => 0, 'status' => 'origin_state_recovery_failed'];
+            }
+            return ['attempts' => (int) $existing['attempts'], 'blocked' => true, 'persisted' => true, 'retry_delay' => 0, 'status' => 'already_blocked'];
+        }
+        if ($existing && !empty($existing['next_retry_at']) && $existing['next_retry_at'] > $now) {
+            $retry_at = strtotime((string) $existing['next_retry_at']);
+            $now_at = strtotime((string) $now);
+            $remaining = ($retry_at !== false && $now_at !== false) ? max(1, $retry_at - $now_at) : 60;
+            $origin_state_saved = $this->update_view_source_origin_state($source_id, $origin_key, [
+                'last_error' => substr((string) ($existing['last_error'] ?? ''), 0, 2000),
+                'status' => 'retry_wait',
+            ], $lock_context);
+            if (empty($origin_state_saved['status']) || $origin_state_saved['status'] !== 'updated') {
+                $this->log_generic_historical_scheduler_error('failure_origin_state_recovery', $origin_state_saved['error'] ?? ($origin_state_saved['status'] ?? 'Unable to recover origin state from the existing retry failure record.'));
+                $this->schedule_generic_historical_failure_retry(min(86400, $remaining), $source_id, $origin_key);
+                return ['attempts' => (int) $existing['attempts'], 'blocked' => true, 'persisted' => true, 'retry_delay' => 0, 'status' => 'origin_state_recovery_failed'];
+            }
+            return ['attempts' => (int) $existing['attempts'], 'blocked' => false, 'persisted' => true, 'retry_delay' => min(86400, $remaining), 'status' => 'retry_already_scheduled'];
+        }
+
+        $attempts = $existing ? ((int) $existing['attempts'] + 1) : 1;
+        $max_attempts = max(1, absint($max_attempts));
+        $blocked = $attempts >= $max_attempts;
+        $delay = min(86400, 60 * (2 ** min(10, max(0, $attempts - 1))));
+        $next_retry = $blocked ? null : current_datetime()->modify('+' . $delay . ' seconds')->format('Y-m-d H:i:s');
+        $data = [
+            'source_id' => $source_id,
+            'origin_key' => sanitize_key((string) $origin_key),
+            'source_record_key' => $record_key,
+            'source_record_hash' => $record_hash,
+            'product_id' => absint($product_id),
+            'attempts' => $attempts,
+            'last_error' => substr(sanitize_textarea_field((string) $error), 0, 60000),
+            'status' => $blocked ? 'blocked' : 'retry',
+            'next_retry_at' => $next_retry,
+            'retry_checkpoint' => is_array($retry_checkpoint) ? wp_json_encode($retry_checkpoint) : null,
+            'updated_at' => $now,
+        ];
+        $allowed_columns = [
+            'source_id', 'origin_key', 'source_record_key', 'source_record_hash',
+            'product_id', 'attempts', 'last_error', 'status', 'next_retry_at',
+            'retry_checkpoint', 'updated_at',
+        ];
+        $columns = array_keys($data);
+        if (array_diff($columns, $allowed_columns) || array_diff($allowed_columns, $columns)) {
+            $this->log_generic_historical_scheduler_error('failure_ledger_schema', 'Failure ledger data did not match the fixed column allowlist.');
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'ledger_schema_mismatch'];
+        }
+        $placeholders = [];
+        $values = [];
+        foreach ($allowed_columns as $column) {
+            $value = $data[$column];
+            $placeholders[] = is_int($value) ? '%d' : '%s';
+            $values[] = $value;
+        }
+        $lock_name = (string) ($lock_context['lock_name'] ?? '');
+        if ($lock_name === '' || !$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'lock_session_lost'];
+        }
+
+        if ($existing) {
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- The SET placeholders are generated from the fixed allowlist; update_values is generated from the same allowlist with the same immutable key columns excluded, followed by id and lock_name.
+            $set = [];
+            foreach ($allowed_columns as $column) {
+                if (in_array($column, ['source_id', 'source_record_hash'], true)) {
+                    continue;
+                }
+                $value = $data[$column];
+                $set[] = "`{$column}` = " . (is_int($value) ? '%d' : '%s');
+            }
+            $update_values = [];
+            foreach ($allowed_columns as $column) {
+                if (!in_array($column, ['source_id', 'source_record_hash'], true)) {
+                    $update_values[] = $data[$column];
+                }
+            }
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- The SET placeholder list and update_values are built in the same pass over the fixed 11-column allowlist, excluding the same two immutable key columns; the two trailing placeholders are always id and lock_name.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $query = /* phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- Placeholder fragments and their values are assembled together from the same fixed allowlists; optional lock predicates and matching values are added together. */ statpl_db_prepare(
+                "UPDATE {$this->view_source_failures_table} SET " . implode(', ', /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $set) . " WHERE id = %d AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+                array_merge($update_values, [(int) $existing['id'], $lock_name])
+            );
+        } else {
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $query = statpl_db_prepare(
+                "INSERT INTO {$this->view_source_failures_table} (" . implode(', ', /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ array_map(function ($column) { return "`{$column}`"; }, $columns)) . ") SELECT " . implode(', ', $placeholders) . " WHERE IS_USED_LOCK(%s) = CONNECTION_ID()",
+                array_merge($values, [$lock_name])
+            );
+        }
+        // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $query is assigned exclusively from statpl_db_prepare() in both branches; dynamic identifiers and column names come from fixed allowlists, and all data values use placeholders.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+        $persisted = statpl_db_query($query);
+        if ($persisted === false || $wpdb->last_error !== '') {
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'ledger_write_failed', 'error' => $wpdb->last_error];
+        }
+        if ($persisted !== 1) {
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => false, 'retry_delay' => 0, 'status' => 'lock_session_lost'];
+        }
+        if (strpos($record_key, 'batch:') !== 0 && $record_key !== 'snapshot_initialization') {
+            $this->save_generic_historical_report_record($source_id, $origin_key, $record_hash, $blocked ? 'failed' : 'retry', $attempts, 'record_import_failed');
+        }
+
+        $origin_status = ($blocked && !is_array($retry_checkpoint)) ? 'needs_attention' : 'retry_wait';
+        $origin_state_saved = $this->update_view_source_origin_state($source_id, $origin_key, [
+            'last_error' => substr((string) $error, 0, 2000),
+            'status' => $origin_status,
+        ], $lock_context);
+        if (empty($origin_state_saved['status']) || !in_array($origin_state_saved['status'], ['updated'], true)) {
+            $this->log_generic_historical_scheduler_error('failure_origin_state', $origin_state_saved['error'] ?? ($origin_state_saved['status'] ?? 'Unable to update origin state after recording a failure.'));
+            // The failure row is durable, but its derived origin status may be
+            // stale. Ensure another locked pass is scheduled to repair the
+            // origin state; do not rely on callers, which correctly stop when
+            // this operation reports blocked=true.
+            if (is_array($retry_checkpoint)) {
+                $this->schedule_generic_historical_failure_retry(max(60, $delay), $source_id, $origin_key);
+            } else {
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            }
+            return ['attempts' => $attempts, 'blocked' => true, 'persisted' => true, 'retry_delay' => 0, 'status' => 'origin_state_update_failed'];
+        }
+
+        return ['attempts' => $attempts, 'blocked' => $blocked, 'persisted' => true, 'retry_delay' => $blocked ? 0 : $delay];
+    }
+
+    /** Clear a previously recorded failure after its record is safely handled. */
+    private function clear_generic_historical_view_failure($source_id, $origin_key, $record_key, $lock_context = null, $report_outcome = 'imported') {
+        global $wpdb;
+        if (!$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return false;
+        }
+        $record_key = substr((string) $record_key, 0, 191);
+        if ($record_key === '') {
+            return false;
+        }
+        $record_hash = hash('sha256', (string) $origin_key . "\0" . $record_key);
+        $existing_failure = statpl_db_get_row(statpl_db_prepare(
+            "SELECT attempts FROM {$this->view_source_failures_table} WHERE source_id = %d AND source_record_hash = %s LIMIT 1",
+            absint($source_id), $record_hash
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error)) { return false; }
+        if ($report_outcome === 'imported' && strpos($record_key, 'batch:') !== 0 && $record_key !== 'snapshot_initialization') {
+            $attempts = is_array($existing_failure) ? (int) ($existing_failure['attempts'] ?? 0) : 0;
+            if (!$this->save_generic_historical_report_record($source_id, $origin_key, $record_hash, 'imported', $attempts, '')) { return false; }
+        }
+        $lock_name = (string) ($lock_context['lock_name'] ?? '');
+        if ($lock_name === '' || !$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return false;
+        }
+        $deleted = statpl_db_query(statpl_db_prepare(
+            "DELETE FROM {$this->view_source_failures_table} WHERE source_id = %d AND source_record_hash = %s AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+            absint($source_id),
+            $record_hash,
+            $lock_name
+        ));
+        if ($deleted === false || $wpdb->last_error !== '') {
+            $this->log_generic_historical_scheduler_error('failure_ledger_clear', $wpdb->last_error ?: 'Unable to clear a resolved failure record.');
+            return false;
+        }
+        // A zero-row DELETE is ambiguous: the failure row may already be absent,
+        // or the SQL ownership predicate may have rejected the operation after a
+        // reconnect/lock loss. Only treat the former as successful, and confirm
+        // that this worker still owns the original lock session after the query.
+        if (!$this->generic_advisory_lock_session_is_current($lock_context)) {
+            return false;
+        }
+        return true;
+    }
+
+    /**
+     * Process one generic source-origin batch. Each accepted record is committed
+     * atomically with its source event and product total; the checkpoint advances
+     * only after the record is safely applied or recognized as an exact duplicate.
+     */
+    public function run_generic_historical_view_import_batch($source_id = 0, $origin_key = '') {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = sanitize_key((string) $origin_key);
+        if (!$source_id || $origin_key === '') {
+            return ['status' => 'invalid_input'];
+        }
+
+        // A connection-scoped MySQL advisory lock prevents two cron/Action
+        // Scheduler workers from advancing the same source-origin checkpoint.
+        // The lock is released automatically if PHP or the DB connection dies.
+        $lock_name = 'statpl_generic_' . substr(hash('sha256', $wpdb->prefix . ':' . $source_id . ':' . $origin_key), 0, 40);
+        $origin_lock = $this->acquire_generic_advisory_lock($lock_name);
+        if (empty($origin_lock['acquired'])) {
+            $this->schedule_generic_historical_view_import_batch(30, $source_id, $origin_key);
+            return ['status' => 'worker_already_running'];
+        }
+
+        try {
+            if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                return ['status' => 'origin_lock_session_lost'];
+            }
+            $result = $this->process_generic_historical_view_import_batch($source_id, $origin_key, null, $origin_lock);
+            // The processing method can return after detecting a lost MySQL session.
+            // Do not start a new source-status write on a transparently reconnected
+            // session: it would run outside the origin lock that serialized this worker.
+            if ($this->generic_advisory_lock_session_is_current($origin_lock)) {
+                $this->refresh_generic_historical_source_status($source_id);
+            } else {
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            }
+            return $result;
+        } finally {
+            $this->release_generic_advisory_lock($origin_lock, 'main_importer');
+        }
+    }
+
+    /** Validate a normalized source datetime without allowing silent MySQL coercion. */
+    private function is_valid_generic_historical_datetime($value) {
+        if ($value === null || $value === '') {
+            return true;
+        }
+        if (!is_string($value) || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $value)) {
+            return false;
+        }
+        $date = DateTime::createFromFormat('!Y-m-d H:i:s', $value);
+        $errors = DateTime::getLastErrors();
+        return $date instanceof DateTime
+            && ($errors === false || (empty($errors['warning_count']) && empty($errors['error_count'])))
+            && $date->format('Y-m-d H:i:s') === $value;
+    }
+
+    /** Accept only a JSON-safe scalar/array cursor that can be persisted and resumed. */
+    private function is_valid_generic_historical_cursor($cursor) {
+        if ($cursor === null || is_resource($cursor) || is_object($cursor)) {
+            return false;
+        }
+        $encoded = wp_json_encode($cursor);
+        return is_string($encoded) && strlen($encoded) <= 60000;
+    }
+
+    /**
+     * Discover overlap candidates fairly across source IDs. A global LIMIT can let
+     * a high-volume source crowd every other adapter out of the reconciliation set.
+     * The per-source fetch is bounded, then candidates are interleaved round-robin.
+     */
+    private function get_generic_reconciliation_candidates_by_source($mode, $criteria, $limit = 25) {
+        global $wpdb;
+
+        if (!is_array($criteria)) {
+            return ['status' => 'error', 'error' => 'Invalid reconciliation criteria.', 'events' => [], 'observed' => 0, 'truncated' => false];
+        }
+        if ($mode === 'fingerprint') {
+            $fingerprint = isset($criteria['fingerprint']) ? (string) $criteria['fingerprint'] : '';
+            $source_id = isset($criteria['source_id']) ? absint($criteria['source_id']) : 0;
+            if ($fingerprint === '' || !$source_id) {
+                return ['status' => 'error', 'error' => 'Invalid fingerprint reconciliation criteria.', 'events' => [], 'observed' => 0, 'truncated' => false];
+            }
+            $where_sql = 'events.source_fingerprint = %s AND events.source_id <> %d';
+            $where_args = [$fingerprint, $source_id];
+        } elseif ($mode === 'temporal') {
+            $source_id = isset($criteria['source_id']) ? absint($criteria['source_id']) : 0;
+            $product_id = isset($criteria['product_id']) ? absint($criteria['product_id']) : 0;
+            $period_start = isset($criteria['period_start']) ? (string) $criteria['period_start'] : '';
+            $period_end = isset($criteria['period_end']) ? (string) $criteria['period_end'] : '';
+            if (!$source_id || !$product_id || $period_start === '' || $period_end === '') {
+                return ['status' => 'error', 'error' => 'Invalid temporal reconciliation criteria.', 'events' => [], 'observed' => 0, 'truncated' => false];
+            }
+            $where_sql = 'events.source_id <> %d AND events.product_id = %d AND events.period_start <= %s AND events.period_end >= %s';
+            $where_args = [$source_id, $product_id, $period_end, $period_start];
+        } else {
+            return ['status' => 'error', 'error' => 'Unsupported reconciliation mode.', 'events' => [], 'observed' => 0, 'truncated' => false];
+        }
+        $limit = max(1, min(25, absint($limit)));
+        $reconciliation_sql = "SELECT DISTINCT events.source_id
+             FROM {$this->view_source_events_table} AS events
+             WHERE {$where_sql}
+             ORDER BY events.source_id ASC";
+        // The criteria branches above define either four temporal placeholders
+        // or two exact-match placeholders; prepare receives the matching values.
+        if ($mode === 'temporal') {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_ids = statpl_db_get_col(statpl_db_prepare(
+                /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $reconciliation_sql,
+                $source_id,
+                $product_id,
+                $period_end,
+                $period_start
+            ));
+        } else {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_ids = statpl_db_get_col(statpl_db_prepare(
+                /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $reconciliation_sql,
+                $fingerprint,
+                $source_id
+            ));
+        }
+        if (!empty($wpdb->last_error)) {
+            return ['status' => 'error', 'error' => (string) $wpdb->last_error, 'events' => [], 'observed' => 0, 'truncated' => false];
+        }
+
+        $per_source = [];
+        $observed = 0;
+        $truncated = false;
+        foreach ((array) $source_ids as $candidate_source_id) {
+            $candidate_source_id = absint($candidate_source_id);
+            if (!$candidate_source_id) {
+                continue;
+            }
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                "SELECT events.id, events.source_id, events.source_record_key,
+                        sources.source_key AS candidate_source_key,
+                        sources.adapter_key AS candidate_adapter_key, events.product_id,
+                        events.record_type, events.observed_views, events.period_start,
+                        events.period_end, events.applied_views
+                 FROM {$this->view_source_events_table} AS events
+                 LEFT JOIN {$this->view_sources_table} AS sources ON sources.id = events.source_id
+                 WHERE ({$where_sql}) AND events.source_id = %d
+                 ORDER BY events.period_start ASC, events.period_end ASC, events.id ASC
+                 LIMIT 26 FOR UPDATE",
+                array_merge($where_args, [$candidate_source_id])
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error)) {
+                return ['status' => 'error', 'error' => (string) $wpdb->last_error, 'events' => [], 'observed' => $observed, 'truncated' => $truncated];
+            }
+            if (count($rows) > 25) {
+                $truncated = true;
+                $rows = array_slice($rows, 0, 25);
+            }
+            $observed += count($rows);
+            if ($rows) {
+                $per_source[$candidate_source_id] = array_values($rows);
+            }
+        }
+
+        $events = [];
+        $round = 0;
+        do {
+            $added_this_round = false;
+            foreach ($per_source as $source_rows) {
+                if (isset($source_rows[$round])) {
+                    $events[] = $source_rows[$round];
+                    $added_this_round = true;
+                    if (count($events) > $limit) {
+                        $truncated = true;
+                        break 2;
+                    }
+                }
+            }
+            $round++;
+        } while ($added_this_round);
+
+        if ($observed > count($events)) {
+            $truncated = true;
+        }
+        return [
+            'status' => 'ok',
+            'events' => array_slice($events, 0, $limit),
+            'observed' => $observed,
+            'truncated' => $truncated,
+        ];
+    }
+
+    /**
+     * Build a source-wide, deterministic overlap profile for the current record.
+     * This is deliberately descriptive: timestamps and aggregate periods are not
+     * proof that two providers observed the same pageview. The profile gives the
+     * later reconciliation pass comparable signals without changing applied_views.
+     */
+    /**
+     * Return declared source capabilities for reconciliation review.
+     * This is a descriptive capability inventory, not a numeric reliability score.
+     * Missing declarations remain unknown; they are never inferred from plugin names.
+     */
+    private function get_generic_source_capability_profiles($source_ids) {
+        global $wpdb;
+
+        $source_ids = array_values(array_unique(array_filter(array_map('absint', (array) $source_ids))));
+        if (!$source_ids) {
+            return ['status' => 'empty', 'sources' => [], 'requested_source_count' => 0];
+        }
+
+        // The list is built only from normalized positive integer source IDs.
+        // A fixed-size batch limit keeps the SQL placeholder count bounded.
+        $placeholders = implode(',', array_fill(0, count($source_ids), '%d'));
+        // Start from the source registry and LEFT JOIN origins. A persisted source
+        // with no origin row must remain visible as an unknown-capability source;
+        // an INNER JOIN would silently omit it from the reconciliation inventory.
+        $inventory_sql = "SELECT s.id AS source_id, s.source_key, s.display_name,
+                    s.adapter_key AS source_adapter_key, s.granularity AS source_granularity,
+                    o.origin_key, o.adapter_key, o.capabilities,
+                    o.detection_status
+             FROM {$this->view_sources_table} AS s
+             LEFT JOIN {$this->view_source_origins_table} AS o ON o.source_id = s.id
+             WHERE s.id IN ({$placeholders})
+             ORDER BY s.id ASC, o.origin_key ASC";
+        // prepare() accepts an argument array as its second parameter. This keeps
+        // the dynamically sized placeholder list paired with its normalized IDs.
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+        $rows = statpl_db_get_results(statpl_db_prepare($inventory_sql, $source_ids), ARRAY_A);
+        if (!empty($wpdb->last_error) || !is_array($rows)) {
+            return [
+                'status' => 'query_failed',
+                'sources' => [],
+                'requested_source_count' => count($source_ids),
+                'error' => (string) $wpdb->last_error,
+            ];
+        }
+
+        $profiles = [];
+        foreach ($rows as $row) {
+            $id = absint($row['source_id'] ?? 0);
+            if (!$id) { continue; }
+            $profiles[$id] = $profiles[$id] ?? [
+                'source_id' => $id,
+                'source_key' => sanitize_key((string) ($row['source_key'] ?? '')),
+                'display_name' => sanitize_text_field((string) ($row['display_name'] ?? '')),
+                'source_adapter_key' => sanitize_key((string) ($row['source_adapter_key'] ?? '')),
+                'source_granularity' => sanitize_key((string) ($row['source_granularity'] ?? 'unknown')),
+                'origin_profile_status' => 'available',
+                'origins' => [],
+            ];
+
+            // A NULL origin row is meaningful: the source exists, but no declared
+            // origin capabilities are available. Do not infer them from its name.
+            if ($row['origin_key'] === null || $row['origin_key'] === '') {
+                $profiles[$id]['origin_profile_status'] = 'no_origin_declarations';
+                continue;
+            }
+
+            $declared = json_decode((string) ($row['capabilities'] ?? ''), true);
+            if (!is_array($declared)) { $declared = []; }
+
+            $granularity = sanitize_key((string) ($declared['granularity'] ?? 'unknown'));
+            $precision = sanitize_key((string) ($declared['timestamp_precision'] ?? 'unknown'));
+            $storage_granularity = sanitize_key((string) ($declared['source_storage_granularity'] ?? 'unknown'));
+            $profiles[$id]['origins'][] = [
+                'origin_key' => sanitize_key((string) ($row['origin_key'] ?? '')),
+                'adapter_key' => sanitize_key((string) ($row['adapter_key'] ?? '')),
+                'detection_status' => sanitize_key((string) ($row['detection_status'] ?? 'unknown')),
+                'granularity' => $granularity,
+                'timestamp_precision' => $precision,
+                'source_storage_granularity' => $storage_granularity,
+                'product_id_direct' => array_key_exists('product_id_direct', $declared) ? (bool) $declared['product_id_direct'] : null,
+                'target_requires_product_resolution' => array_key_exists('target_requires_product_resolution', $declared) ? (bool) $declared['target_requires_product_resolution'] : null,
+                'stable_event_identity_declared' => array_key_exists('stable_event_identity', $declared) ? (bool) $declared['stable_event_identity'] : null,
+                'bot_filtered' => array_key_exists('bot_filtered', $declared) ? (bool) $declared['bot_filtered'] : null,
+                'immutable_past_days' => array_key_exists('immutable_past_days', $declared) ? (bool) $declared['immutable_past_days'] : null,
+                'capability_comparability' => [
+                    'event_level' => $granularity === 'event',
+                    'second_precision' => $precision === 'seconds',
+                    'direct_product_mapping' => !empty($declared['product_id_direct']),
+                    'aggregate_only_or_unknown' => in_array($granularity, ['daily_aggregate', 'hourly_aggregate', 'unknown'], true),
+                ],
+            ];
+        }
+
+        // Preserve requested IDs that have no matching source-registry row as
+        // explicit unresolved entries instead of silently shrinking the scope.
+        foreach ($source_ids as $requested_id) {
+            if (!isset($profiles[$requested_id])) {
+                $profiles[$requested_id] = [
+                    'source_id' => $requested_id,
+                    'source_key' => '',
+                    'display_name' => '',
+                    'source_adapter_key' => '',
+                    'source_granularity' => 'unknown',
+                    'origin_profile_status' => 'source_registry_row_missing',
+                    'origins' => [],
+                ];
+            }
+        }
+        ksort($profiles, SORT_NUMERIC);
+
+        $resolved_count = 0;
+        $without_origin_count = 0;
+        foreach ($profiles as $profile) {
+            if (($profile['origin_profile_status'] ?? '') === 'source_registry_row_missing') {
+                continue;
+            }
+            $resolved_count++;
+            if (($profile['origin_profile_status'] ?? '') === 'no_origin_declarations') {
+                $without_origin_count++;
+            }
+        }
+        $status = $resolved_count < count($source_ids)
+            ? 'partial'
+            : ($without_origin_count > 0 ? 'partial' : 'available');
+
+        return [
+            'status' => $status,
+            'sources' => array_values($profiles),
+            'requested_source_count' => count($source_ids),
+            'resolved_source_count' => $resolved_count,
+            'sources_without_origin_declarations' => $without_origin_count,
+        ];
+    }
+
+    private function build_generic_cross_source_overlap_assessment($product_id, $source_id, $adapter_key, $record_type, $period_start, $period_end, $candidates, $truncated = false, $observed_views = 0) {
+        $product_id = absint($product_id);
+        $record_type = sanitize_key((string) $record_type);
+        $period_start = $period_start !== null ? (string) $period_start : '';
+        $period_end = $period_end !== null ? (string) $period_end : '';
+        $sources = [];
+        $same_instant_event_candidates = 0;
+        $same_bounds_aggregate_candidates = 0;
+        $intersecting_aggregate_candidates = 0;
+        $different_type_candidates = 0;
+
+        foreach ((array) $candidates as $candidate) {
+            if (!is_array($candidate) || (int) ($candidate['product_id'] ?? 0) !== $product_id) {
+                continue;
+            }
+            $candidate_source_id = absint($candidate['source_id'] ?? 0);
+            if (!$candidate_source_id) {
+                continue;
+            }
+            $candidate_type = sanitize_key((string) ($candidate['record_type'] ?? ''));
+            $candidate_start = isset($candidate['period_start']) ? (string) $candidate['period_start'] : '';
+            $candidate_end = isset($candidate['period_end']) ? (string) $candidate['period_end'] : '';
+            $same_bounds = $period_start !== '' && $period_end !== ''
+                && $candidate_start === $period_start && $candidate_end === $period_end;
+            $intersects = $period_start !== '' && $period_end !== ''
+                && $candidate_start !== '' && $candidate_end !== ''
+                && $candidate_start <= $period_end && $candidate_end >= $period_start;
+
+            if (!isset($sources[$candidate_source_id])) {
+                $sources[$candidate_source_id] = [
+                    'source_id' => $candidate_source_id,
+                    'source_key' => isset($candidate['candidate_source_key']) ? (string) $candidate['candidate_source_key'] : null,
+                    'adapter_key' => isset($candidate['candidate_adapter_key']) ? (string) $candidate['candidate_adapter_key'] : null,
+                    'record_types' => [],
+                    'candidate_records' => 0,
+                ];
+            }
+            $sources[$candidate_source_id]['candidate_records']++;
+            if ($candidate_type !== '') {
+                $sources[$candidate_source_id]['record_types'][$candidate_type] = true;
+            }
+
+            if ($candidate_type !== $record_type) {
+                $different_type_candidates++;
+            }
+            if ($record_type === 'event' && $candidate_type === 'event' && $same_bounds) {
+                $same_instant_event_candidates++;
+            } elseif ($record_type === 'aggregate' && $candidate_type === 'aggregate' && $same_bounds) {
+                $same_bounds_aggregate_candidates++;
+            } elseif ($intersects && ($record_type === 'aggregate' || $candidate_type === 'aggregate')) {
+                $intersecting_aggregate_candidates++;
+            }
+        }
+
+        foreach ($sources as &$source) {
+            $source['record_types'] = array_keys($source['record_types']);
+            sort($source['record_types'], SORT_STRING);
+        }
+        unset($source);
+        ksort($sources, SORT_NUMERIC);
+
+        // Identical naive datetime labels cannot establish a shared temporal
+        // bucket without persisted source-timezone provenance; no count range is inferred.
+        $same_bucket_range = [
+            'status' => 'unavailable',
+            'reason' => 'timezone_basis_not_persisted',
+            'minimum_unique_views' => null,
+            'maximum_unique_views' => null,
+            'minimum_possible_duplicate_views' => null,
+            'maximum_possible_duplicate_views' => null,
+            'source_contributions' => [],
+        ];
+
+        $capability_source_ids = array_merge([absint($source_id)], array_keys($sources));
+        $capability_profiles = $this->get_generic_source_capability_profiles($capability_source_ids);
+
+        return [
+            'version' => '0.2.0',
+            'scope' => 'same_product_different_sources',
+            'incoming_source' => [
+                'source_id' => absint($source_id),
+                'adapter_key' => sanitize_key((string) $adapter_key),
+                'record_type' => $record_type,
+            ],
+            'candidate_sources' => array_values($sources),
+            'source_capability_profiles' => $capability_profiles,
+            'reliability_policy' => 'declared_capabilities_only_no_numeric_score_or_inferred_trust_rank',
+            'candidate_source_count' => count($sources),
+            'candidate_record_count' => array_sum(array_column(array_values($sources), 'candidate_records')),
+            'same_instant_event_candidates' => $same_instant_event_candidates,
+            'same_bounds_aggregate_candidates' => $same_bounds_aggregate_candidates,
+            'intersecting_aggregate_candidates' => $intersecting_aggregate_candidates,
+            'period_comparison_semantics' => 'raw_datetime_string_representation_only_timezone_unverified',
+            'different_record_type_candidates' => $different_type_candidates,
+            'candidate_set_truncated' => (bool) $truncated,
+            'identical_bucket_count_range' => $same_bucket_range,
+            'identity_confidence' => 'unproven_without_shared_event_identity',
+            'temporal_basis_status' => 'timezone_provenance_not_persisted',
+            'absolute_temporal_comparison_performed' => false,
+            'counting_decision' => 'preserve_contribution_pending_global_reconciliation',
+            'policy' => 'Stored datetime strings and identical period bounds are representation-level signals only because source timezone provenance is not persisted; no absolute-time overlap or unique-view range is asserted and no contribution is suppressed by this assessment.',
+        ];
+    }
+
+    /**
+     * Build a bounded product-wide inventory across every persisted generic source.
+     * This is a descriptive synthesis of recorded contributions, not a unique-view
+     * estimate: source totals are never added, ranked, or suppressed here.
+     */
+    private function build_generic_product_source_synthesis($product_id) {
+        global $wpdb;
+
+        $product_id = absint($product_id);
+        if (!$product_id) {
+            return ['status' => 'unavailable', 'reason' => 'invalid_product_id', 'sources' => []];
+        }
+
+        // Keep the source-ID inventory independent of the bounded record-group
+        // result so capability profiles cover every source, even when the
+        // descriptive record inventory reaches its output limit.
+        $source_id_rows = statpl_db_get_col(statpl_db_prepare(
+            "SELECT DISTINCT source_id
+             FROM {$this->view_source_events_table}
+             WHERE product_id = %d
+             ORDER BY source_id ASC",
+            $product_id
+        ));
+        if (!empty($wpdb->last_error) || !is_array($source_id_rows)) {
+            return ['status' => 'query_failed', 'reason' => 'product_source_id_inventory_query_failed', 'sources' => []];
+        }
+        $all_source_ids = array_values(array_unique(array_filter(array_map('absint', $source_id_rows))));
+
+        $rows = statpl_db_get_results(statpl_db_prepare(
+            "SELECT e.source_id, s.source_key, s.display_name, e.record_type,
+                    COUNT(*) AS record_count, SUM(e.observed_views) AS observed_views,
+                    SUM(e.applied_views) AS applied_views,
+                    MIN(e.period_start) AS first_period_start,
+                    MAX(e.period_end) AS last_period_end
+             FROM {$this->view_source_events_table} AS e
+             LEFT JOIN {$this->view_sources_table} AS s ON s.id = e.source_id
+             WHERE e.product_id = %d
+             GROUP BY e.source_id, s.source_key, s.display_name, e.record_type
+             ORDER BY e.source_id ASC, e.record_type ASC
+             LIMIT 101",
+            $product_id
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error) || !is_array($rows)) {
+            return ['status' => 'query_failed', 'reason' => 'product_source_inventory_query_failed', 'sources' => []];
+        }
+        $truncated = count($rows) > 100;
+        if ($truncated) {
+            $rows = array_slice($rows, 0, 100);
+        }
+        $sources = [];
+        foreach ($rows as $row) {
+            $source_id = absint($row['source_id'] ?? 0);
+            if (!$source_id) { continue; }
+            if (!isset($sources[$source_id])) {
+                $sources[$source_id] = [
+                    'source_id' => $source_id,
+                    'source_key' => sanitize_key((string) ($row['source_key'] ?? '')),
+                    'display_name' => sanitize_text_field((string) ($row['display_name'] ?? '')),
+                    'record_types' => [],
+                ];
+            }
+            $sources[$source_id]['record_types'][] = [
+                'record_type' => sanitize_key((string) ($row['record_type'] ?? 'unknown')),
+                'record_count' => max(0, (int) ($row['record_count'] ?? 0)),
+                'observed_views' => max(0, (int) ($row['observed_views'] ?? 0)),
+                'applied_views' => max(0, (int) ($row['applied_views'] ?? 0)),
+                'first_period_start' => $row['first_period_start'] !== null ? (string) $row['first_period_start'] : null,
+                'last_period_end' => $row['last_period_end'] !== null ? (string) $row['last_period_end'] : null,
+            ];
+        }
+        ksort($sources, SORT_NUMERIC);
+
+        $capability_profiles = $this->get_generic_source_capability_profiles($all_source_ids);
+        $capability_profiles_by_source = [];
+        // A partial capability lookup still contains useful, successfully
+        // resolved profiles plus explicit unresolved entries. Retain every
+        // returned profile; the status separately communicates incompleteness.
+        if (in_array(($capability_profiles['status'] ?? ''), ['available', 'partial'], true)) {
+            foreach ((array) ($capability_profiles['sources'] ?? []) as $profile) {
+                $profile_source_id = absint($profile['source_id'] ?? 0);
+                if ($profile_source_id) {
+                    $capability_profiles_by_source[$profile_source_id] = $profile;
+                }
+            }
+        }
+
+        return [
+            'status' => 'available',
+            'scope' => 'all_persisted_generic_sources_for_product',
+            'sources' => array_values($sources),
+            'source_ids_in_scope' => $all_source_ids,
+            'source_count_in_scope' => count($all_source_ids),
+            'source_capability_profiles' => array_values($capability_profiles_by_source),
+            'capability_profile_status' => sanitize_key((string) ($capability_profiles['status'] ?? 'unknown')),
+            'capability_profile_source_count' => count($capability_profiles_by_source),
+            'source_record_groups_truncated' => $truncated,
+            'unique_view_total' => null,
+            'counting_decision' => 'no_cross_source_sum_or_suppression',
+            'policy' => 'Observed and applied contributions are reported separately by source and record type; declared capabilities are attached for every source in scope where available, without numeric reliability ranking or a deduplicated product-view total.',
+        ];
+    }
+
+    /**
+     * Combine the independently collected reconciliation evidence into one
+     * product-level audit summary. This is classification only: it never
+     * estimates unique views, changes applied_views, or authorizes suppression.
+     */
+    /**
+     * Classify the completeness and ambiguity of the retained cross-source candidate set.
+     * Candidate ordering identifies an audit primary only; it never establishes identity.
+     */
+    private function build_generic_candidate_set_assessment($candidates, $candidates_truncated = false, $observed_count = null) {
+        $candidates = is_array($candidates) ? $candidates : [];
+        $by_id = [];
+        $source_ids = [];
+        foreach ($candidates as $candidate) {
+            if (!is_array($candidate)) {
+                continue;
+            }
+            $event_id = isset($candidate['id']) ? (int) $candidate['id'] : 0;
+            $source_id = isset($candidate['source_id']) ? (int) $candidate['source_id'] : 0;
+            if ($event_id > 0) {
+                $by_id[$event_id] = true;
+            }
+            if ($source_id > 0) {
+                $source_ids[$source_id] = true;
+            }
+        }
+        $candidate_count = count($by_id);
+        $source_count = count($source_ids);
+        $observed_count = $observed_count === null ? $candidate_count : max($candidate_count, (int) $observed_count);
+        $truncated = (bool) $candidates_truncated;
+
+        if ($candidate_count > 1 || $truncated || $observed_count > $candidate_count) {
+            $classification = 'multiple_or_truncated_candidates_require_review';
+        } elseif ($candidate_count === 1) {
+            $classification = 'single_candidate_requires_review';
+        } else {
+            $classification = 'no_candidate_available';
+        }
+
+        return [
+            'classification' => $classification,
+            'candidate_count_retained' => $candidate_count,
+            'candidate_event_ids' => array_map('intval', array_keys($by_id)),
+            'candidate_source_ids_by_event_id' => array_intersect_key(array_reduce($candidates, static function ($carry, $candidate) {
+                if (is_array($candidate) && !empty($candidate['id']) && !empty($candidate['source_id'])) {
+                    $carry[(int) $candidate['id']] = (int) $candidate['source_id'];
+                }
+                return $carry;
+            }, []), $by_id),
+            'candidate_count_observed' => $observed_count,
+            'candidate_source_count_retained' => $source_count,
+            'multiple_candidate_ambiguity' => $candidate_count > 1 || $observed_count > 1,
+            'multiple_source_ambiguity' => $source_count > 1,
+            'candidate_set_truncated' => $truncated,
+            'candidate_count_is_lower_bound' => $truncated,
+            'primary_candidate_is_identity_proof' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'All retained candidates remain evidence. Primary ordering is for audit navigation only and does not resolve identity or authorize count suppression.',
+        ];
+    }
+
+    /**
+     * Describe conflicting or heterogeneous dimensions across retained candidates.
+     * Differences are classified as evidence only; this method never resolves identity
+     * or changes the contribution applied to product totals.
+     */
+    /**
+     * Validate the integrity of the per-candidate audit records. Missing or duplicate
+     * identifiers and malformed classifications are retained as audit errors; this
+     * method never infers identity or authorizes suppression.
+     */
+    private function build_generic_candidate_record_integrity_assessment($candidate_details, $expected_unique_candidate_count) {
+        $candidate_details = is_array($candidate_details) ? $candidate_details : [];
+        $expected_unique_candidate_count = max(0, (int) $expected_unique_candidate_count);
+        $errors = [];
+        $seen_ids = [];
+        $missing_id_count = 0;
+        $duplicate_id_count = 0;
+        $invalid_classification_count = 0;
+        $invalid_dimension_check_count = 0;
+        $allowed_classifications = [
+            'fingerprint_dimension_mismatch',
+            'temporal_candidate_different_record_shape',
+            'candidate_dimensions_match_without_identity_proof',
+            'insufficient_candidate_dimensions',
+        ];
+        $required_dimensions = ['product_id', 'record_type', 'observed_views', 'period_start', 'period_end'];
+
+        foreach ($candidate_details as $detail) {
+            if (!is_array($detail)) {
+                $missing_id_count++;
+                $invalid_classification_count++;
+                $invalid_dimension_check_count++;
+                continue;
+            }
+            $candidate_id = absint($detail['candidate_event_id'] ?? 0);
+            if (!$candidate_id) {
+                $missing_id_count++;
+            } elseif (isset($seen_ids[$candidate_id])) {
+                $duplicate_id_count++;
+            } else {
+                $seen_ids[$candidate_id] = true;
+            }
+            if (!in_array($detail['classification'] ?? null, $allowed_classifications, true)) {
+                $invalid_classification_count++;
+            }
+            $checks = $detail['dimension_checks'] ?? null;
+            $checks_valid = is_array($checks);
+            if ($checks_valid) {
+                foreach ($required_dimensions as $dimension) {
+                    if (!array_key_exists($dimension, $checks)
+                        || !in_array($checks[$dimension], [true, false, null], true)) {
+                        $checks_valid = false;
+                        break;
+                    }
+                }
+            }
+            if (!$checks_valid) {
+                $invalid_dimension_check_count++;
+            }
+        }
+
+        $detail_count = count($candidate_details);
+        $unique_id_count = count($seen_ids);
+        if ($missing_id_count > 0) {
+            $errors[] = 'candidate_audit_record_missing_valid_event_id';
+        }
+        if ($duplicate_id_count > 0) {
+            $errors[] = 'candidate_audit_records_contain_duplicate_event_ids';
+        }
+        if ($invalid_classification_count > 0) {
+            $errors[] = 'candidate_audit_record_has_invalid_classification';
+        }
+        if ($invalid_dimension_check_count > 0) {
+            $errors[] = 'candidate_audit_record_has_invalid_dimension_checks';
+        }
+        if ($detail_count !== $expected_unique_candidate_count || $unique_id_count !== $expected_unique_candidate_count) {
+            $errors[] = 'candidate_audit_record_count_does_not_match_unique_candidate_inventory';
+        }
+
+        return [
+            'status' => $errors ? 'candidate_records_require_review' : 'candidate_records_valid',
+            'consistent' => !$errors,
+            'errors' => array_values(array_unique($errors)),
+            'candidate_detail_count' => $detail_count,
+            'unique_valid_candidate_id_count' => $unique_id_count,
+            'expected_unique_candidate_count' => $expected_unique_candidate_count,
+            'missing_id_count' => $missing_id_count,
+            'duplicate_id_count' => $duplicate_id_count,
+            'invalid_classification_count' => $invalid_classification_count,
+            'invalid_dimension_check_count' => $invalid_dimension_check_count,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Record validation is audit-only. Invalid records remain visible for review and cannot establish identity or authorize suppression.',
+        ];
+    }
+
+    private function build_generic_candidate_conflict_assessment($incoming, $candidates) {
+        $incoming = is_array($incoming) ? $incoming : [];
+        $candidates = is_array($candidates) ? $candidates : [];
+        $counts = [
+            'fingerprint_dimension_mismatch' => 0,
+            'temporal_candidate_different_record_shape' => 0,
+            'candidate_dimensions_match_without_identity_proof' => 0,
+            'insufficient_candidate_dimensions' => 0,
+        ];
+        $candidate_ids = [];
+        $dimension_signatures = [];
+        $details = [];
+        foreach ($candidates as $candidate) {
+            if (!is_array($candidate)) {
+                continue;
+            }
+            $candidate_id = absint($candidate['id'] ?? 0);
+            if ($candidate_id) {
+                $candidate_ids[$candidate_id] = true;
+            }
+            $discovered_by = array_values((array) ($candidate['_discovered_by'] ?? []));
+            $has_fingerprint_signal = in_array('fingerprint', $discovered_by, true);
+            $has_temporal_signal = in_array('temporal', $discovered_by, true);
+            $checks = [
+                'product_id' => isset($incoming['product_id'], $candidate['product_id'])
+                    ? (int) $incoming['product_id'] === (int) $candidate['product_id'] : null,
+                'record_type' => isset($incoming['record_type'], $candidate['record_type'])
+                    ? (string) $incoming['record_type'] === (string) $candidate['record_type'] : null,
+                'observed_views' => isset($incoming['observed_views'], $candidate['observed_views'])
+                    ? (int) $incoming['observed_views'] === (int) $candidate['observed_views'] : null,
+                'period_start' => !empty($incoming['period_start']) && !empty($candidate['period_start'])
+                    ? (string) $incoming['period_start'] === (string) $candidate['period_start'] : null,
+                'period_end' => !empty($incoming['period_end']) && !empty($candidate['period_end'])
+                    ? (string) $incoming['period_end'] === (string) $candidate['period_end'] : null,
+            ];
+            $known_checks = array_filter($checks, static function ($value) { return $value !== null; });
+            $all_known_dimensions_match = count($known_checks) === count($checks)
+                && !in_array(false, $known_checks, true);
+            $has_dimension_difference = in_array(false, $known_checks, true);
+            if ($has_fingerprint_signal && $has_dimension_difference) {
+                $classification = 'fingerprint_dimension_mismatch';
+            } elseif ($has_temporal_signal && (
+                $checks['record_type'] === false || $checks['observed_views'] === false
+            )) {
+                $classification = 'temporal_candidate_different_record_shape';
+            } elseif ($all_known_dimensions_match) {
+                $classification = 'candidate_dimensions_match_without_identity_proof';
+            } else {
+                $classification = 'insufficient_candidate_dimensions';
+            }
+            $counts[$classification]++;
+            $signature = implode('|', [
+                (string) ($candidate['product_id'] ?? 'unknown'),
+                (string) ($candidate['record_type'] ?? 'unknown'),
+                (string) ($candidate['observed_views'] ?? 'unknown'),
+                (string) ($candidate['period_start'] ?? ''),
+                (string) ($candidate['period_end'] ?? ''),
+            ]);
+            $dimension_signatures[$signature] = true;
+            $details[] = [
+                'candidate_event_id' => $candidate_id ?: null,
+                'candidate_source_id' => !empty($candidate['source_id']) ? (int) $candidate['source_id'] : null,
+                'discovered_by' => $discovered_by,
+                'classification' => $classification,
+                'dimension_checks' => $checks,
+                'identity_proven' => false,
+                'automatic_suppression_authorized' => false,
+            ];
+        }
+        $candidate_count = count($candidate_ids);
+        $record_integrity = $this->build_generic_candidate_record_integrity_assessment($details, $candidate_count);
+        $heterogeneous = count($dimension_signatures) > 1;
+        $has_conflict = $counts['fingerprint_dimension_mismatch'] > 0
+            || $counts['temporal_candidate_different_record_shape'] > 0;
+        return [
+            'status' => $candidate_count ? 'available' : 'no_candidates',
+            'candidate_count' => $candidate_count,
+            'candidate_dimension_signature_count' => count($dimension_signatures),
+            'candidate_set_is_heterogeneous' => $heterogeneous,
+            'conflicting_evidence_present' => $has_conflict,
+            'classification_counts' => $counts,
+            'candidate_record_integrity' => $record_integrity,
+            'candidates' => $details,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Dimension differences and heterogeneous candidates are retained as review evidence only; they do not establish identity, select a winning candidate, or authorize count suppression.',
+        ];
+    }
+
+    /**
+     * Make an explicit audit decision from candidate support and contradiction evidence.
+     * Absence of candidates is not evidence that sources do not overlap. A clean dimensional
+     * comparison is not identity proof, and truncation always limits the conclusion.
+     */
+    private function build_generic_candidate_evidence_decision($conflict_assessment, $candidate_set_assessment = [], $candidate_search_truncated = false) {
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $counts = (array) ($conflict_assessment['classification_counts'] ?? []);
+        $fingerprint_conflicts = max(0, (int) ($counts['fingerprint_dimension_mismatch'] ?? 0));
+        $temporal_shape_conflicts = max(0, (int) ($counts['temporal_candidate_different_record_shape'] ?? 0));
+        $matching_dimensions = max(0, (int) ($counts['candidate_dimensions_match_without_identity_proof'] ?? 0));
+        $insufficient_dimensions = max(0, (int) ($counts['insufficient_candidate_dimensions'] ?? 0));
+        $candidate_count = max(0, (int) ($conflict_assessment['candidate_count'] ?? 0));
+        $truncated = (bool) $candidate_search_truncated
+            || !empty($candidate_set_assessment['candidate_set_truncated'])
+            || !empty($candidate_set_assessment['candidate_count_is_lower_bound']);
+
+        $support = [];
+        $contradictions = [];
+        $limitations = [];
+        if ($matching_dimensions > 0) {
+            $support[] = 'candidate_dimensions_match_but_do_not_prove_shared_identity';
+        }
+        if ($fingerprint_conflicts > 0) {
+            $contradictions[] = 'fingerprint_discovery_signal_has_dimension_mismatches';
+        }
+        if ($temporal_shape_conflicts > 0) {
+            $contradictions[] = 'temporal_candidates_have_different_record_shapes';
+        }
+        if ($insufficient_dimensions > 0) {
+            $limitations[] = 'candidate_dimensions_are_incomplete';
+        }
+        if ($truncated) {
+            $limitations[] = 'candidate_search_truncated_conclusion_is_incomplete';
+        }
+
+        if ($candidate_count === 0) {
+            $classification = $truncated
+                ? 'candidate_search_incomplete_no_retained_candidate_no_overlap_conclusion'
+                : 'no_candidate_found_within_search_bounds_overlap_remains_unknown';
+        } elseif ($fingerprint_conflicts > 0 || $temporal_shape_conflicts > 0) {
+            $classification = ($matching_dimensions > 0)
+                ? 'supporting_and_contradictory_evidence_require_review'
+                : 'contradictory_candidate_evidence_requires_review';
+        } elseif ($matching_dimensions > 0) {
+            $classification = 'supportive_dimensions_without_identity_proof';
+        } else {
+            $classification = 'insufficient_candidate_evidence_requires_review';
+        }
+        if ($truncated && $candidate_count > 0) {
+            $limitations[] = 'retained_candidates_are_not_the_complete_observed_set';
+        }
+
+        return [
+            'classification' => $classification,
+            'supporting_evidence' => array_values(array_unique($support)),
+            'contradictory_evidence' => array_values(array_unique($contradictions)),
+            'limitations' => array_values(array_unique($limitations)),
+            'supporting_candidate_count' => $matching_dimensions,
+            'fingerprint_dimension_conflict_count' => $fingerprint_conflicts,
+            'temporal_record_shape_conflict_count' => $temporal_shape_conflicts,
+            'insufficient_dimension_candidate_count' => $insufficient_dimensions,
+            'candidate_count' => $candidate_count,
+            'candidate_search_truncated' => $truncated,
+            'absence_of_candidates_proves_no_overlap' => false,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Support, contradiction, and missing evidence are reported separately. No candidate is not proof of no overlap; matching dimensions are not proof of identity; no evidence classification changes applied_views or authorizes suppression.',
+        ];
+    }
+
+    /**
+     * Validate that candidate inventory, conflict assessment, and evidence decision
+     * describe the same retained evidence and preserve the non-suppression policy.
+     * This is an audit integrity check only; it never changes reconciliation outcomes.
+     */
+    private function build_generic_candidate_audit_consistency($candidate_set_assessment, $conflict_assessment, $evidence_decision) {
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $evidence_decision = is_array($evidence_decision) ? $evidence_decision : [];
+        $errors = [];
+        $candidate_count = max(0, (int) ($conflict_assessment['candidate_count'] ?? 0));
+        $retained_count = max(0, (int) ($candidate_set_assessment['candidate_count_retained'] ?? 0));
+        $decision_count = max(0, (int) ($evidence_decision['candidate_count'] ?? 0));
+        $counts = (array) ($conflict_assessment['classification_counts'] ?? []);
+        $record_integrity = $conflict_assessment['candidate_record_integrity'] ?? null;
+        $record_integrity = is_array($record_integrity) ? $record_integrity : [];
+        $classified_count = 0;
+        foreach ([
+            'fingerprint_dimension_mismatch',
+            'temporal_candidate_different_record_shape',
+            'candidate_dimensions_match_without_identity_proof',
+            'insufficient_candidate_dimensions',
+        ] as $key) {
+            $classified_count += max(0, (int) ($counts[$key] ?? 0));
+        }
+        if ($candidate_count !== $retained_count || $candidate_count !== $decision_count) {
+            $errors[] = 'candidate_counts_disagree_across_audit_layers';
+        }
+        if (empty($conflict_assessment['candidate_record_integrity']) || !is_array($conflict_assessment['candidate_record_integrity'])) {
+            $errors[] = 'candidate_record_integrity_assessment_missing_from_conflict_audit';
+        } elseif (empty($record_integrity['consistent'])) {
+            $errors[] = 'candidate_record_integrity_validation_failed';
+        }
+        if (isset($record_integrity['expected_unique_candidate_count'])
+            && (int) $record_integrity['expected_unique_candidate_count'] !== $candidate_count) {
+            $errors[] = 'candidate_record_integrity_expected_count_disagrees_with_conflict_inventory';
+        }
+        if ($classified_count > $candidate_count) {
+            $errors[] = 'candidate_classification_count_exceeds_candidate_inventory';
+        } elseif ($classified_count < $candidate_count) {
+            $errors[] = 'candidate_classification_coverage_incomplete';
+        }
+        $classification_coverage_complete = $classified_count === $candidate_count;
+        foreach ([
+            'supporting_candidate_count' => 'candidate_dimensions_match_without_identity_proof',
+            'fingerprint_dimension_conflict_count' => 'fingerprint_dimension_mismatch',
+            'temporal_record_shape_conflict_count' => 'temporal_candidate_different_record_shape',
+            'insufficient_dimension_candidate_count' => 'insufficient_candidate_dimensions',
+        ] as $decision_key => $conflict_key) {
+            if (max(0, (int) ($evidence_decision[$decision_key] ?? 0)) !== max(0, (int) ($counts[$conflict_key] ?? 0))) {
+                $errors[] = 'evidence_decision_count_mismatch_' . $decision_key;
+            }
+        }
+        $set_truncated = !empty($candidate_set_assessment['candidate_set_truncated']);
+        $decision_truncated = !empty($evidence_decision['candidate_search_truncated']);
+        if ($set_truncated && !$decision_truncated) {
+            $errors[] = 'candidate_truncation_not_propagated_to_evidence_decision';
+        }
+        if (!empty($conflict_assessment['identity_proven']) || !empty($evidence_decision['identity_proven'])) {
+            $errors[] = 'candidate_evidence_layer_claims_identity_proof';
+        }
+        if (!empty($candidate_set_assessment['automatic_suppression_authorized'])
+            || !empty($conflict_assessment['automatic_suppression_authorized'])
+            || !empty($evidence_decision['automatic_suppression_authorized'])) {
+            $errors[] = 'candidate_evidence_layer_authorizes_automatic_suppression';
+        }
+        if ($candidate_count === 0 && !empty($evidence_decision['absence_of_candidates_proves_no_overlap'])) {
+            $errors[] = 'absence_of_candidates_misrepresented_as_no_overlap_proof';
+        }
+        return [
+            'status' => $errors ? 'inconsistent_audit_evidence_requires_review' : 'candidate_audit_layers_consistent',
+            'consistent' => !$errors,
+            'errors' => array_values(array_unique($errors)),
+            'candidate_count_conflict_assessment' => $candidate_count,
+            'candidate_count_inventory' => $retained_count,
+            'candidate_count_evidence_decision' => $decision_count,
+            'classified_candidate_count' => $classified_count,
+            'unclassified_candidate_count' => max(0, $candidate_count - $classified_count),
+            'classification_coverage_complete' => $classification_coverage_complete,
+            'candidate_record_integrity' => [
+                'present' => !empty($conflict_assessment['candidate_record_integrity']) && is_array($conflict_assessment['candidate_record_integrity']),
+                'consistent' => !empty($record_integrity['consistent']),
+                'errors' => array_values((array) ($record_integrity['errors'] ?? [])),
+                'candidate_detail_count' => max(0, (int) ($record_integrity['candidate_detail_count'] ?? 0)),
+                'unique_valid_candidate_id_count' => max(0, (int) ($record_integrity['unique_valid_candidate_id_count'] ?? 0)),
+                'expected_unique_candidate_count' => max(0, (int) ($record_integrity['expected_unique_candidate_count'] ?? 0)),
+            ],
+            'candidate_search_truncated' => $decision_truncated,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Consistency validation is audit-only. A failed validation requires review and never changes applied_views or authorizes count suppression.',
+        ];
+    }
+
+    /**
+     * Compare the event/source references retained by candidate inventory and
+     * per-candidate conflict records. Reference mismatches require review only.
+     */
+    private function build_generic_candidate_reference_consistency($candidate_set_assessment, $conflict_assessment) {
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $inventory_ids = array_values(array_unique(array_filter(array_map('absint', (array) ($candidate_set_assessment['candidate_event_ids'] ?? [])))));
+        $detail_ids = [];
+        $detail_sources = [];
+        $duplicate_detail_ids = [];
+        foreach ((array) ($conflict_assessment['candidates'] ?? []) as $detail) {
+            if (!is_array($detail) || empty($detail['candidate_event_id'])) {
+                continue;
+            }
+            $id = absint($detail['candidate_event_id']);
+            if (isset($detail_ids[$id])) {
+                $duplicate_detail_ids[] = $id;
+            }
+            $detail_ids[$id] = true;
+            $detail_sources[$id] = isset($detail['candidate_source_id']) ? absint($detail['candidate_source_id']) : 0;
+        }
+        $inventory_set = array_fill_keys($inventory_ids, true);
+        $detail_set = $detail_ids;
+        $missing_details = array_values(array_diff($inventory_ids, array_keys($detail_set)));
+        $unexpected_details = array_values(array_diff(array_keys($detail_set), $inventory_ids));
+        $source_mismatches = [];
+        $inventory_sources = (array) ($candidate_set_assessment['candidate_source_ids_by_event_id'] ?? []);
+        foreach ($inventory_sources as $event_id => $source_id) {
+            $event_id = absint($event_id);
+            $source_id = absint($source_id);
+            if (isset($detail_sources[$event_id]) && $detail_sources[$event_id] !== $source_id) {
+                $source_mismatches[] = $event_id;
+            }
+        }
+        $errors = [];
+        if ($missing_details) { $errors[] = 'candidate_inventory_event_missing_conflict_detail'; }
+        if ($unexpected_details) { $errors[] = 'conflict_detail_event_missing_from_candidate_inventory'; }
+        if ($duplicate_detail_ids) { $errors[] = 'conflict_details_contain_duplicate_event_references'; }
+        if ($source_mismatches) { $errors[] = 'candidate_source_reference_mismatch'; }
+        return [
+            'status' => $errors ? 'candidate_references_require_review' : 'candidate_references_consistent',
+            'consistent' => !$errors,
+            'errors' => $errors,
+            'inventory_event_ids' => $inventory_ids,
+            'conflict_detail_event_ids' => array_map('intval', array_keys($detail_set)),
+            'missing_conflict_detail_event_ids' => $missing_details,
+            'unexpected_conflict_detail_event_ids' => $unexpected_details,
+            'duplicate_conflict_detail_event_ids' => array_values(array_unique($duplicate_detail_ids)),
+            'source_reference_mismatch_event_ids' => array_values(array_unique($source_mismatches)),
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Reference consistency validates audit traceability only; it does not establish shared event identity or authorize suppression.',
+        ];
+    }
+
+    /**
+     * Validate discovery-signal provenance for every retained candidate. Signals
+     * explain why a candidate was found; they are never treated as identity proof.
+     */
+    private function build_generic_candidate_discovery_signal_consistency($candidate_set_assessment, $conflict_assessment) {
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $inventory_ids = array_values(array_unique(array_filter(array_map('absint', (array) ($candidate_set_assessment['candidate_event_ids'] ?? [])))));
+        $allowed_signals = ['fingerprint', 'temporal'];
+        $candidate_signals = [];
+        $missing_signal_ids = [];
+        $unknown_signals = [];
+        $duplicate_signals = [];
+        $unexpected_ids = [];
+        $inventory_set = array_fill_keys($inventory_ids, true);
+        foreach ((array) ($conflict_assessment['candidates'] ?? []) as $detail) {
+            if (!is_array($detail) || empty($detail['candidate_event_id'])) {
+                continue;
+            }
+            $event_id = absint($detail['candidate_event_id']);
+            if (!isset($inventory_set[$event_id])) {
+                $unexpected_ids[] = $event_id;
+            }
+            $signals = $detail['discovered_by'] ?? null;
+            if (!is_array($signals) || !$signals) {
+                $missing_signal_ids[] = $event_id;
+                $candidate_signals[$event_id] = [];
+                continue;
+            }
+            $normalized = [];
+            foreach ($signals as $signal) {
+                if (!is_string($signal) || !in_array($signal, $allowed_signals, true)) {
+                    $unknown_signals[] = ['candidate_event_id' => $event_id, 'signal' => is_scalar($signal) ? (string) $signal : gettype($signal)];
+                    continue;
+                }
+                if (in_array($signal, $normalized, true)) {
+                    $duplicate_signals[] = ['candidate_event_id' => $event_id, 'signal' => $signal];
+                }
+                $normalized[] = $signal;
+            }
+            $candidate_signals[$event_id] = array_values(array_unique($normalized));
+        }
+        $missing_candidate_ids = array_values(array_diff($inventory_ids, array_keys($candidate_signals)));
+        $errors = [];
+        if ($missing_signal_ids) { $errors[] = 'candidate_discovery_signal_missing'; }
+        if ($missing_candidate_ids) { $errors[] = 'candidate_discovery_record_missing'; }
+        if ($unexpected_ids) { $errors[] = 'discovery_signal_candidate_outside_inventory'; }
+        if ($unknown_signals) { $errors[] = 'unknown_candidate_discovery_signal'; }
+        if ($duplicate_signals) { $errors[] = 'duplicate_candidate_discovery_signal'; }
+        return [
+            'status' => $errors ? 'candidate_discovery_signals_require_review' : 'candidate_discovery_signals_consistent',
+            'consistent' => !$errors,
+            'errors' => $errors,
+            'allowed_signal_types' => $allowed_signals,
+            'candidate_signals_by_event_id' => $candidate_signals,
+            'missing_signal_event_ids' => array_values(array_unique($missing_signal_ids)),
+            'missing_candidate_record_event_ids' => $missing_candidate_ids,
+            'unexpected_candidate_event_ids' => array_values(array_unique($unexpected_ids)),
+            'unknown_signals' => $unknown_signals,
+            'duplicate_signals' => $duplicate_signals,
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Fingerprint and temporal signals describe discovery provenance only; neither signal establishes shared event identity or authorizes suppression.',
+        ];
+    }
+
+    /**
+     * Verify that adapter evidence preserves the discovery signals recorded for
+     * each candidate. Discovery provenance remains advisory and is never identity proof.
+     */
+    private function build_generic_adapter_discovery_evidence_consistency($conflict_assessment, $adapter_overlap_evidence) {
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $adapter_overlap_evidence = is_array($adapter_overlap_evidence) ? $adapter_overlap_evidence : [];
+        $expected = [];
+        foreach ((array) ($conflict_assessment['candidates'] ?? []) as $candidate) {
+            if (!is_array($candidate) || empty($candidate['candidate_event_id'])) { continue; }
+            $id = absint($candidate['candidate_event_id']);
+            $expected[$id] = array_values(array_unique(array_filter((array) ($candidate['discovered_by'] ?? []), 'is_string')));
+        }
+        $seen = [];
+        $missing = [];
+        $unexpected = [];
+        $mismatched = [];
+        $duplicate = [];
+        $invalid = [];
+        $allowed = ['fingerprint', 'temporal'];
+        foreach ($adapter_overlap_evidence as $entry) {
+            if (!is_array($entry) || empty($entry['candidate_event_id'])) { $invalid[] = 'missing_candidate_event_id'; continue; }
+            $id = absint($entry['candidate_event_id']);
+            if (isset($seen[$id])) { $duplicate[] = $id; }
+            $seen[$id] = true;
+            if (!array_key_exists($id, $expected)) { $unexpected[] = $id; continue; }
+            $signals = $entry['discovered_by'] ?? null;
+            if (!is_array($signals)) { $invalid[] = $id; continue; }
+            foreach ($signals as $signal) {
+                if (!is_string($signal) || !in_array($signal, $allowed, true)) { $invalid[] = $id; }
+            }
+            $normalized = array_values(array_unique(array_filter($signals, 'is_string')));
+            sort($normalized);
+            $expected_normalized = $expected[$id];
+            sort($expected_normalized);
+            $comparison_signals = $entry['comparison']['identity_assessment']['candidate_discovery_signals'] ?? null;
+            if (!is_array($comparison_signals)) {
+                $mismatched[] = $id;
+            } else {
+                $comparison_normalized = array_values(array_unique(array_filter($comparison_signals, 'is_string')));
+                sort($comparison_normalized);
+                if ($comparison_normalized !== $normalized) { $mismatched[] = $id; }
+            }
+            if ($normalized !== $expected_normalized) { $mismatched[] = $id; }
+        }
+        $missing = array_values(array_diff(array_keys($expected), array_keys($seen)));
+        $errors = [];
+        if ($missing) { $errors[] = 'adapter_discovery_evidence_missing_candidates'; }
+        if ($unexpected) { $errors[] = 'adapter_discovery_evidence_has_unexpected_candidates'; }
+        if ($mismatched) { $errors[] = 'adapter_discovery_signals_disagree_with_candidate_inventory'; }
+        if ($duplicate) { $errors[] = 'adapter_discovery_evidence_has_duplicate_candidates'; }
+        if ($invalid) { $errors[] = 'adapter_discovery_evidence_has_invalid_signals_or_records'; }
+        return [
+            'status' => $errors ? 'adapter_discovery_evidence_requires_review' : 'adapter_discovery_evidence_consistent',
+            'consistent' => !$errors,
+            'errors' => $errors,
+            'candidate_count_expected' => count($expected),
+            'candidate_count_observed' => count($seen),
+            'missing_candidate_event_ids' => $missing,
+            'unexpected_candidate_event_ids' => array_values(array_unique($unexpected)),
+            'mismatched_candidate_event_ids' => array_values(array_unique($mismatched)),
+            'duplicate_candidate_event_ids' => array_values(array_unique($duplicate)),
+            'invalid_candidate_records' => array_values(array_unique($invalid, SORT_REGULAR)),
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Adapter evidence must preserve discovery provenance; matching signals remain discovery evidence only and never establish shared event identity.',
+        ];
+    }
+
+    /**
+     * Compare the normalized dimensions in adapter evidence with the dimensions
+     * independently classified for each candidate. This validates audit transport,
+     * not shared identity; missing values remain unknown rather than matching.
+     */
+    /**
+     * Classify temporal granularity without treating interval overlap as identity.
+     * Daily windows, aggregate periods and point timestamps are distinct evidence shapes.
+     */
+    /**
+     * Describe the temporal basis that can actually be established from the
+     * adapter contract. The current event table does not persist a timezone or
+     * timezone-version fingerprint, so even WordPress-local values produced by
+     * two adapters cannot safely be compared as absolute instants across imports.
+     * Calendar aggregates retain date-label semantics and are not converted to
+     * timestamps. This helper is descriptive and never authorizes suppression.
+     */
+    private function classify_reconciliation_temporal_basis($adapter_key, $origin_key, $record_type) {
+        $adapter_key = sanitize_key((string) $adapter_key);
+        $origin_key = sanitize_key((string) $origin_key);
+        $record_type = sanitize_key((string) $record_type);
+
+        if ($record_type === 'aggregate') {
+            return [
+                'basis' => 'aggregate_period_timezone_unverified',
+                'source_representation' => 'date_bounded_aggregate_or_period',
+                'absolute_time_comparable' => false,
+                'reason' => 'The adapter imports an aggregate period, but its exact calendar semantics, source timezone, and historical site-timezone setting are not persisted here.',
+            ];
+        }
+
+        if ($record_type === 'event' && $adapter_key === 'burst_statistics') {
+            return [
+                'basis' => 'wordpress_site_local_timezone_unrecorded',
+                'source_representation' => 'unix_timestamp_converted_with_wp_date',
+                'absolute_time_comparable' => false,
+                'reason' => 'The source instant is known, but the WordPress timezone identifier/offset at import time is not persisted with the event.',
+            ];
+        }
+
+        if ($record_type === 'event' && $adapter_key === 'independent_analytics') {
+            return [
+                'basis' => 'wordpress_site_local_timezone_unrecorded',
+                'source_representation' => 'utc_timestamp_converted_to_wp_local_with_wp_date',
+                'absolute_time_comparable' => false,
+                'reason' => 'The source is UTC and is converted to WordPress local time, but the conversion timezone identifier/offset is not persisted with the event.',
+            ];
+        }
+
+        if ($record_type === 'event' && $adapter_key === 'pulseviews' && $origin_key === 'recent_raw_views') {
+            return [
+                'basis' => 'source_local_timezone_unknown',
+                'source_representation' => 'naive_sql_datetime',
+                'absolute_time_comparable' => false,
+                'reason' => 'The raw source datetime has no documented timezone or UTC offset.',
+            ];
+        }
+
+        return [
+            'basis' => 'unknown',
+            'source_representation' => 'unverified',
+            'absolute_time_comparable' => false,
+            'reason' => 'The adapter does not provide sufficient persisted timezone provenance for absolute-time comparison.',
+        ];
+    }
+
+    private function classify_reconciliation_temporal_granularity($record_type, $period_start, $period_end, $precision_hint = 'unknown') {
+        if (!$this->is_valid_reconciliation_period_range($period_start, $period_end)) {
+            return [
+                'granularity' => 'unknown',
+                'classification' => 'insufficient_or_invalid_temporal_bounds',
+                'comparable_at_same_granularity' => false,
+            ];
+        }
+        if ($precision_hint === 'calendar_day'
+            || (substr($period_start, 11) === '00:00:00' && substr($period_end, 11) === '23:59:59')) {
+            return [
+                'granularity' => 'calendar_day',
+                'classification' => 'day_level_interval',
+                'comparable_at_same_granularity' => true,
+            ];
+        }
+        if ($record_type === 'aggregate') {
+            return [
+                'granularity' => 'aggregate_period',
+                'classification' => 'aggregate_interval',
+                'comparable_at_same_granularity' => true,
+            ];
+        }
+        if ($record_type === 'event' && $period_start === $period_end) {
+            return [
+                'granularity' => 'point_timestamp',
+                'classification' => 'event_timestamp_unverified',
+                'comparable_at_same_granularity' => true,
+            ];
+        }
+        return [
+            'granularity' => 'unknown',
+            'classification' => 'unrecognized_temporal_shape',
+            'comparable_at_same_granularity' => false,
+        ];
+    }
+
+    /**
+     * Accept only canonical local SQL datetime values for reconciliation periods.
+     * This validates representation, not timezone equivalence or event identity.
+     */
+    private function is_valid_reconciliation_period_datetime($value) {
+        if (!is_string($value) || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $value)) {
+            return false;
+        }
+        $parsed = DateTime::createFromFormat('!Y-m-d H:i:s', $value);
+        $errors = DateTime::getLastErrors();
+        return $parsed instanceof DateTime
+            && $parsed->format('Y-m-d H:i:s') === $value
+            && ($errors === false || (empty($errors['warning_count']) && empty($errors['error_count'])));
+    }
+
+    /**
+     * Validate chronological ordering when both period boundaries are known.
+     * Canonical local SQL datetimes can be compared lexically; this does not
+     * infer timezone equivalence or prove event identity.
+     */
+    private function is_valid_reconciliation_period_range($period_start, $period_end) {
+        if (!$this->is_valid_reconciliation_period_datetime($period_start)
+            || !$this->is_valid_reconciliation_period_datetime($period_end)) {
+            return null;
+        }
+        return strcmp($period_end, $period_start) >= 0;
+    }
+
+    private function build_generic_adapter_dimension_evidence_consistency($conflict_assessment, $adapter_overlap_evidence) {
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $adapter_overlap_evidence = is_array($adapter_overlap_evidence) ? $adapter_overlap_evidence : [];
+        $expected = [];
+        foreach ((array) ($conflict_assessment['candidates'] ?? []) as $candidate) {
+            if (!is_array($candidate) || empty($candidate['candidate_event_id'])) { continue; }
+            $expected[absint($candidate['candidate_event_id'])] = (array) ($candidate['dimension_checks'] ?? []);
+        }
+        $seen = [];
+        $missing = [];
+        $unexpected = [];
+        $mismatched = [];
+        $incomplete = [];
+        $invalid_period_ranges = [];
+        $dimensions = ['product_id', 'record_type', 'observed_views', 'period_start', 'period_end'];
+        foreach ($adapter_overlap_evidence as $entry) {
+            if (!is_array($entry) || empty($entry['candidate_event_id'])) { $incomplete[] = 'missing_candidate_event_id'; continue; }
+            $id = absint($entry['candidate_event_id']);
+            if (isset($seen[$id])) { $mismatched[] = $id; }
+            $seen[$id] = true;
+            if (!array_key_exists($id, $expected)) { $unexpected[] = $id; continue; }
+            $incoming = $entry['comparison']['incoming'] ?? null;
+            $candidate = $entry['comparison']['candidate'] ?? null;
+            if (!is_array($incoming) || !is_array($candidate)) { $incomplete[] = $id; continue; }
+            $actual = [];
+            foreach ($dimensions as $dimension) {
+                if (!array_key_exists($dimension, $incoming) || !array_key_exists($dimension, $candidate)) {
+                    $actual[$dimension] = null;
+                    continue;
+                }
+                if ($dimension === 'product_id' || $dimension === 'observed_views') {
+                    $left_value = $incoming[$dimension];
+                    $right_value = $candidate[$dimension];
+                    if ($left_value === null || $right_value === null || $left_value === '' || $right_value === ''
+                        || !is_numeric($left_value) || !is_numeric($right_value)) {
+                        $actual[$dimension] = null;
+                        $incomplete[] = $id . ':' . $dimension;
+                    } else {
+                        $left_number = (float) $left_value;
+                        $right_number = (float) $right_value;
+                        if ($left_number < 0 || $right_number < 0
+                            || ($dimension === 'product_id' && ($left_number <= 0 || $right_number <= 0))) {
+                            $actual[$dimension] = null;
+                            $incomplete[] = $id . ':' . $dimension;
+                        } else {
+                            $actual[$dimension] = $left_number === $right_number;
+                        }
+                    }
+                } elseif ($dimension === 'record_type') {
+                    $left = is_scalar($incoming[$dimension]) ? (string) $incoming[$dimension] : '';
+                    $right = is_scalar($candidate[$dimension]) ? (string) $candidate[$dimension] : '';
+                    $actual[$dimension] = ($left !== '' && $right !== '') ? $left === $right : null;
+                    if ($actual[$dimension] === null) { $incomplete[] = $id . ':' . $dimension; }
+                } else {
+                    $left = $incoming[$dimension];
+                    $right = $candidate[$dimension];
+                    if (!$this->is_valid_reconciliation_period_datetime($left)
+                        || !$this->is_valid_reconciliation_period_datetime($right)) {
+                        $actual[$dimension] = null;
+                        $incomplete[] = $id . ':' . $dimension;
+                    } else {
+                        $actual[$dimension] = $left === $right;
+                    }
+                }
+            }
+            foreach (['incoming' => $incoming, 'candidate' => $candidate] as $side => $period_data) {
+                $range_valid = $this->is_valid_reconciliation_period_range(
+                    $period_data['period_start'] ?? null,
+                    $period_data['period_end'] ?? null
+                );
+                if ($range_valid === false) {
+                    $invalid_period_ranges[] = $id . ':' . $side;
+                    $mismatched[] = $id;
+                } elseif ($range_valid === null) {
+                    // Boundary validity is already reported per dimension above.
+                    // Do not turn unknown boundaries into an ordering conclusion.
+                }
+            }
+            $expected_checks = $expected[$id];
+            foreach ($dimensions as $dimension) {
+                if (!array_key_exists($dimension, $expected_checks) || $expected_checks[$dimension] !== $actual[$dimension]) {
+                    $mismatched[] = $id;
+                    break;
+                }
+            }
+        }
+        $missing = array_values(array_diff(array_keys($expected), array_keys($seen)));
+        $errors = [];
+        if ($missing) { $errors[] = 'adapter_dimension_evidence_missing_candidates'; }
+        if ($unexpected) { $errors[] = 'adapter_dimension_evidence_has_unexpected_candidates'; }
+        if ($mismatched) { $errors[] = 'adapter_dimension_checks_disagree_with_conflict_assessment'; }
+        if ($incomplete) { $errors[] = 'adapter_dimension_evidence_incomplete'; }
+        if ($invalid_period_ranges) { $errors[] = 'adapter_period_range_end_precedes_start'; }
+        return [
+            'status' => $errors ? 'adapter_dimension_evidence_requires_review' : 'adapter_dimension_evidence_consistent',
+            'consistent' => !$errors,
+            'errors' => $errors,
+            'candidate_count_expected' => count($expected),
+            'candidate_count_observed' => count($seen),
+            'missing_candidate_event_ids' => $missing,
+            'unexpected_candidate_event_ids' => array_values(array_unique($unexpected)),
+            'mismatched_candidate_event_ids' => array_values(array_unique($mismatched)),
+            'incomplete_candidate_records' => array_values(array_unique($incomplete, SORT_REGULAR)),
+            'invalid_period_ranges' => array_values(array_unique($invalid_period_ranges)),
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'Adapter dimension evidence must reproduce the independently recorded comparison checks. Missing dimensions remain unknown; reversed known period boundaries require review. Consistency validates audit integrity only and never proves shared event identity.',
+        ];
+    }
+
+    /**
+     * Validate the complete candidate reconciliation audit chain, including the
+     * independent candidate ordering checks. This is diagnostic only and cannot
+     * promote evidence to identity proof or change any applied contribution.
+     */
+    private function build_generic_candidate_reconciliation_chain_assessment($candidate_set_assessment, $conflict_assessment, $evidence_decision, $audit_consistency, $candidate_consistency, $reference_consistency = [], $discovery_signal_consistency = []) {
+        $candidate_set_assessment = is_array($candidate_set_assessment) ? $candidate_set_assessment : [];
+        $conflict_assessment = is_array($conflict_assessment) ? $conflict_assessment : [];
+        $evidence_decision = is_array($evidence_decision) ? $evidence_decision : [];
+        $audit_consistency = is_array($audit_consistency) ? $audit_consistency : [];
+        $candidate_consistency = is_array($candidate_consistency) ? $candidate_consistency : [];
+        $reference_consistency = is_array($reference_consistency) ? $reference_consistency : [];
+        $discovery_signal_consistency = is_array($discovery_signal_consistency) ? $discovery_signal_consistency : [];
+        $errors = [];
+
+        $inventory_count = max(0, (int) ($candidate_set_assessment['candidate_count_retained'] ?? 0));
+        $conflict_count = max(0, (int) ($conflict_assessment['candidate_count'] ?? 0));
+        $decision_count = max(0, (int) ($evidence_decision['candidate_count'] ?? 0));
+        $ordering_count = max(0, (int) ($candidate_consistency['candidate_count'] ?? 0));
+        $adapter_count = max(0, (int) ($candidate_consistency['adapter_evidence_candidate_count'] ?? 0));
+
+        if (count(array_unique([$inventory_count, $conflict_count, $decision_count, $ordering_count])) > 1) {
+            $errors[] = 'candidate_inventory_conflict_decision_and_ordering_counts_disagree';
+        }
+        if (!empty($candidate_consistency['adapter_evidence_order_consistent']) && $adapter_count !== $ordering_count) {
+            $errors[] = 'adapter_evidence_count_disagrees_despite_order_consistency_claim';
+        }
+        if (!empty($candidate_consistency['primary_in_candidate_list']) === false) {
+            $errors[] = 'primary_candidate_missing_from_candidate_list';
+        }
+        if (!empty($candidate_consistency['adapter_evidence_primary_consistent']) === false) {
+            $errors[] = 'adapter_evidence_primary_candidate_inconsistent';
+        }
+        if (!empty($candidate_consistency['adapter_evidence_order_consistent']) === false) {
+            $errors[] = 'adapter_evidence_candidate_order_inconsistent';
+        }
+        if (array_key_exists('adapter_discovery_evidence_consistent', $candidate_consistency)
+            && empty($candidate_consistency['adapter_discovery_evidence_consistent'])) {
+            $errors[] = 'adapter_discovery_evidence_provenance_inconsistent';
+        }
+        if (array_key_exists('adapter_dimension_evidence_consistent', $candidate_consistency)
+            && empty($candidate_consistency['adapter_dimension_evidence_consistent'])) {
+            $errors[] = 'adapter_dimension_evidence_inconsistent_with_conflict_assessment';
+        }
+        if (empty($audit_consistency['consistent'])) {
+            $errors[] = 'underlying_candidate_audit_layers_are_inconsistent';
+        }
+        if (array_key_exists('consistent', $reference_consistency) && empty($reference_consistency['consistent'])) {
+            $errors[] = 'candidate_event_or_source_references_are_inconsistent';
+        }
+        if (array_key_exists('consistent', $discovery_signal_consistency) && empty($discovery_signal_consistency['consistent'])) {
+            $errors[] = 'candidate_discovery_signal_provenance_is_inconsistent';
+        }
+        if (array_key_exists('classification_coverage_complete', $audit_consistency)
+            && empty($audit_consistency['classification_coverage_complete'])) {
+            $errors[] = 'candidate_classification_coverage_incomplete_in_chain';
+        }
+        if (!empty($candidate_set_assessment['candidate_set_truncated']) && empty($evidence_decision['candidate_search_truncated'])) {
+            $errors[] = 'truncation_missing_from_final_candidate_decision';
+        }
+        if (!empty($evidence_decision['identity_proven']) || !empty($candidate_consistency['identity_proven'])) {
+            $errors[] = 'candidate_reconciliation_chain_claims_identity_proof';
+        }
+        if (!empty($evidence_decision['automatic_suppression_authorized']) || !empty($candidate_consistency['automatic_suppression_authorized'])) {
+            $errors[] = 'candidate_reconciliation_chain_authorizes_automatic_suppression';
+        }
+
+        return [
+            'status' => $errors ? 'reconciliation_chain_requires_review' : 'reconciliation_chain_consistent',
+            'consistent' => !$errors,
+            'errors' => array_values(array_unique($errors)),
+            'candidate_counts' => [
+                'inventory' => $inventory_count,
+                'conflict_assessment' => $conflict_count,
+                'evidence_decision' => $decision_count,
+                'candidate_ordering' => $ordering_count,
+                'adapter_evidence' => $adapter_count,
+            ],
+            'candidate_search_truncated' => !empty($evidence_decision['candidate_search_truncated']),
+            'classification_coverage_complete' => !empty($audit_consistency['classification_coverage_complete']),
+            'classified_candidate_count' => max(0, (int) ($audit_consistency['classified_candidate_count'] ?? 0)),
+            'unclassified_candidate_count' => max(0, (int) ($audit_consistency['unclassified_candidate_count'] ?? 0)),
+            'candidate_reference_consistency' => $reference_consistency,
+            'candidate_discovery_signal_consistency' => $discovery_signal_consistency,
+            'adapter_discovery_evidence_consistent' => !empty($candidate_consistency['adapter_discovery_evidence_consistent']),
+            'adapter_dimension_evidence_consistent' => !empty($candidate_consistency['adapter_dimension_evidence_consistent']),
+            'identity_proven' => false,
+            'automatic_suppression_authorized' => false,
+            'policy' => 'This end-to-end check validates audit-chain consistency only. Any inconsistency requires review; no result changes applied_views, totals, or count suppression.',
+        ];
+    }
+
+    private function build_generic_product_reconciliation_summary($product_id, $cross_source, $partial_overlap, $product_synthesis, $matched_event = null, $candidate_set = null) {
+        $cross_source = is_array($cross_source) ? $cross_source : [];
+        $partial_overlap = is_array($partial_overlap) ? $partial_overlap : [];
+        $product_synthesis = is_array($product_synthesis) ? $product_synthesis : [];
+        $candidate_set = is_array($candidate_set) ? $candidate_set : [];
+        $candidate_set_assessment = $this->build_generic_candidate_set_assessment(
+            $candidate_set['candidates'] ?? [],
+            !empty($candidate_set['truncated']),
+            $candidate_set['observed_count'] ?? null
+        );
+
+        $capability_status = sanitize_key((string) ($product_synthesis['capability_profile_status'] ?? 'unknown'));
+        $synthesis_status = sanitize_key((string) ($product_synthesis['status'] ?? 'unknown'));
+        $partial_status = sanitize_key((string) ($partial_overlap['status'] ?? 'unknown'));
+        $cross_truncated = !empty($cross_source['candidate_set_truncated']);
+        $inventory_truncated = !empty($product_synthesis['source_record_groups_truncated']);
+        $partial_truncated = !empty($partial_overlap['records_truncated']);
+
+        $limitations = [];
+        if ($synthesis_status !== 'available') { $limitations[] = 'product_source_synthesis_' . ($synthesis_status ?: 'unknown'); }
+        if (!in_array($capability_status, ['available'], true)) { $limitations[] = 'source_capability_profiles_' . ($capability_status ?: 'unknown'); }
+        if ($cross_truncated) { $limitations[] = 'cross_source_candidate_set_truncated'; }
+        if ($inventory_truncated) { $limitations[] = 'product_source_record_groups_truncated'; }
+        if ($partial_status !== 'ok') { $limitations[] = 'partial_overlap_' . ($partial_status ?: 'unknown'); }
+        if ($partial_truncated) { $limitations[] = 'partial_overlap_records_truncated'; }
+
+        $source_count = max(0, (int) ($product_synthesis['source_count_in_scope'] ?? 0));
+        $capability_count = max(0, (int) ($product_synthesis['capability_profile_source_count'] ?? 0));
+        $complete = !$limitations && $source_count === $capability_count;
+
+        // Classify the available evidence without making a new counting decision.
+        // The exact-match flag is supplied only by the importer's existing path,
+        // which has already validated the shared fingerprint and normalized dimensions.
+        $candidate_records = max(0, (int) ($cross_source['candidate_record_count'] ?? 0));
+        $candidate_sources = max(0, (int) ($cross_source['candidate_source_count'] ?? 0));
+        if (is_array($matched_event) && !empty($matched_event['id'])) {
+            $decision_classification = 'confirmed_exact_shared_fingerprint_match';
+            $decision_basis = 'existing_importer_exact_match_contract';
+            $decision_identity_proven = true;
+        } elseif (!empty($candidate_set_assessment['multiple_candidate_ambiguity'])) {
+            $decision_classification = 'multiple_cross_source_candidates_require_review';
+            $decision_basis = 'all_candidates_retained_without_identity_resolution';
+            $decision_identity_proven = false;
+        } elseif ($candidate_records > 0 || $candidate_sources > 0) {
+            $decision_classification = 'possible_cross_source_overlap_requires_review';
+            $decision_basis = 'candidate_fingerprint_or_temporal_evidence_only';
+            $decision_identity_proven = false;
+        } else {
+            $decision_classification = 'insufficient_evidence_to_establish_cross_source_overlap';
+            $decision_basis = 'no_candidate_found_within_declared_search_bounds';
+            $decision_identity_proven = false;
+        }
+
+        return [
+            'version' => '1.0.0',
+            'status' => $complete ? 'evidence_inventory_complete_within_declared_bounds' : 'evidence_inventory_partial_or_limited',
+            'product_id' => absint($product_id),
+            'source_scope' => 'all_persisted_generic_sources_for_product',
+            'source_count' => $source_count,
+            'capability_profile_source_count' => $capability_count,
+            'cross_source_candidate_count' => max(0, (int) ($cross_source['candidate_source_count'] ?? 0)),
+            'partial_overlap_source_count' => count((array) ($partial_overlap['profiles'] ?? [])),
+            'same_bucket_count_bounds' => $cross_source['identical_bucket_count_range'] ?? ['status' => 'unavailable'],
+            'reconciliation_decision' => [
+                'classification' => $decision_classification,
+                'basis' => $decision_basis,
+                'identity_proven' => $decision_identity_proven,
+                'summary_authorizes_count_change' => false,
+                'candidate_search_truncated' => $cross_truncated,
+                'candidate_set_assessment' => $candidate_set_assessment,
+                'policy' => 'This classification describes evidence only. It does not independently authorize suppression, adjustment, or rewriting of applied_views.',
+            ],
+            'unique_view_total' => null,
+            'counting_decision' => 'preserve_all_applied_contributions_no_automatic_suppression',
+            'limitations' => array_values(array_unique($limitations)),
+            'interpretation' => 'This summary combines source inventory, declared capabilities, candidate overlap evidence, and the availability limits of partial-period comparison. It does not prove event identity or calculate a deduplicated unique-view total.',
+        ];
+    }
+
+    /**
+     * Partial aggregate-period duration comparisons are withheld until source
+     * timezone provenance is persisted. Naive datetime strings cannot safely be
+     * converted into shared elapsed-time intervals.
+     */
+    private function build_generic_partial_overlap_profiles($product_id, $source_id, $period_start, $period_end) {
+        // Persisted period strings do not include source timezone provenance.
+        // Do not report elapsed seconds or coverage ratios from naive datetimes.
+        return [
+            'status' => 'unavailable',
+            'reason' => 'timezone_basis_not_persisted',
+            'incoming_period_seconds' => null,
+            'profiles' => [],
+            'records_truncated' => false,
+            'identity_confidence' => 'unproven_without_shared_event_identity',
+            'temporal_comparison' => 'not_performed',
+        ];
+    }
+
+    /** Execute the importer while the caller holds the source-origin advisory lock. */
+    private function process_generic_historical_view_import_batch($source_id, $origin_key, $retry_checkpoint_override = null, $origin_lock = null) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = sanitize_key((string) $origin_key);
+        if (!$source_id || $origin_key === '') {
+            return ['status' => 'invalid_input'];
+        }
+        if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'origin_lock_session_lost'];
+        }
+
+        $state = $this->get_view_source_origin_state($source_id, $origin_key);
+        if (empty($state['status']) || $state['status'] !== 'found') {
+            return ['status' => 'origin_not_found'];
+        }
+        // A queued action may outlive a provider's latest discovery inventory.
+        // Never let such a stale action process an origin that has since been
+        // marked unavailable or is no longer explicitly detected as available.
+        if ($state['origin_status'] === 'unavailable' || $state['detection_status'] !== 'available') {
+            return ['status' => 'origin_unavailable'];
+        }
+        if ($state['origin_status'] === 'completed' && $retry_checkpoint_override === null) {
+            return ['status' => 'already_completed'];
+        }
+        // A terminal failure for one record must not stop the main source scan.
+        // The failed record remains in the ledger for review, while later records
+        // continue importing. Only the independent retry worker is capped at three
+        // total attempts for that individual record.
+        if (!is_array($state['snapshot']) || empty($state['snapshot']['boundary']) || !is_array($state['checkpoint'])) {
+            return ['status' => 'snapshot_not_ready'];
+        }
+
+        $adapter_key = isset($state['adapter_key']) ? sanitize_key($state['adapter_key']) : '';
+        $adapter = $this->get_historical_view_adapter($adapter_key);
+        if (!$adapter) {
+            // A scheduled request may have arrived before provider registration.
+            $this->discover_historical_view_adapters();
+            $adapter = $this->get_historical_view_adapter($adapter_key);
+        }
+        if (!$adapter) {
+            // Provider plugins may be temporarily inactive, load later than this
+            // worker, or briefly fail while assembling their registry. Keep the
+            // immutable snapshot/checkpoint untouched and retry discovery later.
+            // Normal plugin initialization also rediscovers providers, so a
+            // returning adapter can resume automatically without administrator
+            // intervention. A replacement adapter still cannot reinterpret the
+            // persisted identity because register_view_source_origin() guards it.
+            $this->update_view_source_origin_state($source_id, $origin_key, [
+                'last_error' => 'The registered historical adapter is temporarily unavailable; automatic discovery will be retried.',
+            ], $origin_lock);
+            $this->schedule_generic_historical_view_import_batch(21600, $source_id, $origin_key);
+            return ['status' => 'adapter_unavailable', 'retry_scheduled' => true];
+        }
+
+        $checkpoint = ($retry_checkpoint_override !== null && is_array($retry_checkpoint_override))
+            ? $retry_checkpoint_override
+            : $state['checkpoint'];
+        $batch_start_checkpoint = $checkpoint;
+        try {
+            $batch = $adapter->get_product_view_batch($origin_key, $checkpoint, $state['snapshot'], 100);
+        } catch (Throwable $exception) {
+            $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin_key,
+                    'batch:' . substr(hash('sha256', wp_json_encode($checkpoint)), 0, 32),
+                    0,
+                    $exception->getMessage(),
+                    null,
+                    8,
+                    $origin_lock);
+            if (!$failure['blocked']) {
+                $this->schedule_generic_historical_view_import_batch($failure['retry_delay'], $source_id, $origin_key);
+            }
+            return ['status' => $failure['blocked'] ? 'needs_attention' : 'source_read_failed', 'attempts' => $failure['attempts']];
+        }
+
+        $batch_rows_are_valid_list = is_array($batch)
+            && isset($batch['rows'])
+            && is_array($batch['rows'])
+            && array_keys($batch['rows']) === (count($batch['rows']) > 0 ? range(0, count($batch['rows']) - 1) : [])
+            && count($batch['rows']) <= 100;
+        if ($batch_rows_are_valid_list) {
+            foreach ($batch['rows'] as $batch_row) {
+                if (!is_array($batch_row)) {
+                    $batch_rows_are_valid_list = false;
+                    break;
+                }
+            }
+        }
+
+        $batch_is_valid = is_array($batch)
+            && $batch_rows_are_valid_list
+            && array_key_exists('has_more', $batch)
+            && is_bool($batch['has_more'])
+            // The adapter must apply the immutable snapshot boundary in its source query.
+            && isset($batch['boundary_applied'])
+            && $batch['boundary_applied'] === true;
+
+        if ($batch_is_valid && $batch['has_more']) {
+            $batch_is_valid = !empty($batch['rows'])
+                && array_key_exists('next_checkpoint', $batch)
+                && (is_array($batch['next_checkpoint']) || is_scalar($batch['next_checkpoint']))
+                && $this->is_valid_generic_historical_cursor($batch['next_checkpoint'])
+                && wp_json_encode($batch['next_checkpoint']) !== wp_json_encode($checkpoint);
+        }
+
+        if (!$batch_is_valid) {
+            $failure = $this->record_generic_historical_view_failure($source_id,
+                    $origin_key,
+                    'batch:' . substr(hash('sha256', wp_json_encode($checkpoint)), 0, 32),
+                    0,
+                    'Adapter returned an invalid or non-progressing batch. Expected a sequential list of at most 100 array rows, a boolean has_more, boundary_applied=true, and an advancing next_checkpoint whenever more rows remain.',
+                    null,
+                    8,
+                    $origin_lock);
+            if (!$failure['blocked']) {
+                $this->schedule_generic_historical_view_import_batch($failure['retry_delay'], $source_id, $origin_key);
+            }
+            return ['status' => $failure['blocked'] ? 'needs_attention' : 'invalid_batch', 'attempts' => $failure['attempts']];
+        }
+
+        // The source has now returned a structurally valid, snapshot-bounded batch;
+        // clear a previous transient batch-read failure before processing its records.
+        $batch_failure_cleared = $this->clear_generic_historical_view_failure(
+            $source_id,
+            $origin_key,
+            'batch:' . substr(hash('sha256', wp_json_encode($checkpoint)), 0, 32)
+        , $origin_lock);
+        if (!$batch_failure_cleared) {
+            // Do not consume this batch while its previous batch-level failure
+            // remains unresolved in the durable ledger.
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'failure_ledger_clear_failed'];
+        }
+
+        $processed = 0;
+        $duplicates = 0;
+        $failed = 0;
+        $skipped = 0;
+        $next_checkpoint = $checkpoint;
+
+        $checkpoint_persistence_failed = false;
+        foreach ($batch['rows'] as $record) {
+            try {
+                $normalized = $adapter->normalize_record($origin_key, $record);
+            } catch (Throwable $exception) {
+                $normalized = null;
+                $normalization_error = $exception->getMessage();
+            }
+
+            // A replay of a saved batch must retry only records whose own retry
+            // deadline has arrived. Otherwise one due record could cause blocked
+            // or not-yet-due neighbours in the same batch to be retried indefinitely.
+            if ($retry_checkpoint_override !== null) {
+                if (is_array($normalized)) {
+                    $retry_record_key = !empty($normalized['source_record_key'])
+                        ? (string) $normalized['source_record_key']
+                        : wp_json_encode($record);
+                } elseif (is_array($record) && isset($record['source_record_key'])) {
+                    $retry_record_key = (string) $record['source_record_key'];
+                } else {
+                    $retry_record_key = wp_json_encode($record);
+                }
+                $retry_record_key = substr((string) $retry_record_key, 0, 191);
+                $retry_record_hash = hash('sha256', (string) $origin_key . "\0" . $retry_record_key);
+                $retry_is_due = statpl_db_get_var(statpl_db_prepare(
+                    "SELECT id FROM {$this->view_source_failures_table}
+                     WHERE source_id = %d AND source_record_hash = %s
+                       AND status = 'retry' AND next_retry_at <= %s
+                     LIMIT 1",
+                    $source_id,
+                    $retry_record_hash,
+                    current_time('mysql')
+                ));
+                if (!empty($wpdb->last_error)) {
+                    $this->schedule_generic_historical_failure_retry(300, $source_id, $origin_key);
+                    return ['status' => 'retry_ledger_lookup_failed', 'processed' => $processed, 'duplicates' => $duplicates];
+                }
+                if (!$retry_is_due) {
+                    continue;
+                }
+            }
+
+            if (is_array($normalized) && !empty($normalized['skip'])) {
+                // Adapters may explicitly identify a source row as outside their
+                // product-view scope (for example, a site-wide analytics row for
+                // a blog page). Such rows are not failures and must not block the
+                // scan, but their source key and cursor still require validation.
+                $skip_record_key = isset($normalized['source_record_key'])
+                    ? trim((string) $normalized['source_record_key']) : '';
+                $skip_cursor = array_key_exists('cursor', $normalized) ? $normalized['cursor'] : null;
+                if ($skip_record_key === '' || strlen($skip_record_key) > 191
+                    || !$this->is_valid_generic_historical_cursor($skip_cursor)) {
+                    $normalized = null;
+                    $normalization_error = 'Adapter returned an invalid explicit skip record.';
+                } else {
+                    $skip_failure_cleared = $this->clear_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $skip_record_key
+                    , $origin_lock, null);
+                    if (!$skip_failure_cleared) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    $next_checkpoint['cursor'] = $skip_cursor;
+                    $skipped++;
+                    continue;
+                }
+            }
+
+            if (!is_array($normalized)) {
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure(
+                    $source_id,
+                    $origin_key,
+                    (is_array($record) && isset($record['source_record_key'])) ? $record['source_record_key'] : wp_json_encode($record),
+                    0,
+                    isset($normalization_error) ? $normalization_error : 'Adapter could not normalize a source record.',
+                    $batch_start_checkpoint,
+                    3
+                , $origin_lock);
+                if (empty($failure['persisted'])) {
+                    // Without a durable failure-ledger entry, do not advance past this record.
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    $checkpoint_persistence_failed = true;
+                    break;
+                }
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                }
+                unset($normalization_error);
+                continue;
+            }
+
+            $product_id = isset($normalized['product_id']) ? absint($normalized['product_id']) : 0;
+            $record_key = isset($normalized['source_record_key']) ? trim((string) $normalized['source_record_key']) : '';
+            $raw_views = array_key_exists('views', $normalized) ? $normalized['views'] : null;
+            $views_is_valid = is_int($raw_views) && $raw_views >= 0;
+            if (is_string($raw_views) && preg_match('/^(0|[1-9]\d*)$/D', $raw_views)) {
+                // Do not compare large decimal strings through float: on 64-bit PHP,
+                // (float) PHP_INT_MAX rounds to 2^63 and can admit an overflowing value.
+                $max_views_string = (string) PHP_INT_MAX;
+                $raw_views_length = strlen($raw_views);
+                $max_views_length = strlen($max_views_string);
+                $views_is_valid = $raw_views_length < $max_views_length
+                    || ($raw_views_length === $max_views_length && strcmp($raw_views, $max_views_string) <= 0);
+            }
+            $views = $views_is_valid ? (int) $raw_views : -1;
+            $cursor = array_key_exists('cursor', $normalized) ? $normalized['cursor'] : null;
+            $record_type = isset($normalized['record_type']) ? sanitize_key($normalized['record_type']) : 'event';
+            $period_start = array_key_exists('period_start', $normalized) && $normalized['period_start'] !== null
+                ? (string) $normalized['period_start'] : null;
+            $period_end = array_key_exists('period_end', $normalized) && $normalized['period_end'] !== null
+                ? (string) $normalized['period_end'] : null;
+            $periods_are_valid = $this->is_valid_generic_historical_datetime($period_start)
+                && $this->is_valid_generic_historical_datetime($period_end);
+            if ($periods_are_valid && $period_start !== null && $period_end !== null) {
+                $periods_are_valid = strcmp($period_start, $period_end) <= 0;
+            }
+
+            if (
+                !$product_id || get_post_type($product_id) !== 'product'
+                || $record_key === '' || strlen($record_key) > 191
+                || !$views_is_valid || $views < 0 || !in_array($record_type, ['event', 'aggregate'], true)
+                || !$this->is_valid_generic_historical_cursor($cursor)
+                || !$periods_are_valid
+                || ($record_type === 'aggregate' && ($period_start === null || $period_end === null))
+            ) {
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure(
+                    $source_id,
+                    $origin_key,
+                    $record_key !== '' ? $record_key : wp_json_encode($record),
+                    $product_id,
+                    'Normalized record failed validation (product, key, views, type or cursor).',
+                    $batch_start_checkpoint,
+                    3
+                , $origin_lock);
+                if (empty($failure['persisted'])) {
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    $checkpoint_persistence_failed = true;
+                    break;
+                }
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                }
+                unset($normalization_error);
+                continue;
+            }
+
+            $record_hash = hash('sha256', $origin_key . "\0" . $record_key);
+            $now = current_time('mysql');
+            $source_fingerprint = isset($normalized['source_fingerprint'])
+                ? strtolower(trim((string) $normalized['source_fingerprint']))
+                : '';
+            if ($source_fingerprint !== '' && !preg_match('/^[a-f0-9]{64}$/D', $source_fingerprint)) {
+                $failed++;
+                $failure = $this->record_generic_historical_view_failure(
+                    $source_id,
+                    $origin_key,
+                    $record_key,
+                    $product_id,
+                    'Adapter supplied an invalid cross-source fingerprint; expected exactly 64 hexadecimal characters.',
+                    $batch_start_checkpoint,
+                    3
+                , $origin_lock);
+                if (empty($failure['persisted'])) {
+                    // Without a durable failure-ledger entry, do not advance past this record.
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    $checkpoint_persistence_failed = true;
+                    break;
+                }
+                if (!$failure['blocked']) {
+                    $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                }
+                continue;
+            }
+
+            // Cross-plugin reconciliation is deliberately conservative: suppress a
+            // second contribution only when both adapters provide the same explicit
+            // stable fingerprint AND all normalized event dimensions agree exactly.
+            // A fingerprint-scoped advisory lock also serializes the no-existing-row
+            // case, which SELECT ... FOR UPDATE alone cannot reliably protect.
+            $reconciliation_lock = 'statpl_xr_' . substr(hash('sha256', $wpdb->prefix . ':' . $source_fingerprint), 0, 48);
+            $reconciliation_lock_state = null;
+            // Aggregate fingerprints derived from product/date/count are not shared
+            // event identities. They must never drive exact cross-source suppression.
+            // Keep exact fingerprint reconciliation restricted to individual events.
+            $has_exact_event_fingerprint = $source_fingerprint !== '' && $record_type === 'event';
+            if ($has_exact_event_fingerprint) {
+                $reconciliation_lock_state = $this->acquire_generic_advisory_lock($reconciliation_lock);
+                if (empty($reconciliation_lock_state['acquired'])) {
+                    $this->schedule_generic_historical_view_import_batch(30, $source_id, $origin_key);
+                    return ['status' => 'cross_source_lock_busy', 'processed' => $processed, 'duplicates' => $duplicates];
+                }
+                if (!$this->generic_advisory_lock_session_is_current($reconciliation_lock_state)) {
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    return ['status' => 'cross_source_lock_session_lost', 'processed' => $processed, 'duplicates' => $duplicates];
+                }
+            }
+
+            $transaction_open = false;
+            try {
+                if (statpl_db_query('START TRANSACTION') === false) {
+                    $failed++;
+                    $transaction_error = (string) $wpdb->last_error;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Could not start atomic source-event transaction: ' . $transaction_error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                    break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                $transaction_open = true;
+                $matched_event = null;
+            $possible_overlap_event = null;
+            $possible_overlap_events = [];
+            $possible_overlap_candidates_truncated = false;
+            $possible_overlap_fingerprint_candidates_observed = 0;
+            $possible_overlap_temporal_candidates_observed = 0;
+            $possible_overlap_candidate_count_observed = 0;
+            $possible_overlap_candidate_count_is_lower_bound = false;
+            $possible_overlap_reason_code = '';
+            if ($has_exact_event_fingerprint) {
+                $matched_event = statpl_db_get_row(statpl_db_prepare(
+                    "SELECT id, source_id, product_id, record_type, observed_views, period_start, period_end, applied_views
+                     FROM {$this->view_source_events_table}
+                     WHERE source_fingerprint = %s
+                       AND source_id <> %d
+                       AND product_id = %d
+                       AND record_type = %s
+                       AND observed_views = %d
+                       AND ((period_start IS NULL AND %s = '') OR period_start = %s)
+                       AND ((period_end IS NULL AND %s = '') OR period_end = %s)
+                     ORDER BY id ASC LIMIT 1 FOR UPDATE",
+                    $source_fingerprint,
+                    $source_id,
+                    $product_id,
+                    $record_type,
+                    $views,
+                    (string) $period_start,
+                    $period_start,
+                    (string) $period_end,
+                    $period_end
+                ), ARRAY_A);
+                if (!empty($wpdb->last_error)) {
+                    $lookup_error = $wpdb->last_error;
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Cross-source reconciliation lookup failed: ' . $lookup_error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                    break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                if (!$matched_event) {
+                    // Same explicit fingerprint with different normalized dimensions is
+                    // evidence of a possible/partial overlap, not proof of a duplicate.
+                    // Preserve and count this contribution, but retain an auditable
+                    // candidate link so a source-specific reconciliation rule can review it.
+                    $fingerprint_candidate_result = $this->get_generic_reconciliation_candidates_by_source(
+                        'fingerprint',
+                        ['fingerprint' => $source_fingerprint, 'source_id' => $source_id],
+                        25
+                    );
+                    $possible_overlap_events = $fingerprint_candidate_result['events'];
+                    $possible_overlap_fingerprint_candidates_observed = (int) $fingerprint_candidate_result['observed'];
+                    if ($fingerprint_candidate_result['status'] === 'error') {
+                        $lookup_error = $fingerprint_candidate_result['error'];
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                        }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id, $origin_key, $record_key, $product_id,
+                            'Possible-overlap reconciliation lookup failed: ' . $lookup_error,
+                            $batch_start_checkpoint, 3, $origin_lock
+                        );
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                            break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                    if (!empty($fingerprint_candidate_result['truncated'])) {
+                        $possible_overlap_candidates_truncated = true;
+                        $possible_overlap_candidate_count_is_lower_bound = true;
+                    }
+                    if (!empty($possible_overlap_events)) {
+                        $possible_overlap_event = $possible_overlap_events[0];
+                        $possible_overlap_reason_code = 'shared_fingerprint_dimension_mismatch';
+                    }
+                    if (!empty($wpdb->last_error)) {
+                        $lookup_error = $wpdb->last_error;
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id,
+                            $origin_key,
+                            $record_key,
+                            $product_id,
+                            'Possible-overlap reconciliation lookup failed: ' . $lookup_error,
+                            $batch_start_checkpoint,
+                            3
+                        , $origin_lock);
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                    break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                }
+            }
+            // Cross-source temporal overlap is retained as evidence only. This
+            // includes aggregate/event, aggregate/aggregate, and event/event pairs.
+            // Event timestamps can reveal strong candidate relationships even when
+            // providers do not share an event ID; temporal proximity alone still does
+            // not prove identity, so this discovery step never suppresses counts.
+            if (
+                !$matched_event
+                && in_array($record_type, ['aggregate', 'event'], true)
+                && $period_start !== null
+                && $period_end !== null
+            ) {
+                $temporal_candidate_result = $this->get_generic_reconciliation_candidates_by_source(
+                    'temporal',
+                    ['source_id' => $source_id, 'product_id' => $product_id, 'period_start' => $period_start, 'period_end' => $period_end],
+                    25
+                );
+                $temporal_overlap_events = $temporal_candidate_result['events'];
+                if ($temporal_candidate_result['status'] === 'error') {
+                    $lookup_error = $temporal_candidate_result['error'];
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id, $origin_key, $record_key, $product_id,
+                        'Cross-source temporal-overlap lookup failed: ' . $lookup_error,
+                        $batch_start_checkpoint, 3, $origin_lock
+                    );
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                if (!empty($wpdb->last_error)) {
+                    $lookup_error = $wpdb->last_error;
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Cross-source temporal-overlap lookup failed: ' . $lookup_error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                $possible_overlap_temporal_candidates_observed = (int) $temporal_candidate_result['observed'];
+                if (!empty($temporal_candidate_result['truncated'])) {
+                    $possible_overlap_candidates_truncated = true;
+                    $possible_overlap_candidate_count_is_lower_bound = true;
+                }
+
+                $candidate_discovery_by_id = [];
+                foreach ($possible_overlap_events as $candidate_event) {
+                    $candidate_id = isset($candidate_event['id']) ? (int) $candidate_event['id'] : 0;
+                    if ($candidate_id > 0) {
+                        $candidate_discovery_by_id[$candidate_id]['fingerprint'] = true;
+                    }
+                }
+                foreach ($temporal_overlap_events as $candidate_event) {
+                    $candidate_id = isset($candidate_event['id']) ? (int) $candidate_event['id'] : 0;
+                    if ($candidate_id > 0) {
+                        $candidate_discovery_by_id[$candidate_id]['temporal'] = true;
+                    }
+                }
+
+                $candidate_events_by_id = [];
+                foreach (array_merge($possible_overlap_events, $temporal_overlap_events) as $candidate_event) {
+                    $candidate_id = isset($candidate_event['id']) ? (int) $candidate_event['id'] : 0;
+                    if ($candidate_id > 0) {
+                        $candidate_event['_discovered_by'] = array_keys($candidate_discovery_by_id[$candidate_id] ?? []);
+                        $candidate_events_by_id[$candidate_id] = $candidate_event;
+                    }
+                }
+                $possible_overlap_events = array_values($candidate_events_by_id);
+                usort($possible_overlap_events, static function ($left, $right) {
+                    $left_sources = isset($left['_discovered_by']) ? $left['_discovered_by'] : [];
+                    $right_sources = isset($right['_discovered_by']) ? $right['_discovered_by'] : [];
+                    $left_rank = count($left_sources) > 1 ? 0 : (in_array('fingerprint', $left_sources, true) ? 1 : 2);
+                    $right_rank = count($right_sources) > 1 ? 0 : (in_array('fingerprint', $right_sources, true) ? 1 : 2);
+                    if ($left_rank !== $right_rank) {
+                        return $left_rank <=> $right_rank;
+                    }
+                    return (int) $left['id'] <=> (int) $right['id'];
+                });
+                $possible_overlap_candidate_count_observed = count($possible_overlap_events);
+                if (count($possible_overlap_events) > 25) {
+                    $possible_overlap_candidates_truncated = true;
+                    $possible_overlap_candidate_count_is_lower_bound = true;
+                    $possible_overlap_events = array_slice($possible_overlap_events, 0, 25);
+                }
+                if (!empty($possible_overlap_events)) {
+                    $possible_overlap_event = $possible_overlap_events[0];
+                }
+                if ($possible_overlap_event) {
+                    $has_fingerprint_candidate = false;
+                    $has_cross_type_candidate = false;
+                    $has_same_type_event_candidate = false;
+                    foreach ($possible_overlap_events as $candidate_event) {
+                        $discovery = isset($candidate_event['_discovered_by']) ? $candidate_event['_discovered_by'] : [];
+                        if (in_array('fingerprint', $discovery, true)) {
+                            $has_fingerprint_candidate = true;
+                        }
+                        if (
+                            in_array('temporal', $discovery, true)
+                            && isset($candidate_event['record_type'])
+                            && $candidate_event['record_type'] !== $record_type
+                        ) {
+                            $has_cross_type_candidate = true;
+                        }
+                        if (
+                            in_array('temporal', $discovery, true)
+                            && $record_type === 'event'
+                            && isset($candidate_event['record_type'])
+                            && $candidate_event['record_type'] === 'event'
+                        ) {
+                            $has_same_type_event_candidate = true;
+                        }
+                    }
+                    if ($has_fingerprint_candidate) {
+                        $possible_overlap_reason_code = 'shared_fingerprint_dimension_mismatch';
+                    } elseif ($has_cross_type_candidate) {
+                        $possible_overlap_reason_code = 'aggregate_event_temporal_overlap';
+                    } elseif ($has_same_type_event_candidate) {
+                        $possible_overlap_reason_code = 'event_timestamp_overlap';
+                    } elseif ($possible_overlap_reason_code === '') {
+                        $possible_overlap_reason_code = 'overlapping_aggregate_periods';
+                    }
+                }
+            }
+
+            if (empty($temporal_overlap_events) && !empty($possible_overlap_events)) {
+                foreach ($possible_overlap_events as &$candidate_event) {
+                    $candidate_event['_discovered_by'] = ['fingerprint'];
+                }
+                unset($candidate_event);
+                $possible_overlap_candidate_count_observed = count($possible_overlap_events);
+                if (!empty($possible_overlap_events)) {
+                    $possible_overlap_event = $possible_overlap_events[0];
+                }
+            }
+
+            // Optional source-specific analysis enriches the audit trail for partial
+            // overlaps. It is deliberately advisory: an adapter cannot silently change
+            // the counting policy or suppress a contribution through this extension.
+            $adapter_overlap_evidence = [];
+            $adapter_evidence_bytes = 0;
+            $adapter_evidence_total_limit = 65536;
+            $adapter_evidence_candidate_limit = 4096;
+            $adapter_evidence_omitted = 0;
+            if (!$matched_event && $possible_overlap_event && method_exists($adapter, 'get_reconciliation_evidence')) {
+                $overlap_candidates = !empty($possible_overlap_events)
+                    ? $possible_overlap_events
+                    : [$possible_overlap_event];
+                foreach ($overlap_candidates as $candidate_event) {
+                    try {
+                        $adapter_evidence = $adapter->get_reconciliation_evidence(
+                            $origin_key,
+                            $normalized,
+                            $candidate_event
+                        );
+                    } catch (Throwable $exception) {
+                        $adapter_evidence = [
+                            'analysis_status' => 'failed',
+                            'error' => substr(sanitize_text_field($exception->getMessage()), 0, 500),
+                        ];
+                    }
+
+                    if (!is_array($adapter_evidence)) {
+                        $adapter_evidence = ['analysis_status' => 'invalid_result'];
+                    }
+                    $encoded_adapter_evidence = wp_json_encode($adapter_evidence);
+                    $candidate_evidence_size = is_string($encoded_adapter_evidence) ? strlen($encoded_adapter_evidence) : 0;
+                    if (!is_string($encoded_adapter_evidence)) {
+                        $adapter_evidence = [
+                            'analysis_status' => 'rejected',
+                            'reason' => 'Evidence was not JSON serializable.',
+                        ];
+                        $candidate_evidence_size = strlen(wp_json_encode($adapter_evidence));
+                    } elseif ($candidate_evidence_size > $adapter_evidence_candidate_limit) {
+                        $adapter_evidence = [
+                            'analysis_status' => 'rejected',
+                            'reason' => 'Evidence exceeded the 4 KiB per-candidate limit.',
+                            'original_bytes' => $candidate_evidence_size,
+                        ];
+                        $candidate_evidence_size = strlen(wp_json_encode($adapter_evidence));
+                    }
+                    if ($adapter_evidence_bytes + $candidate_evidence_size > $adapter_evidence_total_limit) {
+                        $adapter_evidence_omitted++;
+                        $adapter_evidence = [
+                            'analysis_status' => 'omitted_budget',
+                            'reason' => 'The 64 KiB total adapter-evidence budget was reached.',
+                        ];
+                        $candidate_evidence_size = strlen(wp_json_encode($adapter_evidence));
+                    }
+                    $adapter_evidence_bytes += $candidate_evidence_size;
+                    $candidate_start = isset($candidate_event['period_start']) ? (string) $candidate_event['period_start'] : '';
+                    $candidate_end = isset($candidate_event['period_end']) ? (string) $candidate_event['period_end'] : '';
+                    $incoming_start = (string) $period_start;
+                    $incoming_end = (string) $period_end;
+                    $incoming_has_period = $incoming_start !== '' && $incoming_end !== '';
+                    $candidate_has_period = $candidate_start !== '' && $candidate_end !== '';
+                    // Exact string equality remains a representation-level signal;
+                    // it is not a timezone-safe temporal comparison.
+                    $same_start = $incoming_has_period && $candidate_has_period && $incoming_start === $candidate_start;
+                    $same_end = $incoming_has_period && $candidate_has_period && $incoming_end === $candidate_end;
+                    $incoming_temporal_basis = $this->classify_reconciliation_temporal_basis(
+                        $adapter_key,
+                        $origin_key,
+                        $record_type
+                    );
+                    $candidate_adapter_key = isset($candidate_event['candidate_adapter_key'])
+                        ? sanitize_key((string) $candidate_event['candidate_adapter_key']) : '';
+                    $candidate_record_key = isset($candidate_event['source_record_key'])
+                        ? (string) $candidate_event['source_record_key'] : '';
+                    $candidate_origin_key = '';
+                    if ($candidate_adapter_key === 'pulseviews') {
+                        if (strpos($candidate_record_key, 'pulseviews_day_') === 0) {
+                            $candidate_origin_key = 'daily_aggregates';
+                        } elseif (strpos($candidate_record_key, 'pulseviews_view_') === 0) {
+                            $candidate_origin_key = 'recent_raw_views';
+                        }
+                    }
+                    $candidate_temporal_basis = $this->classify_reconciliation_temporal_basis(
+                        $candidate_adapter_key,
+                        $candidate_origin_key,
+                        isset($candidate_event['record_type']) ? $candidate_event['record_type'] : ''
+                    );
+                    $periods_intersect = false;
+                    $temporal_relation = ($incoming_has_period && $candidate_has_period)
+                        ? 'not_compared_timezone_basis_unverified'
+                        : 'insufficient_temporal_data';
+                    $incoming_precision = 'unknown';
+                    if ($record_type === 'aggregate') {
+                        $incoming_precision = 'aggregate_period';
+                    } elseif ($adapter_key === 'statify') {
+                        $incoming_precision = 'calendar_day';
+                    } elseif (in_array($adapter_key, ['burst_statistics', 'independent_analytics'], true)) {
+                        $incoming_precision = 'seconds';
+                    } elseif ($adapter_key === 'pulseviews') {
+                        $incoming_precision = $origin_key === 'daily_aggregates' ? 'calendar_day' : 'seconds';
+                    } elseif ($record_type === 'event' && $incoming_start !== '' && $incoming_start === $incoming_end) {
+                        $incoming_precision = 'source_event_timestamp_unverified';
+                    }
+                    $candidate_precision = (isset($candidate_event['record_type']) && $candidate_event['record_type'] === 'aggregate')
+                        ? 'aggregate_period'
+                        : ((isset($candidate_event['record_type']) && $candidate_event['record_type'] === 'event' && $candidate_start !== '' && $candidate_start === $candidate_end)
+                            ? 'stored_event_timestamp_unverified'
+                            : 'unknown');
+                    $incoming_granularity = $this->classify_reconciliation_temporal_granularity(
+                        (string) $record_type,
+                        $incoming_start,
+                        $incoming_end,
+                        $incoming_precision
+                    );
+                    $candidate_granularity = $this->classify_reconciliation_temporal_granularity(
+                        isset($candidate_event['record_type']) ? (string) $candidate_event['record_type'] : '',
+                        $candidate_start,
+                        $candidate_end,
+                        $candidate_precision
+                    );
+                    $same_temporal_granularity = $incoming_granularity['granularity'] !== 'unknown'
+                        && $incoming_granularity['granularity'] === $candidate_granularity['granularity'];
+                    $temporal_granularity_relation = $same_temporal_granularity
+                        ? 'same_granularity_temporal_evidence_only'
+                        : (($incoming_granularity['granularity'] !== 'unknown' && $candidate_granularity['granularity'] !== 'unknown')
+                            ? 'different_temporal_granularity'
+                            : 'insufficient_temporal_granularity');
+
+                    $candidate_rank = count($adapter_overlap_evidence) + 1;
+                    $adapter_overlap_evidence[] = [
+                        'candidate_event_id' => (int) $candidate_event['id'],
+                        'candidate_rank' => $candidate_rank,
+                        'is_primary_candidate' => $candidate_rank === 1
+                            && (int) $candidate_event['id'] === (int) $possible_overlap_event['id'],
+                        'discovered_by' => isset($candidate_event['_discovered_by']) ? $candidate_event['_discovered_by'] : [],
+                        'adapter_key' => $adapter_key,
+                        'comparison' => [
+                            'identity_assessment' => [
+                                'candidate_discovery_signals' => isset($candidate_event['_discovered_by'])
+                                    ? array_values((array) $candidate_event['_discovered_by'])
+                                    : [],
+                                'same_explicit_fingerprint_signal' => in_array(
+                                    'fingerprint',
+                                    (array) ($candidate_event['_discovered_by'] ?? []),
+                                    true
+                                ) && $source_fingerprint !== '',
+                                'classification' => (
+                                    in_array('fingerprint', (array) ($candidate_event['_discovered_by'] ?? []), true)
+                                    && $source_fingerprint !== ''
+                                ) ? 'shared_fingerprint_candidate_requires_contract_and_dimension_validation' : 'temporal_or_other_candidate_without_shared_identity',
+                                'identity_proven' => false,
+                                'automatic_suppression_authorized' => false,
+                                'reason' => 'Candidate discovery by a matching fingerprint is a review signal only. Identity is confirmed only by the separate exact-match path, which also requires event type and all normalized dimensions to agree.',
+                            ],
+                            'incoming' => [
+                                'source_id' => (int) $source_id,
+                                'origin_key' => (string) $origin_key,
+                                'product_id' => (int) $product_id,
+                                'record_type' => (string) $record_type,
+                                'observed_views' => (int) $views,
+                                'period_start' => $incoming_start,
+                                'period_end' => $incoming_end,
+                                'temporal_basis' => $incoming_temporal_basis,
+                            ],
+                            'candidate' => [
+                                'source_id' => isset($candidate_event['source_id']) ? (int) $candidate_event['source_id'] : 0,
+                                'source_key' => isset($candidate_event['candidate_source_key']) ? (string) $candidate_event['candidate_source_key'] : null,
+                                'adapter_key' => isset($candidate_event['candidate_adapter_key']) ? (string) $candidate_event['candidate_adapter_key'] : null,
+                                'product_id' => isset($candidate_event['product_id']) ? (int) $candidate_event['product_id'] : 0,
+                                'record_type' => isset($candidate_event['record_type']) ? (string) $candidate_event['record_type'] : '',
+                                'observed_views' => isset($candidate_event['observed_views']) ? (int) $candidate_event['observed_views'] : 0,
+                                'applied_views' => isset($candidate_event['applied_views']) ? (int) $candidate_event['applied_views'] : 0,
+                                'period_start' => $candidate_start,
+                                'period_end' => $candidate_end,
+                                'temporal_basis' => $candidate_temporal_basis,
+                            ],
+                            'temporal_analysis' => [
+                                'incoming_precision' => $incoming_precision,
+                                'candidate_precision' => $candidate_precision,
+                                'relation' => $temporal_relation,
+                                'incoming_basis' => $incoming_temporal_basis,
+                                'candidate_basis' => $candidate_temporal_basis,
+                                'absolute_time_comparison_performed' => false,
+                                'incoming_granularity' => $incoming_granularity,
+                                'candidate_granularity' => $candidate_granularity,
+                                'granularity_relation' => $temporal_granularity_relation,
+                                'same_granularity_is_identity_proof' => false,
+                                'same_granularity_establishes_timezone_compatibility' => false,
+                                'same_period_bounds' => $same_start && $same_end,
+                                'same_instant_bounds' => false,
+                                'same_event_datetime_string_representation' => $same_start && $same_end
+                                    && $record_type === 'event'
+                                    && isset($candidate_event['record_type']) && $candidate_event['record_type'] === 'event',
+                                'same_instant_is_proven' => false,
+                                'interpretation' => 'Temporal similarity is evidence of possible overlap only; it does not establish event identity.',
+                            ],
+                            'signals' => [
+                                'same_product' => isset($candidate_event['product_id']) && (int) $candidate_event['product_id'] === (int) $product_id,
+                                'same_record_type' => isset($candidate_event['record_type']) && (string) $candidate_event['record_type'] === (string) $record_type,
+                                'same_period_start' => $candidate_start !== '' && $candidate_start === $incoming_start,
+                                'same_period_end' => $candidate_end !== '' && $candidate_end === $incoming_end,
+                                'same_observed_view_count' => isset($candidate_event['observed_views']) && (int) $candidate_event['observed_views'] === (int) $views,
+                                'same_explicit_fingerprint_candidate_signal' => in_array('fingerprint', (array) ($candidate_event['_discovered_by'] ?? []), true) && $source_fingerprint !== '',
+                                'periods_intersect' => null,
+                                'same_period_string_representation' => $same_start && $same_end,
+                                'period_string_equality_is_temporal_proof' => false,
+                            ],
+                        ],
+                        'evidence_contract_version' => '1.7.0',
+                        'evidence' => $adapter_evidence,
+                    ];
+                }
+            }
+
+            if ($adapter_evidence_omitted > 0 && !empty($adapter_overlap_evidence)) {
+                $adapter_overlap_evidence[0]['evidence_budget_summary'] = [
+                    'total_limit_bytes' => $adapter_evidence_total_limit,
+                    'candidate_limit_bytes' => $adapter_evidence_candidate_limit,
+                    'omitted_candidates' => $adapter_evidence_omitted,
+                    'stored_evidence_bytes' => $adapter_evidence_bytes,
+                ];
+            }
+
+            $applied_views = $matched_event ? 0 : $views;
+            $inserted = statpl_db_insert($this->view_source_events_table, [
+                'source_id' => $source_id,
+                'source_record_key' => $record_key,
+                'source_record_hash' => $record_hash,
+                'product_id' => $product_id,
+                'record_type' => $record_type,
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'observed_views' => $views,
+                'applied_views' => $applied_views,
+                'source_fingerprint' => $has_exact_event_fingerprint ? $source_fingerprint : null,
+                'status' => $matched_event ? 'reconciled' : ($possible_overlap_event ? 'possible_overlap' : 'applied'),
+                'created_at' => $now,
+                'updated_at' => $now,
+            ]);
+
+            if ($inserted === 1) {
+                $new_event_id = (int) $wpdb->insert_id;
+                // Build the shared audit context for both exact matches and possible
+                // overlaps. The possible-overlap persistence path below also stores
+                // these values, so they must never depend on the exact-match branch.
+                $cross_source_assessment = null;
+                $partial_overlap_profiles = null;
+                $product_source_synthesis = null;
+                $product_reconciliation_summary = null;
+                if ($matched_event || $possible_overlap_event) {
+                    $audit_candidates = !empty($possible_overlap_events)
+                        ? $possible_overlap_events
+                        : ($matched_event ? [$matched_event] : [$possible_overlap_event]);
+                    $cross_source_assessment = $this->build_generic_cross_source_overlap_assessment(
+                        $product_id,
+                        $source_id,
+                        $adapter_key,
+                        $record_type,
+                        $period_start,
+                        $period_end,
+                        $audit_candidates,
+                        $possible_overlap_candidates_truncated,
+                        $views
+                    );
+                    $partial_overlap_profiles = $this->build_generic_partial_overlap_profiles(
+                        $product_id,
+                        $source_id,
+                        $period_start,
+                        $period_end
+                    );
+                    $product_source_synthesis = $this->build_generic_product_source_synthesis($product_id);
+                    $product_reconciliation_summary = $this->build_generic_product_reconciliation_summary(
+                        $product_id,
+                        $cross_source_assessment,
+                        $partial_overlap_profiles,
+                        $product_source_synthesis,
+                        $matched_event,
+                        [
+                            'candidates' => !empty($possible_overlap_events)
+                                ? $possible_overlap_events
+                                : ($matched_event ? [$matched_event] : ($possible_overlap_event ? [$possible_overlap_event] : [])),
+                            'truncated' => $possible_overlap_candidates_truncated,
+                            'observed_count' => $possible_overlap_candidate_count_observed,
+                        ]
+                    );
+                }
+                if ($matched_event) {
+                    $adapter_discovery_evidence_consistency = $this->build_generic_adapter_discovery_evidence_consistency(
+                        $candidate_conflict_assessment,
+                        $adapter_overlap_evidence
+                    );
+
+                    $evidence = wp_json_encode([
+                        'match_type' => 'exact_shared_fingerprint',
+                        'source_id' => $source_id,
+                        'matched_source_id' => (int) $matched_event['source_id'],
+                        'product_id' => $product_id,
+                        'record_type' => $record_type,
+                        'observed_views' => $views,
+                        'period_start' => $period_start,
+                        'period_end' => $period_end,
+                        'source_fingerprint' => $source_fingerprint,
+                        'cross_source_assessment' => $cross_source_assessment,
+                        'partial_overlap_profiles' => $partial_overlap_profiles,
+                        'product_source_synthesis' => $product_source_synthesis,
+                        'product_reconciliation_summary' => $product_reconciliation_summary,
+                        'candidate_set_assessment' => $this->build_generic_candidate_set_assessment(
+                            !empty($possible_overlap_events) ? $possible_overlap_events : [$matched_event],
+                            $possible_overlap_candidates_truncated,
+                            $possible_overlap_candidate_count_observed
+                        ),
+                    ]);
+                    $reconciliation_inserted = statpl_db_insert($this->view_source_reconciliation_table, [
+                        'event_id' => $new_event_id,
+                        'status' => 'matched_exact',
+                        'reason_code' => 'shared_fingerprint_exact_match',
+                        'reason' => 'A different source supplied the same explicit fingerprint and identical normalized event dimensions. This contribution was retained for audit but not added again.',
+                        'matched_event_id' => (int) $matched_event['id'],
+                        'evidence' => $evidence,
+                        'algorithm_version' => '1.0.0',
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ]);
+                    $history_inserted = $reconciliation_inserted === 1 ? statpl_db_insert($this->view_source_reconciliation_history_table, [
+                        'event_id' => $new_event_id,
+                        'previous_status' => null,
+                        'new_status' => 'matched_exact',
+                        'reason_code' => 'shared_fingerprint_exact_match',
+                        'reason' => 'Exact cross-source match using an adapter-provided shared fingerprint and identical normalized dimensions.',
+                        'matched_event_id' => (int) $matched_event['id'],
+                        'evidence' => $evidence,
+                        'algorithm_version' => '1.0.0',
+                        'created_at' => $now,
+                    ]) : false;
+                    if ($reconciliation_inserted !== 1 || $history_inserted !== 1) {
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id,
+                            $origin_key,
+                            $record_key,
+                            $product_id,
+                            'Could not persist cross-source reconciliation evidence: ' . $wpdb->last_error,
+                            $batch_start_checkpoint,
+                            3
+                        , $origin_lock);
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                    break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                }
+                if ($possible_overlap_event) {
+                    $adapter_dimension_evidence_consistency = $this->build_generic_adapter_dimension_evidence_consistency(
+                        $candidate_conflict_assessment,
+                        $adapter_overlap_evidence
+                    );
+                    // Validate that the primary reference, ordered candidate set and
+                    // adapter evidence describe the same candidate identities before
+                    // persisting the reconciliation record.
+                    $primary_candidate_id = (int) $possible_overlap_event['id'];
+                    $candidate_ids = array_values(array_unique(array_map(
+                        static function ($candidate) {
+                            return isset($candidate['id']) ? (int) $candidate['id'] : 0;
+                        },
+                        !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event]
+                    )));
+                    $candidate_ids = array_values(array_filter($candidate_ids, static function ($id) {
+                        return $id > 0;
+                    }));
+                    $candidate_list_primary_consistent = in_array($primary_candidate_id, $candidate_ids, true)
+                        && !empty($candidate_ids)
+                        && $candidate_ids[0] === $primary_candidate_id;
+
+                    $adapter_candidate_ids = array_values(array_map(
+                        static function ($entry) {
+                            return isset($entry['candidate_event_id']) ? (int) $entry['candidate_event_id'] : 0;
+                        },
+                        $adapter_overlap_evidence
+                    ));
+                    $adapter_evidence_primary_consistent = empty($adapter_overlap_evidence)
+                        || (
+                            isset($adapter_overlap_evidence[0]['is_primary_candidate'])
+                            && $adapter_overlap_evidence[0]['is_primary_candidate'] === true
+                            && $adapter_candidate_ids[0] === $primary_candidate_id
+                        );
+                    $adapter_evidence_order_consistent = true;
+                    foreach ($adapter_overlap_evidence as $index => $entry) {
+                        if (
+                            !isset($entry['candidate_rank'], $entry['candidate_event_id'])
+                            || (int) $entry['candidate_rank'] !== $index + 1
+                            || (int) $entry['candidate_event_id'] !== (int) ($candidate_ids[$index] ?? 0)
+                        ) {
+                            $adapter_evidence_order_consistent = false;
+                            break;
+                        }
+                    }
+
+                    $evidence = wp_json_encode([
+                        'match_type' => $possible_overlap_reason_code,
+                        'source_id' => $source_id,
+                        'matched_source_id' => (int) $possible_overlap_event['source_id'],
+                        'matched_event_id' => (int) $possible_overlap_event['id'],
+                        'current' => [
+                            'product_id' => $product_id,
+                            'record_type' => $record_type,
+                            'observed_views' => $views,
+                            'period_start' => $period_start,
+                            'period_end' => $period_end,
+                        ],
+                        'candidates_truncated' => $possible_overlap_candidates_truncated,
+                        'candidate_limit' => 25,
+                        'candidate_count_observed' => $possible_overlap_candidate_count_observed,
+                        'candidate_count_is_lower_bound' => $possible_overlap_candidate_count_is_lower_bound,
+                        'candidate_set_assessment' => $this->build_generic_candidate_set_assessment(
+                            !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event],
+                            $possible_overlap_candidates_truncated,
+                            $possible_overlap_candidate_count_observed
+                        ),
+                        'candidate_conflict_assessment' => $candidate_conflict_assessment = $this->build_generic_candidate_conflict_assessment(
+                            [
+                                'product_id' => $product_id,
+                                'record_type' => $record_type,
+                                'observed_views' => $views,
+                                'period_start' => $period_start,
+                                'period_end' => $period_end,
+                            ],
+                            !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event]
+                        ),
+                        'candidate_evidence_decision' => $candidate_evidence_decision = $this->build_generic_candidate_evidence_decision(
+                            $candidate_conflict_assessment,
+                            $candidate_set_assessment = $this->build_generic_candidate_set_assessment(
+                                !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event],
+                                $possible_overlap_candidates_truncated,
+                                $possible_overlap_candidate_count_observed
+                            ),
+                            $possible_overlap_candidates_truncated
+                        ),
+                        'candidate_audit_consistency' => $this->build_generic_candidate_audit_consistency(
+                            $candidate_set_assessment,
+                            $candidate_conflict_assessment,
+                            $candidate_evidence_decision
+                        ),
+                        'candidate_reference_consistency' => $this->build_generic_candidate_reference_consistency(
+                            $candidate_set_assessment,
+                            $candidate_conflict_assessment
+                        ),
+                        'candidate_discovery_signal_consistency' => $this->build_generic_candidate_discovery_signal_consistency(
+                            $candidate_set_assessment,
+                            $candidate_conflict_assessment
+                        ),
+                        'adapter_discovery_evidence_consistency' => $adapter_discovery_evidence_consistency,
+                        'adapter_dimension_evidence_consistency' => $adapter_dimension_evidence_consistency,
+                        'candidate_consistency' => [
+                            'primary_in_candidate_list' => $candidate_list_primary_consistent,
+                            'adapter_evidence_primary_consistent' => $adapter_evidence_primary_consistent,
+                            'adapter_evidence_order_consistent' => $adapter_evidence_order_consistent,
+                            'adapter_discovery_evidence_consistent' => !empty($adapter_discovery_evidence_consistency['consistent']),
+                            'adapter_dimension_evidence_consistent' => !empty($adapter_dimension_evidence_consistency['consistent']),
+                            'candidate_count' => count($candidate_ids),
+                            'adapter_evidence_candidate_count' => count($adapter_candidate_ids),
+                            'validation_policy' => 'audit_only_no_automatic_count_suppression',
+                        ],
+                        'candidate_reconciliation_chain' => $this->build_generic_candidate_reconciliation_chain_assessment(
+                            $candidate_set_assessment,
+                            $candidate_conflict_assessment,
+                            $candidate_evidence_decision,
+                            $this->build_generic_candidate_audit_consistency(
+                                $candidate_set_assessment,
+                                $candidate_conflict_assessment,
+                                $candidate_evidence_decision
+                            ),
+                            [
+                                'primary_in_candidate_list' => $candidate_list_primary_consistent,
+                                'adapter_evidence_primary_consistent' => $adapter_evidence_primary_consistent,
+                                'adapter_evidence_order_consistent' => $adapter_evidence_order_consistent,
+                                'adapter_discovery_evidence_consistent' => !empty($adapter_discovery_evidence_consistency['consistent']),
+                                'adapter_dimension_evidence_consistent' => !empty($adapter_dimension_evidence_consistency['consistent']),
+                                'candidate_count' => count($candidate_ids),
+                                'adapter_evidence_candidate_count' => count($adapter_candidate_ids),
+                            ],
+                            $this->build_generic_candidate_reference_consistency(
+                                $candidate_set_assessment,
+                                $candidate_conflict_assessment
+                            ),
+                            $this->build_generic_candidate_discovery_signal_consistency(
+                                $candidate_set_assessment,
+                                $candidate_conflict_assessment
+                            )
+                        ),
+                        'primary_candidate' => [
+                            'event_id' => (int) $possible_overlap_event['id'],
+                            'source_id' => (int) $possible_overlap_event['source_id'],
+                            'source_key' => isset($possible_overlap_event['candidate_source_key']) ? (string) $possible_overlap_event['candidate_source_key'] : null,
+                            'adapter_key' => isset($possible_overlap_event['candidate_adapter_key']) ? (string) $possible_overlap_event['candidate_adapter_key'] : null,
+                            'discovered_by' => isset($possible_overlap_event['_discovered_by']) ? $possible_overlap_event['_discovered_by'] : [],
+                            'selection_policy' => 'highest_discovery_evidence_then_lowest_event_id',
+                        ],
+                        'fingerprint_candidates_observed' => $possible_overlap_fingerprint_candidates_observed,
+                        'temporal_candidates_observed' => $possible_overlap_temporal_candidates_observed,
+                        'candidates' => array_map(static function ($candidate) {
+                            return [
+                                'event_id' => (int) $candidate['id'],
+                                'discovered_by' => isset($candidate['_discovered_by']) ? $candidate['_discovered_by'] : [],
+                                'source_id' => (int) $candidate['source_id'],
+                                'source_key' => isset($candidate['candidate_source_key']) ? (string) $candidate['candidate_source_key'] : null,
+                                'adapter_key' => isset($candidate['candidate_adapter_key']) ? (string) $candidate['candidate_adapter_key'] : null,
+                                'product_id' => (int) $candidate['product_id'],
+                                'record_type' => (string) $candidate['record_type'],
+                                'observed_views' => (int) $candidate['observed_views'],
+                                'applied_views' => (int) $candidate['applied_views'],
+                                'period_start' => $candidate['period_start'],
+                                'period_end' => $candidate['period_end'],
+                            ];
+                        }, !empty($possible_overlap_events) ? $possible_overlap_events : [$possible_overlap_event]),
+                        'cross_source_assessment' => $cross_source_assessment,
+                        'partial_overlap_profiles' => $partial_overlap_profiles,
+                        'product_source_synthesis' => $product_source_synthesis,
+                        'product_reconciliation_summary' => $product_reconciliation_summary,
+                        'source_fingerprint' => $source_fingerprint !== '' ? $source_fingerprint : null,
+                        'adapter_overlap_evidence' => $adapter_overlap_evidence,
+                        'counting_policy' => 'preserve_both_pending_source_specific_evidence',
+                    ]);
+                    $reconciliation_inserted = statpl_db_insert($this->view_source_reconciliation_table, [
+                        'event_id' => $new_event_id,
+                        'status' => 'possible_overlap',
+                        'reason_code' => $possible_overlap_reason_code,
+                        'reason' => 'A different source contains one or more potentially overlapping records. All matching candidates were retained as evidence; the contribution was preserved and counted because no automatic suppression was justified without stronger source-specific evidence.',
+                        'matched_event_id' => (int) $possible_overlap_event['id'],
+                        'evidence' => $evidence,
+                        'algorithm_version' => '1.6.0',
+                        'created_at' => $now,
+                        'updated_at' => $now,
+                    ]);
+                    $history_inserted = $reconciliation_inserted === 1 ? statpl_db_insert($this->view_source_reconciliation_history_table, [
+                        'event_id' => $new_event_id,
+                        'previous_status' => null,
+                        'new_status' => 'possible_overlap',
+                        'reason_code' => $possible_overlap_reason_code,
+                        'reason' => 'Potential partial overlap recorded for review. Both source contributions remain counted until source-specific evidence justifies adjustment.',
+                        'matched_event_id' => (int) $possible_overlap_event['id'],
+                        'evidence' => $evidence,
+                        'algorithm_version' => '1.6.0',
+                        'created_at' => $now,
+                    ]) : false;
+                    if ($reconciliation_inserted !== 1 || $history_inserted !== 1) {
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id,
+                            $origin_key,
+                            $record_key,
+                            $product_id,
+                            'Could not persist possible-overlap reconciliation evidence: ' . $wpdb->last_error,
+                            $batch_start_checkpoint,
+                            3
+                        , $origin_lock);
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                    break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                }
+                if ($applied_views > 0) {
+                    $total_result = statpl_db_query(statpl_db_prepare(
+                        "INSERT INTO {$this->views_table} (product_id, total_views) VALUES (%d, %d)
+                         ON DUPLICATE KEY UPDATE total_views = total_views + VALUES(total_views)",
+                        $product_id,
+                        $applied_views
+                    ));
+                    if ($total_result === false) {
+                        if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                        $failed++;
+                        $failure = $this->record_generic_historical_view_failure(
+                            $source_id,
+                            $origin_key,
+                            $record_key,
+                            $product_id,
+                            'Could not update product view totals: ' . $wpdb->last_error,
+                            $batch_start_checkpoint,
+                            3
+                        , $origin_lock);
+                        if (empty($failure['persisted'])) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            $checkpoint_persistence_failed = true;
+                    break;
+                        }
+                        if (!$failure['blocked']) {
+                            $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                        }
+                        continue;
+                    }
+                }
+                $origin_session_current = $this->generic_advisory_lock_session_is_current($origin_lock);
+                $fingerprint_session_current = !is_array($reconciliation_lock_state)
+                    || empty($reconciliation_lock_state['acquired'])
+                    || $this->generic_advisory_lock_session_is_current($reconciliation_lock_state);
+                if (!$origin_session_current || !$fingerprint_session_current) {
+                    // The transaction belongs to the origin-lock connection. A lost
+                    // advisory lock does not itself mean the DB connection changed.
+                    // Never send ROLLBACK to a transparently reconnected session.
+                    if ($transaction_open && !$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    return [
+                        'status' => 'transaction_lock_session_lost',
+                        'processed' => $processed,
+                        'duplicates' => $duplicates,
+                        'failed' => $failed,
+                    ];
+                }
+
+                if (statpl_db_query('COMMIT') === false) {
+                    $commit_error = (string) $wpdb->last_error;
+
+                    // A failed COMMIT acknowledgement is ambiguous when WordPress has
+                    // transparently reconnected: the server may have committed the
+                    // transaction before the client lost its connection. Do not issue
+                    // ledger writes on a replacement session or classify the record
+                    // as failed. Replaying the same record is safe because the source
+                    // event's unique key and transactional totals update are idempotent.
+                    $origin_session_after_commit = $this->generic_advisory_lock_session_is_current($origin_lock);
+                    $fingerprint_session_after_commit = !is_array($reconciliation_lock_state)
+                        || empty($reconciliation_lock_state['acquired'])
+                        || $this->generic_advisory_lock_session_is_current($reconciliation_lock_state);
+                    if (!$origin_session_after_commit || !$fingerprint_session_after_commit) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return [
+                            'status' => 'commit_outcome_unknown',
+                            'processed' => $processed,
+                            'duplicates' => $duplicates,
+                            'failed' => $failed,
+                        ];
+                    }
+
+                    // The original session is still alive, so the failed COMMIT can
+                    // be rolled back and recorded as a normal retryable row failure.
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Could not commit imported source event: ' . $commit_error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                $transaction_open = false;
+                $processed++;
+            } elseif ($inserted === false && stripos((string) $wpdb->last_error, 'duplicate') !== false) {
+                if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                // A repeated source_record_key is idempotent only when the stored
+                // normalized payload is identical. A changed payload under the same
+                // key signals an adapter/source inconsistency and must not be silently
+                // accepted as an ordinary duplicate.
+                $existing_event = statpl_db_get_row(statpl_db_prepare(
+                    "SELECT id, product_id, record_type, observed_views, period_start, period_end, source_fingerprint, status
+                     FROM {$this->view_source_events_table}
+                     WHERE source_id = %d AND source_record_hash = %s
+                     LIMIT 1",
+                    $source_id,
+                    $record_hash
+                ), ARRAY_A);
+                if (!empty($wpdb->last_error) || !is_array($existing_event)) {
+                    $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                    return ['status' => 'duplicate_verification_failed', 'processed' => $processed, 'duplicates' => $duplicates];
+                }
+                $existing_period_start = $existing_event['period_start'] !== null ? (string) $existing_event['period_start'] : null;
+                $existing_period_end = $existing_event['period_end'] !== null ? (string) $existing_event['period_end'] : null;
+                $existing_fingerprint = $existing_event['source_fingerprint'] !== null ? (string) $existing_event['source_fingerprint'] : '';
+                $same_existing_payload = (int) $existing_event['product_id'] === $product_id
+                    && (string) $existing_event['record_type'] === $record_type
+                    && (int) $existing_event['observed_views'] === $views
+                    && $existing_period_start === $period_start
+                    && $existing_period_end === $period_end
+                    && $existing_fingerprint === $source_fingerprint;
+                if ($same_existing_payload) {
+                    // A retry must not rewrite reconciliation evidence or append
+                    // another history row. Verify the already committed audit record
+                    // before accepting the source event as a complete duplicate.
+                    $existing_event_id = isset($existing_event['id']) ? (int) $existing_event['id'] : 0;
+                    $existing_event_status = isset($existing_event['status']) ? (string) $existing_event['status'] : '';
+                    if (in_array($existing_event_status, ['possible_overlap', 'reconciled'], true)) {
+                        $existing_audit = statpl_db_get_row(statpl_db_prepare(
+                            "SELECT status, reason_code, matched_event_id, evidence, algorithm_version
+                             FROM {$this->view_source_reconciliation_table}
+                             WHERE event_id = %d
+                             LIMIT 1",
+                            $existing_event_id
+                        ), ARRAY_A);
+                        if (!empty($wpdb->last_error) || !is_array($existing_audit)) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_missing_or_unreadable',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+                        $existing_audit_evidence = !empty($existing_audit['evidence'])
+                            ? json_decode((string) $existing_audit['evidence'], true)
+                            : null;
+                        $audit_matches_event = is_array($existing_audit_evidence)
+                            && isset($existing_audit_evidence['source_id'])
+                            && (int) $existing_audit_evidence['source_id'] === (int) $source_id;
+                        if ($existing_event_status === 'possible_overlap') {
+                            $audit_matches_event = $audit_matches_event
+                                && isset($existing_audit['matched_event_id'], $existing_audit_evidence['primary_candidate']['event_id'])
+                                && (int) $existing_audit['matched_event_id'] === (int) $existing_audit_evidence['primary_candidate']['event_id']
+                                && (int) $existing_audit_evidence['primary_candidate']['event_id'] > 0;
+                        } elseif ($existing_event_status === 'reconciled') {
+                            $audit_matches_event = $audit_matches_event
+                                && (string) $existing_audit['status'] === 'matched_exact'
+                                && isset($existing_audit['matched_event_id'])
+                                && (int) $existing_audit['matched_event_id'] > 0;
+                        }
+                        if (!$audit_matches_event) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_integrity_mismatch',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+
+                        // The current reconciliation row and its latest history
+                        // snapshot must agree. History is verified, never synthesized
+                        // or repaired during a duplicate retry.
+                        $latest_history = statpl_db_get_row(statpl_db_prepare(
+                            "SELECT new_status, reason_code, matched_event_id, evidence, algorithm_version
+                             FROM {$this->view_source_reconciliation_history_table}
+                             WHERE event_id = %d
+                             ORDER BY id DESC
+                             LIMIT 1",
+                            $existing_event_id
+                        ), ARRAY_A);
+                        if (!empty($wpdb->last_error) || !is_array($latest_history)) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_history_missing_or_unreadable',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+
+                        $history_matches_audit = (string) $latest_history['new_status'] === (string) $existing_audit['status']
+                            && (string) $latest_history['reason_code'] === (string) $existing_audit['reason_code']
+                            && (int) ($latest_history['matched_event_id'] ?? 0) === (int) ($existing_audit['matched_event_id'] ?? 0)
+                            && (string) ($latest_history['evidence'] ?? '') === (string) ($existing_audit['evidence'] ?? '')
+                            && (string) $latest_history['algorithm_version'] === (string) $existing_audit['algorithm_version'];
+
+                        // Validate the recorded transition chain in ascending history
+                        // order. The first row is treated as the chain anchor because
+                        // older installations may not have retained its predecessor.
+                        $history_chain = statpl_db_get_results(statpl_db_prepare(
+                            "SELECT id, previous_status, new_status
+                             FROM {$this->view_source_reconciliation_history_table}
+                             WHERE event_id = %d
+                             ORDER BY id ASC",
+                            $existing_event_id
+                        ), ARRAY_A);
+                        if (!empty($wpdb->last_error) || !is_array($history_chain) || empty($history_chain)) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_history_chain_unreadable',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+
+                        $history_chain_consistent = true;
+                        $previous_new_status = null;
+                        $previous_history_id = 0;
+                        foreach ($history_chain as $history_entry) {
+                            $history_id = isset($history_entry['id']) ? (int) $history_entry['id'] : 0;
+                            $new_status = isset($history_entry['new_status']) ? (string) $history_entry['new_status'] : '';
+                            $previous_status = isset($history_entry['previous_status']) && $history_entry['previous_status'] !== null
+                                ? (string) $history_entry['previous_status']
+                                : null;
+
+                            if ($history_id <= $previous_history_id || $new_status === '') {
+                                $history_chain_consistent = false;
+                                break;
+                            }
+                            if ($previous_new_status !== null && $previous_status !== $previous_new_status) {
+                                $history_chain_consistent = false;
+                                break;
+                            }
+                            $previous_new_status = $new_status;
+                            $previous_history_id = $history_id;
+                        }
+
+                        if (!$history_chain_consistent) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_history_transition_chain_mismatch',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+
+                        if (!$history_matches_audit) {
+                            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                            return [
+                                'status' => 'duplicate_audit_history_integrity_mismatch',
+                                'processed' => $processed,
+                                'duplicates' => $duplicates,
+                            ];
+                        }
+                    }
+                    $duplicates++;
+                } else {
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'The adapter returned different normalized data for an existing source record key. The original imported event was preserved.',
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                        break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+                } else {
+                    $error = (string) $wpdb->last_error;
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    $failed++;
+                    $failure = $this->record_generic_historical_view_failure(
+                        $source_id,
+                        $origin_key,
+                        $record_key,
+                        $product_id,
+                        'Could not persist source event: ' . $error,
+                        $batch_start_checkpoint,
+                        3
+                    , $origin_lock);
+                    if (empty($failure['persisted'])) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        $checkpoint_persistence_failed = true;
+                    break;
+                    }
+                    if (!$failure['blocked']) {
+                        $this->schedule_generic_historical_failure_retry($failure['retry_delay'], $source_id, $origin_key);
+                    }
+                    continue;
+                }
+            } finally {
+                if ($transaction_open) {
+                    // A changed or unverifiable session means the original transaction
+                    // outcome cannot be inspected here. Do not issue transaction control
+                    // on a replacement connection; ensure the record is retried instead.
+                    if (!$this->generic_db_session_matches_lock($origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                    if (!$this->rollback_generic_import_transaction($transaction_open, $origin_lock)) {
+                        $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                        return ['status' => 'rollback_outcome_unknown', 'processed' => $processed, 'duplicates' => $duplicates, 'failed' => $failed];
+                    }
+                }
+                if (is_array($reconciliation_lock_state) && !empty($reconciliation_lock_state['acquired'])) {
+                    $this->release_generic_advisory_lock($reconciliation_lock_state, 'cross_source_fingerprint');
+                }
+            }
+
+            $failure_cleared = $this->clear_generic_historical_view_failure($source_id, $origin_key, $record_key, $origin_lock);
+            if ($failure_cleared && is_array($record) && !empty($record['source_record_key']) && (string) $record['source_record_key'] !== $record_key) {
+                $failure_cleared = $this->clear_generic_historical_view_failure($source_id, $origin_key, $record['source_record_key'], $origin_lock, null);
+            } elseif ($failure_cleared && (!is_array($record) || empty($record['source_record_key']))) {
+                $failure_cleared = $this->clear_generic_historical_view_failure($source_id, $origin_key, wp_json_encode($record), $origin_lock, null);
+            }
+            if (!$failure_cleared) {
+                // The event may already be committed. Idempotency makes replay
+                // safe, but the cursor must not move beyond this record until
+                // its stale failure-ledger entries have been cleared.
+                $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+                $checkpoint_persistence_failed = true;
+                break;
+            }
+            $next_checkpoint['cursor'] = $cursor;
+            $next_checkpoint['processed'] = isset($next_checkpoint['processed']) ? (int) $next_checkpoint['processed'] + 1 : 1;
+            unset($normalization_error);
+        }
+
+        if ($checkpoint_persistence_failed) {
+            // Do not persist the adapter's batch-level next_checkpoint when a
+            // row could not be durably represented in the failure ledger. The
+            // next main-import attempt must revisit this batch and this row.
+            return [
+                'status' => 'failure_ledger_persist_failed',
+                'processed' => $processed,
+                'duplicates' => $duplicates,
+                'failed' => $failed,
+                'skipped' => $skipped,
+            ];
+        }
+
+        // A connection can be transparently re-established after a mid-batch DB outage.
+        // Never persist checkpoint/status progress unless this request still owns the
+        // original origin lock session that serialized the batch.
+        if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return [
+                'status' => 'checkpoint_blocked_origin_lock_session_lost',
+                'processed' => $processed,
+                'duplicates' => $duplicates,
+                'failed' => $failed,
+                'skipped' => $skipped,
+            ];
+        }
+
+        // Individual bad records have been durably placed in the failure ledger.
+        // Continue advancing the main batch checkpoint; a separate replay worker
+        // revisits the saved batch checkpoint without blocking later records.
+        if ($retry_checkpoint_override !== null) {
+            return [
+                'status' => $failed ? 'retry_replay_partial' : 'retry_replay_completed',
+                'processed' => $processed,
+                'duplicates' => $duplicates,
+                'failed' => $failed,
+            ];
+        }
+
+        if (isset($batch['next_checkpoint'])) {
+            $next_checkpoint['cursor'] = $batch['next_checkpoint'];
+        }
+        $has_more = !empty($batch['has_more']);
+        $failure_counts = statpl_db_get_row(statpl_db_prepare(
+            "SELECT SUM(CASE WHEN status = 'retry' THEN 1 ELSE 0 END) AS pending,
+                    SUM(CASE WHEN status = 'blocked' THEN 1 ELSE 0 END) AS blocked
+             FROM {$this->view_source_failures_table} WHERE source_id = %d AND origin_key = %s",
+            $source_id,
+            $origin_key
+        ), ARRAY_A);
+        if (!empty($wpdb->last_error) || !is_array($failure_counts)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'failure_ledger_read_failed', 'processed' => $processed, 'duplicates' => $duplicates];
+        }
+        $pending_failures = (int) $failure_counts['pending'];
+        $blocked_failures = (int) $failure_counts['blocked'];
+        $origin_status = $has_more ? 'importing' : (($pending_failures > 0 || $blocked_failures > 0) ? ($blocked_failures > 0 ? 'needs_attention' : 'retry_wait') : 'completed');
+        if (!$this->generic_advisory_lock_session_is_current($origin_lock)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'checkpoint_blocked_origin_lock_session_lost', 'processed' => $processed, 'duplicates' => $duplicates];
+        }
+
+        $updates = [
+            'checkpoint_data' => $next_checkpoint,
+            'last_error' => ($pending_failures > 0 || $blocked_failures > 0) ? 'One or more historical records remain unresolved; the main import continues independently.' : null,
+            'status' => $origin_status,
+        ];
+        if (!$has_more && $pending_failures === 0 && $blocked_failures === 0) {
+            $updates['completed_at'] = current_time('mysql');
+        } else {
+            $updates['completed_at'] = null;
+        }
+        $saved = $this->update_view_source_origin_state($source_id, $origin_key, $updates, $origin_lock);
+        if (empty($saved['status']) || $saved['status'] !== 'updated') {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return ['status' => 'checkpoint_write_failed', 'processed' => $processed, 'duplicates' => $duplicates];
+        }
+
+        // A successful statpl_db_query() confirms that MySQL accepted the UPDATE,
+        // but a worker must not report durable progress until the exact state is
+        // readable again. This also handles ambiguous acknowledgements and
+        // storage-layer anomalies without advancing the scheduler to the next
+        // batch on an unverified checkpoint.
+        $persisted_state = $this->get_view_source_origin_state($source_id, $origin_key);
+        $checkpoint_is_persisted = isset($persisted_state['status'])
+            && $persisted_state['status'] === 'found'
+            && isset($persisted_state['checkpoint'])
+            && wp_json_encode($persisted_state['checkpoint']) === wp_json_encode($next_checkpoint)
+            && isset($persisted_state['origin_status'])
+            && $persisted_state['origin_status'] === $origin_status;
+        $completion_is_persisted = array_key_exists('completed_at', $updates)
+            && ((array_key_exists('completed_at', $persisted_state) && $updates['completed_at'] === null && $persisted_state['completed_at'] === null)
+                || (array_key_exists('completed_at', $persisted_state) && $updates['completed_at'] !== null && $persisted_state['completed_at'] === $updates['completed_at']));
+        if (!$checkpoint_is_persisted || !$completion_is_persisted || !$this->generic_advisory_lock_session_is_current($origin_lock)) {
+            $this->schedule_generic_historical_view_import_batch(60, $source_id, $origin_key);
+            return [
+                'status' => 'checkpoint_write_unverified',
+                'processed' => $processed,
+                'duplicates' => $duplicates,
+            ];
+        }
+
+        if ($has_more) {
+            $this->schedule_generic_historical_view_import_batch(5, $source_id, $origin_key);
+        }
+        if ($pending_failures > 0) {
+            $this->schedule_generic_historical_failure_retry(60, $source_id, $origin_key);
+        }
+        return [
+            'status' => $has_more ? 'batch_completed' : ($pending_failures > 0 ? 'completed_with_pending_retries' : ($blocked_failures > 0 ? 'completed_with_unresolved_records' : 'completed')),
+            'processed' => $processed,
+            'duplicates' => $duplicates,
+            'checkpoint' => $next_checkpoint,
+        ];
+    }
+
+    private function register_view_source($source_key, $display_name, $adapter_version, $granularity, $status = 'detected', $adapter_key = null) {
+        global $wpdb;
+
+        $source_key = (string) $source_key;
+        $display_name = sanitize_text_field($display_name);
+        $adapter_version = sanitize_text_field($adapter_version);
+        $granularity = (string) $granularity;
+        $status = (string) $status;
+        $adapter_key = $adapter_key === null ? null : sanitize_key((string) $adapter_key);
+
+        if (
+            ($adapter_key !== null && ($adapter_key === '' || strlen($adapter_key) > 100))
+            ||
+            !preg_match('/^[a-z0-9_-]{1,100}$/D', $source_key)
+            || $display_name === ''
+            || $adapter_version === ''
+            || !preg_match('/^[a-z0-9_-]{1,20}$/D', $granularity)
+            || !preg_match('/^[a-z0-9_-]{1,20}$/D', $status)
+            || strlen($display_name) > 191
+            || strlen($adapter_version) > 32
+        ) {
+            return [
+                'status' => 'invalid_input',
+                'source_id' => 0,
+            ];
+        }
+
+        $now = current_time('mysql');
+
+        $result = statpl_db_query(statpl_db_prepare(
+            "INSERT INTO {$this->view_sources_table}
+                (source_key, adapter_key, display_name, adapter_version, granularity, status, created_at, updated_at)
+             VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+             ON DUPLICATE KEY UPDATE
+                display_name = IF(VALUES(adapter_key) IS NULL OR adapter_key IS NULL OR adapter_key = VALUES(adapter_key), VALUES(display_name), display_name),
+                adapter_version = IF(VALUES(adapter_key) IS NULL OR adapter_key IS NULL OR adapter_key = VALUES(adapter_key), VALUES(adapter_version), adapter_version),
+                granularity = IF(VALUES(adapter_key) IS NULL OR adapter_key IS NULL OR adapter_key = VALUES(adapter_key), VALUES(granularity), granularity),
+                updated_at = IF(VALUES(adapter_key) IS NULL OR adapter_key IS NULL OR adapter_key = VALUES(adapter_key), VALUES(updated_at), updated_at)",
+            $source_key,
+            $adapter_key,
+            $display_name,
+            $adapter_version,
+            $granularity,
+            $status,
+            $now,
+            $now
+        ));
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return [
+                'status' => 'database_error',
+                'source_id' => 0,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        $source_id = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT id FROM {$this->view_sources_table} WHERE source_key = %s",
+                $source_key
+            )
+        );
+
+        if (!empty($wpdb->last_error) || !$source_id) {
+            return [
+                'status' => 'database_error',
+                'source_id' => 0,
+                'error' => $wpdb->last_error !== ''
+                    ? $wpdb->last_error
+                    : 'Registered source ID could not be retrieved.',
+            ];
+        }
+
+        if ($adapter_key !== null) {
+            $ownership_result = statpl_db_query(
+                statpl_db_prepare(
+                    "UPDATE {$this->view_sources_table}
+                     SET adapter_key = %s
+                     WHERE id = %d AND (adapter_key IS NULL OR adapter_key = %s)",
+                    $adapter_key,
+                    (int) $source_id,
+                    $adapter_key
+                )
+            );
+            if ($ownership_result === false || $wpdb->last_error !== '') {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => 0,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+
+            $stored_adapter_key = statpl_db_get_var(statpl_db_prepare(
+                "SELECT adapter_key FROM {$this->view_sources_table} WHERE id = %d",
+                (int) $source_id
+            ));
+            if ($wpdb->last_error !== '') {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => 0,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+            if ((string) $stored_adapter_key !== $adapter_key) {
+                return [
+                    'status' => 'adapter_mismatch',
+                    'source_id' => 0,
+                ];
+            }
+        }
+
+        return [
+            'status' => 'registered',
+            'source_id' => (int) $source_id,
+        ];
+    }
+
+    private function register_view_source_origin($source_id, $origin_key, $adapter_key, $capabilities = [], $detection_status = 'unknown') {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = (string) $origin_key;
+        $adapter_key = (string) $adapter_key;
+        $detection_status = (string) $detection_status;
+
+        if (
+            !$source_id
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $adapter_key)
+            || !in_array($detection_status, ['unknown', 'available', 'missing_table', 'incompatible_schema', 'database_error'], true)
+            || !is_array($capabilities)
+        ) {
+            return [
+                'status' => 'invalid_input',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $source_exists = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT id FROM {$this->view_sources_table} WHERE id = %d",
+                $source_id
+            )
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        if (!$source_exists) {
+            return [
+                'status' => 'source_not_found',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        // An adapter identity is part of the immutable meaning of an origin's
+        // snapshot and checkpoint. Never silently replace it after initialization.
+        $existing_origin = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT adapter_key, snapshot_data, checkpoint_data, status
+                 FROM {$this->view_source_origins_table}
+                 WHERE source_id = %d AND origin_key = %s",
+                $source_id,
+                $origin_key
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        $existing_source_events = 0;
+        $existing_origin_failures = 0;
+        if (is_array($existing_origin) && isset($existing_origin['adapter_key']) && (string) $existing_origin['adapter_key'] !== $adapter_key) {
+            $existing_source_events = (int) statpl_db_get_var(statpl_db_prepare(
+                "SELECT COUNT(*) FROM {$this->view_source_events_table} WHERE source_id = %d",
+                $source_id
+            ));
+            if (!empty($wpdb->last_error)) {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+            $existing_origin_failures = (int) statpl_db_get_var(statpl_db_prepare(
+                "SELECT COUNT(*) FROM {$this->view_source_failures_table} WHERE source_id = %d AND origin_key = %s",
+                $source_id,
+                $origin_key
+            ));
+            if (!empty($wpdb->last_error)) {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+        }
+
+        if (
+            is_array($existing_origin)
+            && isset($existing_origin['adapter_key'])
+            && (string) $existing_origin['adapter_key'] !== $adapter_key
+            && (
+                !empty($existing_origin['snapshot_data'])
+                || !empty($existing_origin['checkpoint_data'])
+                || !in_array($existing_origin['status'], ['pending', 'unavailable'], true)
+                || $existing_source_events > 0
+                || $existing_origin_failures > 0
+            )
+        ) {
+            $message = sprintf(
+                'Historical adapter identity changed from "%1$s" to "%2$s" after this origin was initialized. Existing historical data and checkpoints were preserved; the replacement adapter was not allowed to reinterpret them.',
+                sanitize_key((string) $existing_origin['adapter_key']),
+                sanitize_key($adapter_key)
+            );
+            // A replacement adapter cannot safely inherit the old adapter's
+            // snapshot or checkpoint. Keep the origin automatically unavailable
+            // (rather than requiring administrator intervention), while normal
+            // discovery continues to look for the original adapter. If that
+            // original identity returns, the ordinary registration path can resume
+            // from the preserved checkpoint without reinterpreting historical data.
+            statpl_db_update(
+                $this->view_source_origins_table,
+                [
+                    'status' => 'unavailable',
+                    'last_error' => $message,
+                    'updated_at' => current_time('mysql'),
+                ],
+                [
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                ],
+                ['%s', '%s', '%s'],
+                ['%d', '%s']
+            );
+            if (!empty($wpdb->last_error)) {
+                return [
+                    'status' => 'database_error',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'error' => $wpdb->last_error,
+                ];
+            }
+            return [
+                'status' => 'adapter_mismatch',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $capabilities_json = wp_json_encode($capabilities);
+
+        if (!is_string($capabilities_json)) {
+            return [
+                'status' => 'invalid_capabilities',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $now = current_time('mysql');
+
+        $result = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->view_source_origins_table}
+                    (source_id, origin_key, adapter_key, capabilities, detection_status, status, updated_at)
+                 VALUES (%d, %s, %s, %s, %s, %s, %s)
+                 ON DUPLICATE KEY UPDATE
+                    adapter_key = VALUES(adapter_key),
+                    capabilities = VALUES(capabilities),
+                    detection_status = %s,
+                    status = CASE
+                        WHEN VALUES(detection_status) <> 'available' AND status NOT IN ('completed', 'needs_attention') THEN 'unavailable'
+                        WHEN VALUES(detection_status) = 'available' AND status = 'unavailable' THEN 'pending'
+                        ELSE status
+                    END,
+                    updated_at = %s",
+                $source_id,
+                $origin_key,
+                $adapter_key,
+                $capabilities_json,
+                $detection_status,
+                $detection_status === 'available' ? 'pending' : 'unavailable',
+                $now,
+                $detection_status,
+                $now
+            )
+        );
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return [
+                'status' => 'database_error',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        return [
+            'status' => 'registered',
+            'source_id' => $source_id,
+            'origin_key' => $origin_key,
+        ];
+    }
+
+    private function get_view_source_origin_state($source_id, $origin_key) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = is_string($origin_key) ? trim($origin_key) : '';
+
+        if (
+            !$source_id
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+        ) {
+            return [
+                'status' => 'invalid_input',
+            ];
+        }
+
+        $row = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT
+                    source_id,
+                    origin_key,
+                    adapter_key,
+                    capabilities,
+                    snapshot_data,
+                    checkpoint_data,
+                    detection_status,
+                    status,
+                    last_error,
+                    started_at,
+                    completed_at,
+                    updated_at
+                 FROM {$this->view_source_origins_table}
+                 WHERE source_id = %d
+                   AND origin_key = %s",
+                $source_id,
+                $origin_key
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        if (!$row) {
+            return [
+                'status' => 'not_found',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $capabilities = null;
+        if ($row['capabilities'] !== null && $row['capabilities'] !== '') {
+            $capabilities = json_decode($row['capabilities'], true);
+            if (json_last_error() !== JSON_ERROR_NONE) {
+                return [
+                    'status' => 'invalid_stored_data',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'field' => 'capabilities',
+                ];
+            }
+        }
+
+        $snapshot = null;
+        if ($row['snapshot_data'] !== null && $row['snapshot_data'] !== '') {
+            $snapshot = json_decode($row['snapshot_data'], true);
+            if (json_last_error() !== JSON_ERROR_NONE) {
+                return [
+                    'status' => 'invalid_stored_data',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'field' => 'snapshot_data',
+                ];
+            }
+        }
+
+        $checkpoint = null;
+        if ($row['checkpoint_data'] !== null && $row['checkpoint_data'] !== '') {
+            $checkpoint = json_decode($row['checkpoint_data'], true);
+            if (json_last_error() !== JSON_ERROR_NONE) {
+                return [
+                    'status' => 'invalid_stored_data',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                    'field' => 'checkpoint_data',
+                ];
+            }
+        }
+
+        return [
+            'status' => 'found',
+            'source_id' => (int) $row['source_id'],
+            'origin_key' => $row['origin_key'],
+            'adapter_key' => $row['adapter_key'],
+            'capabilities' => $capabilities,
+            'snapshot' => $snapshot,
+            'checkpoint' => $checkpoint,
+            'detection_status' => $row['detection_status'],
+            'origin_status' => $row['status'],
+            'last_error' => $row['last_error'],
+            'started_at' => $row['started_at'],
+            'completed_at' => $row['completed_at'],
+            'updated_at' => $row['updated_at'],
+        ];
+    }
+
+    private function update_view_source_origin_state($source_id, $origin_key, $updates, $lock_context = null) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = is_string($origin_key) ? trim($origin_key) : '';
+
+        if (
+            !$source_id
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+            || !is_array($updates)
+            || empty($updates)
+        ) {
+            return [
+                'status' => 'invalid_input',
+            ];
+        }
+
+        $allowed_fields = [
+            'snapshot_data',
+            'checkpoint_data',
+            'status',
+            'last_error',
+            'started_at',
+            'completed_at',
+        ];
+
+        $columns = [];
+        $values = [];
+
+        foreach ($updates as $field => $value) {
+            if (!in_array($field, $allowed_fields, true)) {
+                return [
+                    'status' => 'invalid_field',
+                    'field' => $field,
+                ];
+            }
+
+            if (in_array($field, ['snapshot_data', 'checkpoint_data'], true)) {
+                if ($value !== null && !is_array($value)) {
+                    return [
+                        'status' => 'invalid_input',
+                        'field' => $field,
+                    ];
+                }
+
+                $encoded = $value === null ? null : wp_json_encode($value);
+
+                if ($value !== null && !is_string($encoded)) {
+                    return [
+                        'status' => 'encoding_error',
+                        'field' => $field,
+                    ];
+                }
+
+                $columns[] = "`{$field}` = %s";
+                $values[] = $encoded;
+                continue;
+            }
+
+            if ($field === 'status') {
+                if (
+                    !is_string($value)
+                    || !preg_match('/^[a-z0-9_-]{1,20}$/D', $value)
+                ) {
+                    return [
+                        'status' => 'invalid_input',
+                        'field' => $field,
+                    ];
+                }
+
+                $columns[] = "`{$field}` = %s";
+                $values[] = $value;
+                continue;
+            }
+
+            if ($field === 'last_error') {
+                if ($value !== null && !is_string($value)) {
+                    return [
+                        'status' => 'invalid_input',
+                        'field' => $field,
+                    ];
+                }
+
+                $columns[] = "`{$field}` = %s";
+                $values[] = $value;
+                continue;
+            }
+
+            if ($value !== null && (
+                !is_string($value)
+                || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $value)
+            )) {
+                return [
+                    'status' => 'invalid_input',
+                    'field' => $field,
+                ];
+            }
+
+            $columns[] = "`{$field}` = %s";
+            $values[] = $value;
+        }
+
+        $columns[] = '`updated_at` = %s';
+        $values[] = current_time('mysql');
+
+        $values[] = $source_id;
+        $values[] = $origin_key;
+
+        $lock_name = '';
+        if ($lock_context !== null) {
+            if (!$this->generic_advisory_lock_session_is_current($lock_context) || empty($lock_context['lock_name'])) {
+                return ['status' => 'lock_session_lost'];
+            }
+            $lock_name = (string) $lock_context['lock_name'];
+        }
+        // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- The optional lock predicate and its matching lock-name argument are both added only when lock_context is present.
+        $lock_predicate = $lock_context !== null ? ' AND IS_USED_LOCK(%s) = CONNECTION_ID()' : '';
+        if ($lock_context !== null) {
+            $values[] = $lock_name;
+        }
+        // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- SET placeholders and values are appended together from the validated origin-state field allowlist; source_id/origin_key and the optional lock placeholder are appended to the values in matching order.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+        $result = statpl_db_query(/* phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- Placeholder fragments and their values are assembled together from the same fixed allowlists; optional lock predicates and matching values are added together. */ statpl_db_prepare(
+            "UPDATE {$this->view_source_origins_table}
+             SET " . implode(', ', /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $columns) . "
+             WHERE source_id = %d AND origin_key = %s" . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $lock_predicate,
+            ...$values
+        ));
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return [
+                'status' => 'database_error',
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        if ($result === 0) {
+            if ($lock_context !== null && !$this->generic_advisory_lock_session_is_current($lock_context)) {
+                return ['status' => 'lock_session_lost'];
+            }
+            $exists = statpl_db_get_var(
+                statpl_db_prepare(
+                    "SELECT 1 FROM {$this->view_source_origins_table}
+                     WHERE source_id = %d AND origin_key = %s",
+                    $source_id,
+                    $origin_key
+                )
+            );
+
+            if (!empty($wpdb->last_error)) {
+                return [
+                    'status' => 'database_error',
+                    'error' => $wpdb->last_error,
+                ];
+            }
+
+            // The existence read can itself trigger a transparent wpdb reconnect.
+            // Revalidate the original lock session after that read before treating
+            // a zero-row UPDATE as a successful no-op. Otherwise a replacement
+            // connection could make an unperformed state transition look complete.
+            if ($lock_context !== null && !$this->generic_advisory_lock_session_is_current($lock_context)) {
+                return ['status' => 'lock_session_lost'];
+            }
+
+            if (!$exists) {
+                return [
+                    'status' => 'not_found',
+                    'source_id' => $source_id,
+                    'origin_key' => $origin_key,
+                ];
+            }
+        }
+
+        return [
+            'status' => 'updated',
+            'source_id' => $source_id,
+            'origin_key' => $origin_key,
+        ];
+    }
+
+    private function save_view_source_origin_snapshot_if_empty($source_id, $origin_key, $snapshot) {
+        global $wpdb;
+
+        $source_id = absint($source_id);
+        $origin_key = is_string($origin_key) ? trim($origin_key) : '';
+
+        if (
+            !$source_id
+            || !preg_match('/^[a-z0-9_-]{1,100}$/D', $origin_key)
+            || !is_array($snapshot)
+            || empty($snapshot)
+        ) {
+            return [
+                'status' => 'invalid_input',
+            ];
+        }
+
+        $encoded = wp_json_encode($snapshot);
+
+        if (!is_string($encoded)) {
+            return [
+                'status' => 'encoding_error',
+            ];
+        }
+
+        $result = statpl_db_query(
+            statpl_db_prepare(
+                "UPDATE {$this->view_source_origins_table}
+                 SET snapshot_data = %s, updated_at = %s
+                 WHERE source_id = %d
+                 AND origin_key = %s
+                 AND snapshot_data IS NULL",
+                $encoded,
+                current_time('mysql'),
+                $source_id,
+                $origin_key
+            )
+        );
+
+        if ($result === false || $wpdb->last_error !== '') {
+            return [
+                'status' => 'database_error',
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        if ($result === 1) {
+            return [
+                'status' => 'updated',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $existing = $this->get_view_source_origin_state($source_id, $origin_key);
+
+        if ($existing['status'] !== 'found') {
+            return $existing;
+        }
+
+        if ($existing['snapshot'] !== null) {
+            return [
+                'status' => 'already_initialized',
+                'source_id' => $source_id,
+                'origin_key' => $origin_key,
+                'snapshot' => $existing['snapshot'],
+            ];
+        }
+
+        return [
+            'status' => 'database_error',
+            'source_id' => $source_id,
+            'origin_key' => $origin_key,
+        ];
+    }
+
+    private function initialize_view_source_origin_snapshot($source_id, $origin_key) {
+        global $wpdb;
+
+        $state = $this->get_view_source_origin_state($source_id, $origin_key);
+
+        if ($state['status'] !== 'found') {
+            return $state;
+        }
+
+        if (!empty($state['snapshot'])) {
+            return [
+                'status' => 'already_initialized',
+                'source_id' => (int) $source_id,
+                'origin_key' => $origin_key,
+                'snapshot' => $state['snapshot'],
+            ];
+        }
+
+        if ($state['detection_status'] !== 'available') {
+            return [
+                'status' => 'origin_unavailable',
+                'source_id' => (int) $source_id,
+                'origin_key' => $origin_key,
+                'detection_status' => $state['detection_status'],
+            ];
+        }
+
+        $origin_tables = [
+            'slim_stats' => $wpdb->prefix . 'slim_stats',
+            'slim_stats_archive' => $wpdb->prefix . 'slim_stats_archive',
+        ];
+
+        if (!isset($origin_tables[$origin_key])) {
+            return [
+                'status' => 'unsupported_origin',
+                'source_id' => (int) $source_id,
+                'origin_key' => $origin_key,
+            ];
+        }
+
+        $table = $origin_tables[$origin_key];
+
+        $max_id = statpl_db_get_var(
+            "SELECT MAX(id) FROM `{$table}`"
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'source_id' => (int) $source_id,
+                'origin_key' => $origin_key,
+                'error' => $wpdb->last_error,
+            ];
+        }
+
+        $snapshot = [
+            'max_id' => $max_id === null ? 0 : (int) $max_id,
+            'captured_at' => current_time('mysql'),
+        ];
+
+        $saved = $this->save_view_source_origin_snapshot_if_empty(
+            $source_id,
+            $origin_key,
+            $snapshot
+        );
+
+        if ($saved['status'] === 'already_initialized') {
+            return $saved;
+        }
+
+        if ($saved['status'] !== 'updated') {
+            return $saved;
+        }
+
+        return [
+            'status' => 'initialized',
+            'source_id' => (int) $source_id,
+            'origin_key' => $origin_key,
+            'snapshot' => $snapshot,
+        ];
+    }
+
+    private function save_view_source_origin_snapshot($source_id, $origin_key, $snapshot) {
+        if (!is_array($snapshot) || empty($snapshot)) {
+            return [
+                'status' => 'invalid_snapshot',
+            ];
+        }
+
+        return $this->update_view_source_origin_state(
+            $source_id,
+            $origin_key,
+            [
+                'snapshot_data' => $snapshot,
+            ]
+        );
+    }
+
+    private function save_view_source_origin_checkpoint($source_id, $origin_key, $checkpoint) {
+        if (!is_array($checkpoint) || empty($checkpoint)) {
+            return [
+                'status' => 'invalid_checkpoint',
+            ];
+        }
+
+        return $this->update_view_source_origin_state(
+            $source_id,
+            $origin_key,
+            [
+                'checkpoint_data' => $checkpoint,
+            ]
+        );
+    }
+
+    private function detect_slimstat_view_origins() {
+        global $wpdb;
+
+        $origins = [
+            'slim_stats' => $wpdb->prefix . 'slim_stats',
+            'slim_stats_archive' => $wpdb->prefix . 'slim_stats_archive',
+        ];
+
+        $required_columns = [
+            'id',
+            'content_type',
+            'content_id',
+            'dt',
+        ];
+
+        $results = [];
+
+        foreach ($origins as $origin_key => $table) {
+            $exists = statpl_db_get_var(
+                statpl_db_prepare(
+                    'SHOW TABLES LIKE %s',
+                    $wpdb->esc_like($table)
+                )
+            );
+
+            if (!empty($wpdb->last_error)) {
+                $results[$origin_key] = [
+                    'status' => 'database_error',
+                    'error' => $wpdb->last_error,
+                ];
+                continue;
+            }
+
+            if ($exists !== $table) {
+                $results[$origin_key] = [
+                    'status' => 'missing_table',
+                ];
+                continue;
+            }
+
+            $columns = statpl_db_get_col(
+                "SHOW COLUMNS FROM `{$table}`",
+                0
+            );
+
+            if (!empty($wpdb->last_error)) {
+                $results[$origin_key] = [
+                    'status' => 'database_error',
+                    'error' => $wpdb->last_error,
+                ];
+                continue;
+            }
+
+            $missing_columns = array_values(
+                array_diff($required_columns, $columns)
+            );
+
+            if (!empty($missing_columns)) {
+                $results[$origin_key] = [
+                    'status' => 'incompatible_schema',
+                    'missing_columns' => $missing_columns,
+                ];
+                continue;
+            }
+
+            $results[$origin_key] = [
+                'status' => 'available',
+                'capabilities' => [
+                    'historical_views' => true,
+                    'record_id' => true,
+                    'product_reference' => true,
+                    'event_timestamp' => true,
+                ],
+            ];
+        }
+
+        return $results;
+    }
+
+    private function initialize_slimstat_view_source_origins() {
+        $registration = $this->register_slimstat_view_source();
+
+        if (
+            !in_array($registration['status'], ['registered', 'partial'], true)
+            || empty($registration['source']['source_id'])
+        ) {
+            return [
+                'status' => 'registration_failed',
+                'registration' => $registration,
+                'origins' => [],
+            ];
+        }
+
+        $source_id = (int) $registration['source']['source_id'];
+        $origins = [];
+        $initialization_failed = false;
+        $available_origins = 0;
+
+        foreach ($registration['origins'] as $origin_key => $origin_data) {
+            $origin_registration = isset($origin_data['registration'])
+                ? $origin_data['registration']
+                : [];
+
+            if (($origin_registration['status'] ?? '') !== 'registered') {
+                $origins[$origin_key] = [
+                    'status' => 'registration_failed',
+                    'registration' => $origin_registration,
+                ];
+                $initialization_failed = true;
+                continue;
+            }
+
+            $detection_status = $origin_data['detection']['status'] ?? 'unknown';
+
+            if ($detection_status !== 'available') {
+                $origins[$origin_key] = [
+                    'status' => 'skipped',
+                    'reason' => $detection_status,
+                ];
+                continue;
+            }
+
+            $available_origins++;
+
+            $result = $this->initialize_view_source_origin_snapshot(
+                $source_id,
+                $origin_key
+            );
+
+            $origins[$origin_key] = $result;
+
+            if (!in_array(
+                $result['status'],
+                ['initialized', 'already_initialized'],
+                true
+            )) {
+                $initialization_failed = true;
+            }
+        }
+
+        if ($available_origins === 0 && !$initialization_failed) {
+            $status = 'no_available_origins';
+        } else {
+            $status = $initialization_failed ? 'partial' : 'initialized';
+        }
+
+        return [
+            'status' => $status,
+            'source_id' => $source_id,
+            'registration' => $registration,
+            'origins' => $origins,
+        ];
+    }
+
+    private function register_slimstat_view_source() {
+        $source = $this->register_view_source(
+            'slimstat',
+            'SlimStat',
+            '1.0.0',
+            'event',
+            'registered'
+        );
+
+        if ($source['status'] !== 'registered' || empty($source['source_id'])) {
+            return [
+                'status' => 'source_registration_failed',
+                'source' => $source,
+                'origins' => [],
+            ];
+        }
+
+        $source_id = (int) $source['source_id'];
+        $detected_origins = $this->detect_slimstat_view_origins();
+        $origins = [];
+        $registration_failed = false;
+
+        foreach ($detected_origins as $origin_key => $detection) {
+            $capabilities = isset($detection['capabilities'])
+                ? $detection['capabilities']
+                : [];
+
+            $registration = $this->register_view_source_origin(
+                $source_id,
+                $origin_key,
+                'slimstat',
+                $capabilities,
+                in_array($detection['status'], ['unknown', 'available', 'missing_table', 'incompatible_schema', 'database_error'], true)
+                    ? $detection['status']
+                    : 'unknown'
+            );
+
+            $origins[$origin_key] = [
+                'detection' => $detection,
+                'registration' => $registration,
+            ];
+
+            if ($registration['status'] !== 'registered') {
+                $registration_failed = true;
+            }
+        }
+
+        return [
+            'status' => $registration_failed ? 'partial' : 'registered',
+            'source' => $source,
+            'origins' => $origins,
+        ];
+    }
+
+    private function detect_slimstat_source() {
+    global $wpdb;
+
+    // Check whether SlimStat is installed and loaded.
+    if (!class_exists('wp_slimstat', false)) {
+        return [
+            'status' => 'not_installed',
+        ];
+    }
+
+    // SlimStat source tables.
+    $tables = [
+        'active'  => $wpdb->prefix . 'slim_stats',
+        'archive' => $wpdb->prefix . 'slim_stats_archive',
+    ];
+
+    $missing_tables = [];
+
+    // Check that both tables exist.
+    foreach ($tables as $key => $table) {
+        $exists = statpl_db_get_var(
+            statpl_db_prepare(
+                'SHOW TABLES LIKE %s',
+                $wpdb->esc_like($table)
+            )
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+            ];
+        }
+
+        if ($exists !== $table) {
+            $missing_tables[] = $table;
+        }
+    }
+
+    if (!empty($missing_tables)) {
+        return [
+            'status'  => 'missing_tables',
+            'missing' => $missing_tables,
+        ];
+    }
+
+    // Required columns for historical product-view import.
+    $required_columns = [
+        'id',
+        'content_type',
+        'content_id',
+        'dt',
+    ];
+
+    $incompatible_tables = [];
+
+    // Check the required schema in both tables.
+    foreach ($tables as $key => $table) {
+        $columns = statpl_db_get_col(
+            "SHOW COLUMNS FROM `{$table}`",
+            0
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+            ];
+        }
+
+        $missing_columns = array_diff(
+            $required_columns,
+            $columns
+        );
+
+        if (!empty($missing_columns)) {
+            $incompatible_tables[$table] = array_values(
+                $missing_columns
+            );
+        }
+    }
+
+    if (!empty($incompatible_tables)) {
+        return [
+            'status'          => 'incompatible_schema',
+            'missing_columns' => $incompatible_tables,
+        ];
+    }
+
+    return [
+        'status' => 'available',
+        'tables' => $tables,
+    ];
+}
+    private function get_slimstat_view_snapshot() {
+    global $wpdb;
+
+    $source = $this->detect_slimstat_source();
+
+    if ($source['status'] !== 'available') {
+        return $source;
+    }
+
+    $snapshot = [];
+
+    foreach ($source['tables'] as $key => $table) {
+        $max_id = statpl_db_get_var(
+    statpl_db_prepare(
+        "SELECT MAX(id) FROM `{$table}` WHERE content_type = %s",
+        'cpt:product'
+      )
+   );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+            ];
+        }
+
+        $snapshot[$key] = (int) $max_id;
+    }
+
+    return [
+        'status'   => 'available',
+        'snapshot' => $snapshot,
+    ];
+}
+private function initialize_slimstat_view_import() {
+    global $wpdb;
+
+    $existing = statpl_db_get_var(
+        statpl_db_prepare(
+            "SELECT source FROM {$this->view_import_state_table} WHERE source = %s",
+            'slimstat'
+        )
+    );
+
+    if (!empty($wpdb->last_error)) {
+        return [
+            'status' => 'database_error',
+        ];
+    }
+
+    if ($existing === 'slimstat') {
+        return [
+            'status' => 'already_initialized',
+        ];
+    }
+
+    $result = $this->get_slimstat_view_snapshot();
+
+    if ($result['status'] !== 'available') {
+        return $result;
+    }
+
+    $inserted = statpl_db_query(
+        statpl_db_prepare(
+            "INSERT IGNORE INTO {$this->view_import_state_table}
+            (source, snapshot_max_id, snapshot_active_max_id, snapshot_archive_max_id, last_processed_id, status, updated_at)
+        VALUES (%s, %d, %d, %d, %d, %s, %s)",
+                       'slimstat',
+                       max($result['snapshot']['active'], $result['snapshot']['archive']),
+                       $result['snapshot']['active'],
+                       $result['snapshot']['archive'],
+                       0,
+                       'pending',
+                       current_time('mysql')
+        )
+    );
+
+    if (false === $inserted) {
+        return [
+            'status' => 'database_error',
+        ];
+    }
+
+    if (0 === $inserted) {
+        $existing = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT source FROM {$this->view_import_state_table} WHERE source = %s",
+                'slimstat'
+            )
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+            ];
+        }
+
+        if ($existing === 'slimstat') {
+            return [
+                'status' => 'already_initialized',
+            ];
+        }
+
+        return [
+            'status' => 'insert_not_confirmed',
+        ];
+    }
+
+    return [
+        'status' => 'initialized',
+        'snapshot' => $result['snapshot'],
+    ];
+}
+
+    /**
+     * Retrieve the next historical SlimStat product-view batch.
+     * This method is read-only: it never changes the checkpoint or import tables.
+     */
+    private function get_slimstat_view_import_batch($last_processed_id, $batch_size = 50) {
+        global $wpdb;
+
+        $state = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT snapshot_active_max_id, snapshot_archive_max_id
+                 FROM {$this->view_import_state_table}
+                 WHERE source = %s",
+                'slimstat'
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'rows'   => [],
+            ];
+        }
+
+        if (!is_array($state)) {
+            return [
+                'status' => 'state_missing',
+                'rows'   => [],
+            ];
+        }
+
+        $active_max_id  = (int) $state['snapshot_active_max_id'];
+        $archive_max_id = (int) $state['snapshot_archive_max_id'];
+        $last_processed_id = max(0, (int) $last_processed_id);
+        $batch_size = max(1, min(500, (int) $batch_size));
+
+        $active_table  = $wpdb->prefix . 'slim_stats';
+        $archive_table = $wpdb->prefix . 'slim_stats_archive';
+
+        $sql = "
+            SELECT id, product_id, dt, source
+            FROM (
+                SELECT
+                    s.id AS id,
+                    s.content_id AS product_id,
+                    s.dt AS dt,
+                    'active' AS source
+                FROM `{$active_table}` s
+                WHERE s.content_type = %s
+                  AND s.id > %d
+                  AND s.id <= %d
+
+                UNION ALL
+
+                SELECT
+                    a.id AS id,
+                    a.content_id AS product_id,
+                    a.dt AS dt,
+                    'archive' AS source
+                FROM `{$archive_table}` a
+                WHERE a.content_type = %s
+                  AND a.id > %d
+                  AND a.id <= %d
+                  AND NOT EXISTS (
+                      SELECT 1
+                      FROM `{$active_table}` s
+                      WHERE s.id = a.id
+                        AND s.id <= %d
+                  )
+            ) AS combined
+            ORDER BY id ASC
+            LIMIT %d
+        ";
+
+        // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $sql is a fixed SQL template with value placeholders; execution below passes it through statpl_db_prepare() with the complete value list.
+        $rows = statpl_db_get_results(
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            statpl_db_prepare(
+                /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $sql,
+                'cpt:product',
+                $last_processed_id,
+                $active_max_id,
+                'cpt:product',
+                $last_processed_id,
+                $archive_max_id,
+                $active_max_id,
+                $batch_size
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return [
+                'status' => 'database_error',
+                'rows'   => [],
+            ];
+        }
+
+        return [
+            'status' => 'available',
+            'rows'   => is_array($rows) ? $rows : [],
+        ];
+    }
+
+    /**
+     * Import one historical SlimStat product-view event idempotently.
+     *
+     * The event ledger is the unique source of truth. A guarded multi-table
+     * update applies the metrics and marks the event in one atomic statement.
+     *
+     * The caller is responsible for checkpoint progression and retry handling.
+     *
+     * @param array $row Historical SlimStat source row.
+     * @return string imported|duplicate|failed
+     */
+    private function import_slimstat_view_event($row) {
+        global $wpdb;
+
+        if (
+            !is_array($row)
+            || !isset($row['id'], $row['product_id'])
+        ) {
+            return 'failed';
+        }
+
+        $source_view_id = (int) $row['id'];
+        $product_id = (int) $row['product_id'];
+
+        if ($source_view_id <= 0 || $product_id <= 0) {
+            return 'failed';
+        }
+
+        $now = current_time('mysql');
+
+        // Insert the event as unapplied. Repeating this insert is harmless.
+        $ledger_inserted = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->view_import_events_table}
+                (source, source_view_id, product_id, imported_at, counts_applied)
+                VALUES (%s, %d, %d, %s, 0)
+                ON DUPLICATE KEY UPDATE
+                    source_view_id = VALUES(source_view_id)",
+                'slimstat',
+                $source_view_id,
+                $product_id,
+                $now
+            )
+        );
+
+        if (false === $ledger_inserted) {
+            return 'failed';
+        }
+
+        // Verify the existing event identity; never reassign it to another product.
+        $event = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT product_id, counts_applied
+                FROM {$this->view_import_events_table}
+                WHERE source = %s AND source_view_id = %d",
+                'slimstat',
+                $source_view_id
+            ),
+            ARRAY_A
+        );
+
+        if (
+            !is_array($event)
+            || !isset($event['product_id'], $event['counts_applied'])
+            || (int) $event['product_id'] !== $product_id
+        ) {
+            return 'failed';
+        }
+
+        if (1 === (int) $event['counts_applied']) {
+            return 'duplicate';
+        }
+
+        // Ensure both metric rows exist. These writes are safe to repeat.
+        $total_ready = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->views_table}
+                (product_id, total_views)
+                VALUES (%d, 0)
+                ON DUPLICATE KEY UPDATE product_id = VALUES(product_id)",
+                $product_id
+            )
+        );
+
+        if (false === $total_ready) {
+            return 'failed';
+        }
+
+        $aggregate_ready = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->view_imports_table}
+                (source, product_id, imported_views, imported_at)
+                VALUES (%s, %d, 0, %s)
+                ON DUPLICATE KEY UPDATE product_id = VALUES(product_id)",
+                'slimstat',
+                $product_id,
+                $now
+            )
+        );
+
+        if (false === $aggregate_ready) {
+            return 'failed';
+        }
+
+        /*
+         * Apply all three changes atomically.
+         * Replaying this statement cannot increment the metrics twice.
+         */
+        $metrics_updated = statpl_db_query(
+            statpl_db_prepare(
+                "UPDATE {$this->views_table} t
+                INNER JOIN {$this->view_imports_table} i
+                    ON i.source = %s AND i.product_id = t.product_id
+                INNER JOIN {$this->view_import_events_table} e
+                    ON e.source = %s
+                    AND e.source_view_id = %d
+                    AND e.product_id = t.product_id
+                SET
+                    t.total_views = t.total_views + 1,
+                    i.imported_views = i.imported_views + 1,
+                    i.imported_at = %s,
+                    e.counts_applied = 1
+                WHERE t.product_id = %d
+                  AND e.counts_applied = 0",
+                'slimstat',
+                'slimstat',
+                $source_view_id,
+                $now,
+                $product_id
+            )
+        );
+
+        if (false === $metrics_updated) {
+            return 'failed';
+        }
+
+        if (3 === $metrics_updated) {
+            delete_transient('statpl_global_summary_v2');
+            return 'imported';
+        }
+
+        // Verify an ambiguous or concurrent result using the durable marker.
+        if (0 === $metrics_updated) {
+            $event = statpl_db_get_row(
+                statpl_db_prepare(
+                    "SELECT product_id, counts_applied
+                    FROM {$this->view_import_events_table}
+                    WHERE source = %s AND source_view_id = %d",
+                    'slimstat',
+                    $source_view_id
+                ),
+                ARRAY_A
+            );
+
+            if (
+                is_array($event)
+                && isset($event['product_id'], $event['counts_applied'])
+                && (int) $event['product_id'] === $product_id
+                && 1 === (int) $event['counts_applied']
+            ) {
+                delete_transient('statpl_global_summary_v2');
+                return 'duplicate';
+            }
+        }
+
+        return 'failed';
+    }
+
+
+    /** Persist an initial SlimStat import failure without counting a replay as another attempt. */
+    private function record_slimstat_view_import_failure($row, $error) {
+        global $wpdb;
+
+        $source_view_id = isset($row['id']) ? absint($row['id']) : 0;
+        $product_id = isset($row['product_id']) ? absint($row['product_id']) : 0;
+
+        if ($source_view_id < 1) {
+            return false;
+        }
+
+        $error = substr(wp_strip_all_tags((string) $error), 0, 4000);
+        if ($error === '') {
+            $error = 'SlimStat historical view could not be imported.';
+        }
+
+        $result = statpl_db_query(
+            statpl_db_prepare(
+                "INSERT INTO {$this->view_import_failures_table}
+                    (source, source_view_id, product_id, attempts, last_error, status, updated_at)
+                 VALUES (%s, %d, %d, 1, %s, 'retry', %s)
+                 ON DUPLICATE KEY UPDATE last_error = VALUES(last_error)",
+                'slimstat',
+                $source_view_id,
+                $product_id,
+                $error,
+                current_time('mysql')
+            )
+        );
+
+        if (false === $result) {
+            return false;
+        }
+        $this->save_historical_import_report_record('slimstat', 'SlimStat', 'slimstat', hash('sha256', "slimstat\0" . $source_view_id), 'retry', 1, 'record_import_failed');
+
+        $failure = statpl_db_get_row(
+            statpl_db_prepare(
+                "SELECT product_id
+                 FROM {$this->view_import_failures_table}
+                 WHERE source = %s AND source_view_id = %d",
+                'slimstat',
+                $source_view_id
+            ),
+            ARRAY_A
+        );
+
+        return empty($wpdb->last_error)
+            && is_array($failure)
+            && isset($failure['product_id'])
+            && (int) $failure['product_id'] === $product_id;
+    }
+
+    /** Process independently due SlimStat retries. */
+    private function process_slimstat_view_import_retries($lock = null) {
+        global $wpdb;
+
+        // Retry processing is part of the same serialized worker as the main
+        // batch. Verify ownership per event, not merely before and after the
+        // entire retry loop, because a transparent reconnect can occur midway.
+        if (!$this->slimstat_import_lock_is_current($lock)) {
+            return false;
+        }
+
+        $now = current_time('mysql');
+
+        $failures = statpl_db_get_results(
+            statpl_db_prepare(
+                "SELECT id, source_view_id, product_id, attempts
+                 FROM {$this->view_import_failures_table}
+                 WHERE source = %s
+                   AND status = 'retry'
+                   AND (
+                       (attempts = 1 AND updated_at <= DATE_SUB(%s, INTERVAL 1 MINUTE))
+                       OR
+                       (attempts = 2 AND updated_at <= DATE_SUB(%s, INTERVAL 2 MINUTE))
+                   )
+                 ORDER BY updated_at ASC
+                 LIMIT 50",
+                'slimstat',
+                $now,
+                $now
+            ),
+            ARRAY_A
+        );
+
+        if (!empty($wpdb->last_error) || !is_array($failures)) {
+            return false;
+        }
+
+        foreach ($failures as $failure) {
+            if (!$this->slimstat_import_lock_is_current($lock)) {
+                return false;
+            }
+
+            $result = $this->import_slimstat_view_event([
+                'id'         => (int) $failure['source_view_id'],
+                'product_id' => (int) $failure['product_id'],
+            ]);
+
+            // The event may have committed immediately before a DB reconnect.
+            // Its counts_applied marker makes replay safe, but no retry-ledger
+            // mutation may continue on a replacement session without the lock.
+            if (!$this->slimstat_import_lock_is_current($lock)) {
+                return false;
+            }
+
+            if (in_array($result, ['imported', 'duplicate'], true)) {
+                $this->save_historical_import_report_record('slimstat', 'SlimStat', 'slimstat', hash('sha256', "slimstat\0" . (int) $failure['source_view_id']), 'imported', (int) $failure['attempts'], '');
+                $deleted = statpl_db_delete(
+                    $this->view_import_failures_table,
+                    [
+                        'id'     => (int) $failure['id'],
+                        'source' => 'slimstat',
+                    ],
+                    ['%d', '%s']
+                );
+
+                if (false === $deleted || !$this->slimstat_import_lock_is_current($lock)) {
+                    return false;
+                }
+
+                continue;
+            }
+
+            $error = !empty($wpdb->last_error)
+                ? $wpdb->last_error
+                : 'SlimStat historical view retry failed.';
+
+            $updated = statpl_db_query(
+                statpl_db_prepare(
+                    "UPDATE {$this->view_import_failures_table}
+                     SET
+                         status = IF(attempts >= 2, 'failed', 'retry'),
+                         attempts = attempts + 1,
+                         last_error = %s,
+                         updated_at = %s
+                     WHERE id = %d
+                       AND source = %s
+                       AND status = 'retry'
+                       AND attempts < 3",
+                    substr(wp_strip_all_tags((string) $error), 0, 4000),
+                    current_time('mysql'),
+                    (int) $failure['id'],
+                    'slimstat'
+                )
+            );
+
+            if (1 !== $updated || !$this->slimstat_import_lock_is_current($lock)) {
+                return false;
+            }
+            $this->save_historical_import_report_record('slimstat', 'SlimStat', 'slimstat', hash('sha256', "slimstat\0" . (int) $failure['source_view_id']), ((int) $failure['attempts'] >= 2 ? 'failed' : 'retry'), (int) $failure['attempts'] + 1, 'record_import_failed');
+        }
+
+        return $this->slimstat_import_lock_is_current($lock);
+    }
+
+    /** Return the delay until the earliest pending SlimStat retry. */
+    private function get_slimstat_view_import_retry_delay() {
+        global $wpdb;
+
+        $delay = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT GREATEST(
+                    5,
+                    TIMESTAMPDIFF(
+                        SECOND,
+                        %s,
+                        CASE
+                            WHEN attempts = 1 THEN DATE_ADD(updated_at, INTERVAL 1 MINUTE)
+                            ELSE DATE_ADD(updated_at, INTERVAL 2 MINUTE)
+                        END
+                    )
+                 )
+                 FROM {$this->view_import_failures_table}
+                 WHERE source = %s AND status = 'retry'
+                 ORDER BY
+                    CASE
+                        WHEN attempts = 1 THEN DATE_ADD(updated_at, INTERVAL 1 MINUTE)
+                        ELSE DATE_ADD(updated_at, INTERVAL 2 MINUTE)
+                    END ASC
+                 LIMIT 1",
+                current_time('mysql'),
+                'slimstat'
+            )
+        );
+
+        if (!empty($wpdb->last_error)) {
+            return 60;
+        }
+
+        return null === $delay ? 5 : max(5, (int) $delay);
+    }
+
+    /** Advance the SlimStat checkpoint only after the current row is durably resolved. */
+    private function update_slimstat_view_import_checkpoint($expected_id, $next_id, $lock) {
+        global $wpdb;
+
+        $expected_id = max(0, (int) $expected_id);
+        $next_id = max(0, (int) $next_id);
+
+        if ($next_id <= $expected_id) {
+            return $this->slimstat_import_lock_is_current($lock);
+        }
+        if (!$this->slimstat_import_lock_is_current($lock)) {
+            return false;
+        }
+
+        // Enforce ownership inside the checkpoint UPDATE itself. This closes
+        // the check/write race if wpdb reconnects between separate statements.
+        $updated = statpl_db_query(
+            statpl_db_prepare(
+                "UPDATE {$this->view_import_state_table}
+                 SET last_processed_id = %d, updated_at = %s
+                 WHERE source = %s AND last_processed_id = %d
+                   AND CONNECTION_ID() = %s
+                   AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+                $next_id,
+                current_time('mysql'),
+                'slimstat',
+                $expected_id,
+                (string) $lock['connection_id'],
+                (string) $lock['lock_name']
+            )
+        );
+
+        return 1 === $updated && $this->slimstat_import_lock_is_current($lock);
+    }
+
+    /** Capture and verify the exact MySQL session that owns the SlimStat import lock. */
+    private function acquire_slimstat_import_lock($lock_name) {
+        global $wpdb;
+        try {
+            $row = statpl_db_get_row(statpl_db_prepare(
+                'SELECT CONNECTION_ID() AS connection_id, GET_LOCK(%s, 0) AS lock_acquired',
+                (string) $lock_name
+            ), ARRAY_A);
+        } catch (Throwable $exception) {
+            return ['acquired' => false, 'error' => $exception->getMessage()];
+        }
+        if (!is_array($row) || !empty($wpdb->last_error)
+            || (string) ($row['lock_acquired'] ?? '') !== '1'
+            || empty($row['connection_id'])) {
+            return ['acquired' => false, 'error' => (string) $wpdb->last_error];
+        }
+        return [
+            'acquired' => true,
+            'connection_id' => (string) $row['connection_id'],
+            'lock_name' => (string) $lock_name,
+        ];
+    }
+
+    /** Verify both connection identity and actual ownership of the SlimStat lock. */
+    private function slimstat_import_lock_is_current($lock) {
+        global $wpdb;
+        if (!is_array($lock) || empty($lock['acquired'])
+            || empty($lock['connection_id']) || empty($lock['lock_name'])) {
+            return false;
+        }
+        try {
+            $row = statpl_db_get_row(statpl_db_prepare(
+                'SELECT CONNECTION_ID() AS connection_id, IS_USED_LOCK(%s) AS lock_owner',
+                (string) $lock['lock_name']
+            ), ARRAY_A);
+        } catch (Throwable $exception) {
+            return false;
+        }
+        return is_array($row) && empty($wpdb->last_error)
+            && (string) ($row['connection_id'] ?? '') === (string) $lock['connection_id']
+            && (string) ($row['lock_owner'] ?? '') === (string) $lock['connection_id'];
+    }
+
+    /** Release the SlimStat lock only through the original lock-owning session. */
+    private function release_slimstat_import_lock($lock) {
+        global $wpdb;
+        if (!$this->slimstat_import_lock_is_current($lock)) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: SlimStat advisory lock session changed before release.');
+            }
+            return false;
+        }
+        try {
+            $released = statpl_db_get_var(statpl_db_prepare(
+                'SELECT RELEASE_LOCK(%s)', (string) $lock['lock_name']
+            ));
+            return (string) $released === '1' && empty($wpdb->last_error);
+        } catch (Throwable $exception) {
+            if (defined('WP_DEBUG') && WP_DEBUG) {
+                $this->debug_log('Statora Plus: SlimStat advisory lock release failed: ' . $exception->getMessage());
+            }
+            return false;
+        }
+    }
+
+    /** Execute one protected SlimStat historical import batch. */
+    public function run_slimstat_view_import_batch() {
+        global $wpdb;
+
+        // MySQL advisory lock names must remain within the server's 64-character limit.
+        $lock_name = 'statpl_view_import_' . substr(md5($wpdb->prefix), 0, 32);
+
+        $slimstat_lock = $this->acquire_slimstat_import_lock($lock_name);
+
+        if (empty($slimstat_lock['acquired'])) {
+            $this->schedule_slimstat_view_import_batch(
+                !empty($wpdb->last_error) ? 60 : 15
+            );
+            return;
+        }
+
+        try {
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            $state = statpl_db_get_row(
+                statpl_db_prepare(
+                    "SELECT snapshot_max_id, last_processed_id, status
+                     FROM {$this->view_import_state_table}
+                     WHERE source = %s",
+                    'slimstat'
+                ),
+                ARRAY_A
+            );
+
+            if (!empty($wpdb->last_error)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            if (!is_array($state)) {
+                return;
+            }
+
+            if (!in_array($state['status'], ['pending', 'running'], true)) {
+                return;
+            }
+
+            $state_updated = statpl_db_query(
+                statpl_db_prepare(
+                    "UPDATE {$this->view_import_state_table}
+                     SET status = 'running', updated_at = %s
+                     WHERE source = %s AND status IN ('pending', 'running')
+                       AND CONNECTION_ID() = %s
+                       AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+                    current_time('mysql'),
+                    'slimstat',
+                    (string) $slimstat_lock['connection_id'],
+                    (string) $slimstat_lock['lock_name']
+                )
+            );
+
+            if (false === $state_updated) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            // Retry previously failed rows independently of the sequential source batch.
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            if (!$this->process_slimstat_view_import_retries($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                // A retry may have committed its event before a transparent DB
+                // reconnect. Its durable event marker makes replay safe, but this
+                // worker must not advance the sequential checkpoint on a new session.
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            $checkpoint = (int) $state['last_processed_id'];
+            $snapshot_max_id = (int) $state['snapshot_max_id'];
+
+            $batch = $this->get_slimstat_view_import_batch($checkpoint, 50);
+
+            if (
+                !is_array($batch)
+                || !isset($batch['status'], $batch['rows'])
+                || 'available' !== $batch['status']
+                || !is_array($batch['rows'])
+            ) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            foreach ($batch['rows'] as $row) {
+                if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+                // A checkpoint replay must not consume another import attempt.
+                $existing_failure = statpl_db_get_row(
+                    statpl_db_prepare(
+                        "SELECT product_id, status
+                         FROM {$this->view_import_failures_table}
+                         WHERE source = %s AND source_view_id = %d",
+                        'slimstat',
+                        (int) $row['id']
+                    ),
+                    ARRAY_A
+                );
+
+                if (!empty($wpdb->last_error)) {
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+
+                if (is_array($existing_failure)) {
+                    if ((int) $existing_failure['product_id'] !== (int) $row['product_id']) {
+                        $this->debug_log(
+                            'Statora Plus: SlimStat failure ledger product ID mismatch for source event '
+                            . (int) $row['id']
+                        );
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+
+                    if (!in_array($existing_failure['status'], ['retry', 'failed'], true)) {
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+
+                    // The failure is already durable; wait for its independent retry.
+                    $next_id = (int) $row['id'];
+
+                    if (!$this->slimstat_import_lock_is_current($slimstat_lock)
+                        || !$this->update_slimstat_view_import_checkpoint($checkpoint, $next_id, $slimstat_lock)) {
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+
+                    $checkpoint = $next_id;
+                    continue;
+                }
+
+                $result = $this->import_slimstat_view_event($row);
+
+                if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                    // The event helper may have completed its atomic metric update
+                    // just before a connection loss. Do not move the checkpoint;
+                    // replay is protected by counts_applied and the unique event key.
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+
+                if (in_array($result, ['imported', 'duplicate'], true)) {
+                    $this->save_historical_import_report_record('slimstat', 'SlimStat', 'slimstat', hash('sha256', "slimstat\0" . (int) $row['id']), 'imported', is_array($existing_failure) ? (int) ($existing_failure['attempts'] ?? 0) : 0, '');
+                    // A previous retry record is no longer needed after confirmed success.
+                    $deleted = statpl_db_delete(
+                        $this->view_import_failures_table,
+                        [
+                            'source'        => 'slimstat',
+                            'source_view_id' => (int) $row['id'],
+                        ],
+                        ['%s', '%d']
+                    );
+
+                    if (false === $deleted) {
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+                } else {
+                    // Capture the helper's SQL error before executing another database query.
+                    $error = !empty($wpdb->last_error)
+                        ? $wpdb->last_error
+                        : 'SlimStat historical view could not be imported.';
+
+                    if (!$this->record_slimstat_view_import_failure($row, $error)) {
+                        $this->schedule_slimstat_view_import_batch(60);
+                        return;
+                    }
+                }
+
+                $next_id = (int) $row['id'];
+
+                if (!$this->slimstat_import_lock_is_current($slimstat_lock)
+                    || !$this->update_slimstat_view_import_checkpoint($checkpoint, $next_id, $slimstat_lock)) {
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+
+                $checkpoint = $next_id;
+            }
+
+            if (!empty($batch['rows'])) {
+                $this->schedule_slimstat_view_import_batch(5);
+                return;
+            }
+
+            // An empty successful source query means the snapshot has been exhausted.
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            if ($checkpoint < $snapshot_max_id) {
+                if (!$this->update_slimstat_view_import_checkpoint($checkpoint, $snapshot_max_id, $slimstat_lock)) {
+                    $this->schedule_slimstat_view_import_batch(60);
+                    return;
+                }
+
+                $checkpoint = $snapshot_max_id;
+            }
+
+            $failure_counts = statpl_db_get_row(
+                statpl_db_prepare(
+                    "SELECT
+                        SUM(CASE WHEN status = 'retry' THEN 1 ELSE 0 END) AS pending_retries,
+                        SUM(CASE WHEN status = 'failed' THEN 1 ELSE 0 END) AS terminal_failures
+                     FROM {$this->view_import_failures_table}
+                     WHERE source = %s",
+                    'slimstat'
+                ),
+                ARRAY_A
+            );
+
+            if (!empty($wpdb->last_error) || !is_array($failure_counts)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+
+            $pending_retries = (int) $failure_counts['pending_retries'];
+            $terminal_failures = (int) $failure_counts['terminal_failures'];
+
+            if ($pending_retries > 0) {
+                $this->schedule_slimstat_view_import_batch(
+                    $this->get_slimstat_view_import_retry_delay()
+                );
+                return;
+            }
+
+            if (!$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+                return;
+            }
+            $final_status = $terminal_failures > 0 ? 'error' : 'complete';
+
+            $finalized = statpl_db_query(
+                statpl_db_prepare(
+                    "UPDATE {$this->view_import_state_table}
+                     SET status = %s, updated_at = %s
+                     WHERE source = %s AND status IN ('pending', 'running')
+                       AND CONNECTION_ID() = %s
+                       AND IS_USED_LOCK(%s) = CONNECTION_ID()",
+                    $final_status,
+                    current_time('mysql'),
+                    'slimstat',
+                    (string) $slimstat_lock['connection_id'],
+                    (string) $slimstat_lock['lock_name']
+                )
+            );
+
+            if (1 !== $finalized || !$this->slimstat_import_lock_is_current($slimstat_lock)) {
+                $this->schedule_slimstat_view_import_batch(60);
+            }
+        } finally {
+            // Release only through the original connection. If WordPress transparently
+            // reconnected, MySQL has already released the old session's advisory lock.
+            $this->release_slimstat_import_lock($slimstat_lock);
+        }
+    }
+
+    /** Schedule one independent SlimStat view import batch. */
+    public function schedule_slimstat_view_import_batch($delay = 10) {
+        global $wpdb;
+
+        $status = statpl_db_get_var(
+            statpl_db_prepare(
+                "SELECT status FROM {$this->view_import_state_table} WHERE source = %s",
+                'slimstat'
+            )
+        );
+
+        if (!empty($wpdb->last_error) || !in_array($status, ['pending', 'running'], true)) {
+            return;
+        }
+
+        $delay = max(5, (int) $delay);
+
+        if (function_exists('as_schedule_single_action') && !did_action('action_scheduler_init')) {
+            add_action('action_scheduler_init', [$this, 'schedule_slimstat_view_import_batch'], 10, 0);
+            return;
+        }
+
+        if (
+            did_action('action_scheduler_init')
+            && class_exists('ActionScheduler')
+            && class_exists('ActionScheduler_Store')
+            && null !== ActionScheduler::store()->query_action(
+                [
+                    'hook'    => 'statpl_view_import_batch',
+                    'status'  => ActionScheduler_Store::STATUS_PENDING,
+                    'group'   => 'statpl-plus',
+                    'args'    => [],
+                    'orderby' => 'none',
+                ]
+            )
+        ) {
+            return;
+        }
+
+        if (function_exists('as_schedule_single_action') && did_action('action_scheduler_init')) {
+            $action_id = as_schedule_single_action(
+                time() + $delay,
+                'statpl_view_import_batch',
+                [],
+                'statpl-plus'
+            );
+
+            if ($action_id) {
+                return;
+            }
+        }
+
+        if (!wp_next_scheduled('statpl_view_import_batch')) {
+            wp_schedule_single_event(time() + $delay, 'statpl_view_import_batch');
+        }
+    }
+
     /** Schedule one import batch with a delay to avoid overlapping batch execution. */
     public function schedule_import_batch($delay = 10) {
@@ -645 +10105 @@
         $args = array_merge([$since,$since,$since], $ids);
         // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Query is prepared with all variable values; table name is a class property built from the WordPress table prefix and fixed suffix; event counts must be current.
-        $rows = $wpdb->get_results($wpdb->prepare($sql, $args), ARRAY_A);
+        $rows = statpl_db_get_results(statpl_db_prepare($sql, $args), ARRAY_A);
         foreach ($rows as $r) {
             $id = (int)$r['product_id']; if (!isset($out[$id])) continue;
@@ -662 +10122 @@
         $event_args = array_merge([$event_since, $event_since], $ids);
         // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Query is prepared with all variable values; table name is a class property built from the WordPress table prefix and fixed suffix; event counts must be current.
-        $event_rows = $wpdb->get_results($wpdb->prepare($event_sql, $event_args), ARRAY_A);
+        $event_rows = statpl_db_get_results(statpl_db_prepare($event_sql, $event_args), ARRAY_A);
         foreach ($event_rows as $event_row) {
             $id = (int)$event_row['product_id'];
@@ -686 +10146 @@
         $summary = [
             // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- This dashboard aggregate is cached by global_summary_metrics() for 60 seconds and invalidated when relevant data changes.
-            'products' => (int) $wpdb->get_var("SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_type='product' AND post_status IN ('publish','private','draft','pending')"),
+            'products' => (int) statpl_db_get_var("SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_type='product' AND post_status IN ('publish','private','draft','pending')"),
             'views' => 0, 'views24' => 0, 'orders' => 0, 'orders24' => 0,
             'units' => 0.0, 'units24' => 0.0, 'revenue' => 0.0, 'revenue24' => 0.0,
@@ -694 +10154 @@
         // All product views are recorded and aggregated by Statora Plus.
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is constructor-generated from the WordPress prefix and a fixed suffix; the dashboard aggregate is cached for 60 seconds and view recording invalidates that cache.
-        $summary['views'] = (int) $wpdb->get_var("SELECT COALESCE(SUM(total_views),0) FROM {$this->views_table}");
+        $summary['views'] = (int) statpl_db_get_var("SELECT COALESCE(SUM(total_views),0) FROM {$this->views_table}");
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; the date value is prepared.
-        $summary['views24'] = (int) $wpdb->get_var(
-            $wpdb->prepare(
+        $summary['views24'] = (int) statpl_db_get_var(
+            statpl_db_prepare(
                 // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; the date value is prepared.
                 "SELECT COUNT(*) FROM {$this->events_table} WHERE viewed_at >= %s",
@@ -707 +10167 @@
         // phpcs:disable WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- SQL identifiers cannot be bound as value placeholders; the identifier is internal, not user-controlled.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- This aggregate is cached by global_summary_metrics() for 60 seconds and invalidated on relevant changes.
-        $sales = $wpdb->get_row($wpdb->prepare("SELECT
+        $sales = statpl_db_get_row(statpl_db_prepare("SELECT
             COALESCE(SUM(CASE WHEN statpl_snapshot.order_status='completed' AND statpl_snapshot.completed_at IS NOT NULL THEN statpl_snapshot.net_quantity ELSE 0 END),0) AS units_total,
             COALESCE(SUM(CASE WHEN statpl_snapshot.order_status='completed' AND statpl_snapshot.completed_at >= %s THEN statpl_snapshot.net_quantity ELSE 0 END),0) AS units24,
@@ -723 +10183 @@
         // Product-level detail is calculated separately from rows with actual product IDs.
         // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed suffix; no user-supplied SQL values are used.
-        $event_totals = $wpdb->get_row(
+        $event_totals = statpl_db_get_row(
             // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter -- The table identifier is constructor-generated from $wpdb->prefix and a fixed plugin suffix; this aggregate has no user-supplied SQL values.
             "SELECT COUNT(DISTINCT CASE WHEN event_type='cancelled' AND product_id=0 THEN order_id END) AS cancelled_total, COUNT(DISTINCT CASE WHEN event_type='refund' AND product_id=0 AND event_ref_id > 0 THEN event_ref_id END) AS refunds_total FROM {$this->order_events_table}",
@@ -734 +10194 @@
         // Every normal order is represented once per product in the snapshot; count order IDs only once.
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is constructor-generated from the WordPress prefix and a fixed suffix.; Table identifier is internally generated from the WordPress prefix and a fixed suffix.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['total_orders'] = (int) $wpdb->get_var("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table}");
+        $summary['total_orders'] = (int) statpl_db_get_var("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table}");
         // Clean orders are currently processing/completed and retain some non-refunded product quantity/value.
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is constructor-generated from the WordPress prefix and a fixed suffix.; Table identifier is internally generated from the WordPress prefix and a fixed suffix.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['orders'] = (int) $wpdb->get_var("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table} WHERE order_status IN ('processing','completed') AND (net_quantity > 0 OR net_revenue > 0)");
+        $summary['orders'] = (int) statpl_db_get_var("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table} WHERE order_status IN ('processing','completed') AND (net_quantity > 0 OR net_revenue > 0)");
         // Today's clean orders are based on order creation date, not payment/completion date.
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is internally generated; date value is prepared.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['orders24'] = (int) $wpdb->get_var($wpdb->prepare("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table} WHERE order_status IN ('processing','completed') AND created_at >= %s AND (net_quantity > 0 OR net_revenue > 0)", $since));
+        $summary['orders24'] = (int) statpl_db_get_var(statpl_db_prepare("SELECT COUNT(DISTINCT order_id) FROM {$this->order_items_table} WHERE order_status IN ('processing','completed') AND created_at >= %s AND (net_quantity > 0 OR net_revenue > 0)", $since));
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is internally generated; date value is prepared.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['cancelled24'] = (int) $wpdb->get_var($wpdb->prepare("SELECT COUNT(DISTINCT order_id) FROM {$this->order_events_table} WHERE product_id=0 AND event_type='cancelled' AND event_at >= %s", $since));
+        $summary['cancelled24'] = (int) statpl_db_get_var(statpl_db_prepare("SELECT COUNT(DISTINCT order_id) FROM {$this->order_events_table} WHERE product_id=0 AND event_type='cancelled' AND event_at >= %s", $since));
         // phpcs:ignore WordPress.DB.PreparedSQL.InterpolatedNotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Table identifier is internally generated; date value is prepared.; This aggregate is part of the 60-second cached dashboard summary.
-        $summary['refunds24'] = (int) $wpdb->get_var($wpdb->prepare("SELECT COUNT(DISTINCT event_ref_id) FROM {$this->order_events_table} WHERE product_id=0 AND event_type='refund' AND event_ref_id > 0 AND event_at >= %s", $since));
+        $summary['refunds24'] = (int) statpl_db_get_var(statpl_db_prepare("SELECT COUNT(DISTINCT event_ref_id) FROM {$this->order_events_table} WHERE product_id=0 AND event_type='refund' AND event_ref_id > 0 AND event_at >= %s", $since));
         $summary['revenue'] = round($summary['revenue'], wc_get_price_decimals());
         $summary['revenue24'] = round($summary['revenue24'], wc_get_price_decimals());
@@ -829 +10289 @@
                         SELECT product_id, COUNT(*) AS views_today
                         FROM {$this->events_table}
-                        WHERE viewed_at >= " . $wpdb->prepare('%s', $since_mysql) . "
+                        WHERE viewed_at >= " . statpl_db_prepare('%s', $since_mysql) . "
                         GROUP BY product_id
                     ) recent ON recent.product_id = totals.product_id
@@ -837 +10297 @@
                     SELECT product_id, COUNT(*) AS views_today
                     FROM {$this->events_table}
-                    WHERE viewed_at >= " . $wpdb->prepare('%s', $since_mysql) . "
+                    WHERE viewed_at >= " . statpl_db_prepare('%s', $since_mysql) . "
                     GROUP BY product_id
                 ) statpl_recent_views ON statpl_recent_views.product_id = p.ID";
@@ -849 +10309 @@
                     SELECT product_id,
                         COUNT(DISTINCT CASE WHEN order_status IN ('processing','completed') AND (net_quantity > 0 OR net_revenue > 0) THEN order_id END) AS orders,
-                        COUNT(DISTINCT CASE WHEN order_status IN ('processing','completed') AND created_at >= " . $wpdb->prepare('%s', $since) . " AND (net_quantity > 0 OR net_revenue > 0) THEN order_id END) AS orders24,
+                        COUNT(DISTINCT CASE WHEN order_status IN ('processing','completed') AND created_at >= " . statpl_db_prepare('%s', $since) . " AND (net_quantity > 0 OR net_revenue > 0) THEN order_id END) AS orders24,
                         SUM(CASE WHEN order_status='completed' AND completed_at IS NOT NULL THEN net_quantity ELSE 0 END) AS units,
-                        SUM(CASE WHEN order_status='completed' AND completed_at >= " . $wpdb->prepare('%s', $since) . " THEN net_quantity ELSE 0 END) AS units24,
+                        SUM(CASE WHEN order_status='completed' AND completed_at >= " . statpl_db_prepare('%s', $since) . " THEN net_quantity ELSE 0 END) AS units24,
                         SUM(CASE WHEN order_status='completed' AND completed_at IS NOT NULL THEN net_revenue ELSE 0 END) AS revenue,
-                        SUM(CASE WHEN order_status='completed' AND completed_at >= " . $wpdb->prepare('%s', $since) . " THEN net_revenue ELSE 0 END) AS revenue24
+                        SUM(CASE WHEN order_status='completed' AND completed_at >= " . statpl_db_prepare('%s', $since) . " THEN net_revenue ELSE 0 END) AS revenue24
                     FROM {$this->order_items_table} GROUP BY product_id
                 ) statpl_orders ON statpl_orders.product_id = p.ID
@@ -859 +10319 @@
                     SELECT product_id,
                         COUNT(DISTINCT CASE WHEN event_type='cancelled' THEN order_id END) AS cancelled,
-                        COUNT(DISTINCT CASE WHEN event_type='cancelled' AND event_at >= " . $wpdb->prepare('%s', $since) . " THEN order_id END) AS cancelled24,
+                        COUNT(DISTINCT CASE WHEN event_type='cancelled' AND event_at >= " . statpl_db_prepare('%s', $since) . " THEN order_id END) AS cancelled24,
                         COUNT(DISTINCT CASE WHEN event_type='refund' AND event_ref_id > 0 THEN event_ref_id END) AS refunds,
-                        COUNT(DISTINCT CASE WHEN event_type='refund' AND event_ref_id > 0 AND event_at >= " . $wpdb->prepare('%s', $since) . " THEN event_ref_id END) AS refunds24
+                        COUNT(DISTINCT CASE WHEN event_type='refund' AND event_ref_id > 0 AND event_at >= " . statpl_db_prepare('%s', $since) . " THEN event_ref_id END) AS refunds24
                     FROM {$this->order_events_table} GROUP BY product_id
                 ) statpl_events ON statpl_events.product_id = p.ID";
@@ -869 +10329 @@
             // $join and $where are assembled only from fixed SQL fragments and prepared placeholders; user input is passed in $args.
             // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Query fragments are plugin-controlled; all user-supplied values are bound through prepare(); product filters are evaluated live.
-            $total = (int) $wpdb->get_var($wpdb->prepare($count_sql, $args));
+            $total = (int) statpl_db_get_var(statpl_db_prepare($count_sql, $args));
             $order_column = $order_columns[$orderby] ?? 'p.post_title';
             $pages_for_query = max(1, (int) ceil($total / $per_page));
@@ -878 +10338 @@
             // $order_column is selected from the internal allowlist and $order is normalized before query construction.
             // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared, PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- Query fragments are plugin-controlled; all user-supplied values are bound through prepare(); product filters are evaluated live.
-            $product_ids = array_map('intval', $wpdb->get_col($wpdb->prepare($id_sql, $id_args)));
+            $product_ids = array_map('intval', statpl_db_get_col(statpl_db_prepare($id_sql, $id_args)));
         } else {
             $base_args = ['post_type'=>'product','post_status'=>$statuses,'posts_per_page'=>-1,'fields'=>'ids','orderby'=>'ID','order'=>'ASC'];
@@ -891 +10351 @@
 if (false === $sku_ids) {
     // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery -- Prepared partial-SKU lookup is required; results are cached for 60 seconds.
-    $sku_ids = $wpdb->get_col(
-        $wpdb->prepare(
+    $sku_ids = statpl_db_get_col(
+        statpl_db_prepare(
     "SELECT DISTINCT p.ID
     FROM {$wpdb->posts} p
@@ -928 +10388 @@
             $st = $stats_by_product[$product_id] ?? ['orders'=>0,'orders24'=>0,'units'=>0,'units24'=>0,'revenue'=>0.0,'revenue24'=>0.0,'cancelled'=>0,'cancelled24'=>0,'refunds'=>0,'refunds24'=>0];
             $stock_summary = $this->stock_summary_for_product($product);
+            $product_status = get_post_status($product_id);
+            $visibility_labels = [
+                'private' => 'Κρυφό',
+                'draft' => 'Πρόχειρο',
+                'pending' => 'Σε αναμονή',
+            ];
             $rows[] = ['id'=>$product_id,'title'=>$product->get_name(),'date'=>get_post_field('post_date',$product_id),'sku'=>$product->get_sku(),
-                'views'=>(int)$views['total'],'views24'=>(int)$views['today'],'source'=>$views['source'],'stock_managed'=>$stock_summary['managed'],'stock'=>$stock_summary['quantity'],'edit_url'=>get_edit_post_link($product_id, 'raw')] + $st;
+                'product_visibility'=>$visibility_labels[$product_status] ?? '',
+                'views'=>(int)$views['total'],'views24'=>(int)$views['today'],'source'=>$views['source'],'stock_managed'=>$stock_summary['managed'],'stock'=>$stock_summary['quantity'],'stock_in_stock'=>$stock_summary['in_stock'],'edit_url'=>get_edit_post_link($product_id, 'raw')] + $st;
         }
         if (!$db_paged) {
@@ -945 +10412 @@
         $summary = $this->global_summary_metrics();
 
-        echo '<div class="wrap statpl-metrics-wrap"><h1>Statora Plus</h1><p class="description">Στατιστικά προϊόντων WooCommerce σε μία συνοπτική εικόνα.</p>';
+        echo '<div class="wrap statpl-metrics-wrap"><h1>Statora Plus</h1>';
         $overview_url = add_query_arg(['page'=>'statpl-product-metrics','view'=>'overview'], admin_url('admin.php'));
         $products_url = add_query_arg(['page'=>'statpl-product-metrics','view'=>'products'], admin_url('admin.php'));
         echo '<nav class="nav-tab-wrapper"><a class="nav-tab '.($view === 'overview' ? 'nav-tab-active' : '').'" href="'.esc_url($overview_url).'">Συνολική εικόνα</a><a class="nav-tab '.($view === 'products' ? 'nav-tab-active' : '').'" href="'.esc_url($products_url).'">Στατιστικά ανά προϊόν</a></nav>';
 
-        if (get_option('statpl_import_complete')) {
-            echo '<div class="notice notice-success inline"><p>Η αρχική εισαγωγή ιστορικού έχει επισημανθεί ως ολοκληρωμένη.</p></div>';
-        } else {
-            $import_page = max(1, (int) get_option('statpl_import_page', 1));
-            echo '<div class="notice notice-info inline"><p>Η αρχική εισαγωγή ιστορικού εκτελείται στο παρασκήνιο. Επεξεργασία παρτίδας: '.esc_html((string)$import_page).'. Τα στατιστικά ενδέχεται να είναι ελλιπή μέχρι να ολοκληρωθεί.</p></div>';
-        }
+        $this->render_historical_import_notice();
         if ($view === 'overview') {
             echo '<h2>Συνολικά στατιστικά καταστήματος</h2>'; 
@@ -1006 +10468 @@
         if (!$visible_rows) echo '<tr><td colspan="14">Δεν βρέθηκαν προϊόντα.</td></tr>';
         foreach ($visible_rows as $r) {
-            echo '<tr><td><a class="statpl-product-title" href="'.esc_url($r['edit_url']).'">'.esc_html($r['title']).'</a></td>';
-            echo '<td>'.($r['stock_managed'] ? esc_html(number_format_i18n($r['stock'])) : '<span class="statpl-stock-not-tracked">Δεν παρακολουθείται</span>').'</td>';
+            echo '<tr><td><a class="statpl-product-title" href="'.esc_url($r['edit_url']).'">'.esc_html($r['title']).'</a>';
+            if (!empty($r['product_visibility'])) {
+                echo ' <span class="statpl-product-visibility">'.esc_html($r['product_visibility']).'</span>';
+            }
+            echo '</td>';
+            if ($r['stock_managed']) {
+                $stock_quantity = (float) $r['stock'];
+                if ($stock_quantity > 0) {
+                    echo '<td>'.esc_html(number_format_i18n($stock_quantity)).'</td>';
+                } elseif (!empty($r['stock_in_stock'])) {
+                    // Zero quantity with backorders allowed remains purchasable.
+                    echo '<td>0</td>';
+                } else {
+                    echo '<td>Εξαντλημένο</td>';
+                }
+            } else {
+                echo '<td><span class="statpl-stock-not-tracked">Δεν γίνεται διαχείριση αποθέματος</span></td>';
+            }
             echo '<td>'.esc_html(number_format_i18n($r['views'])).'</td><td>'.esc_html(number_format_i18n($r['views24'])).'</td>';
             foreach (['orders','orders24'] as $k) echo '<td>'.esc_html(number_format_i18n($r[$k])).'</td>';
@@ -1022 +10500 @@
 }
 STATPL_Core::instance();
+
+
+/**
+ * Page View Count adapter.
+ *
+ * Reads only the provider's immutable, per-product daily rows from pvc_daily.
+ * The current day is intentionally excluded because Page View Count updates
+ * that row in place; importing a mutable count would violate the immutable
+ * source snapshot contract. Lifetime totals in pvc_total are deliberately not
+ * imported because they overlap the daily rows and have no date boundaries.
+ */
+if (!class_exists('STATPL_Page_View_Count_Historical_Adapter')) {
+    final class STATPL_Page_View_Count_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'page_view_count';
+        const SOURCE_KEY = 'page_view_count';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'daily_product_views';
+
+        public function get_adapter_key() {
+            return self::ADAPTER_KEY;
+        }
+
+        public function get_source_key() {
+            return self::SOURCE_KEY;
+        }
+
+        public function get_display_name() {
+            return 'Page Views Count';
+        }
+
+        public function get_adapter_version() {
+            return self::ADAPTER_VERSION;
+        }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'pvc_daily';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- SHOW TABLES LIKE has one %s placeholder and receives exactly one escaped table-name value.
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) {
+                return ['status' => 'database_error', 'error' => (string) $wpdb->last_error];
+            }
+            if ($exists !== $table) {
+                return ['status' => 'missing_table'];
+            }
+
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- SHOW COLUMNS contains no value placeholders; the table identifier is validated and quoted by quoted_table_name().
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) {
+                return ['status' => 'database_error', 'error' => (string) $wpdb->last_error];
+            }
+            $names = [];
+            foreach ($columns as $column) {
+                if (isset($column['Field'])) {
+                    $names[] = (string) $column['Field'];
+                }
+            }
+            $required = ['id', 'time', 'postnum', 'postcount'];
+            if (array_diff($required, $names)) {
+                return ['status' => 'incompatible_schema'];
+            }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') {
+                // A previously registered source can be marked unavailable by the
+                // core's authoritative inventory reconciliation if its table was
+                // removed. A never-installed source is not registered needlessly.
+                return [];
+            }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => [
+                    'product_views' => true,
+                    'granularity' => 'daily_aggregate',
+                    'immutable_past_days' => true,
+                ],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) {
+                return [];
+            }
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'available') {
+                throw new RuntimeException('Page View Count source table is not available or has an incompatible schema.');
+            }
+
+            $through_date = current_datetime()->modify('-1 day')->format('Y-m-d');
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(d.id)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS d
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p
+                   ON p.ID = CAST(d.postnum AS UNSIGNED)
+                  AND p.post_type = %s
+                 WHERE d.postnum REGEXP %s AND d.time <= %s',
+                'product',
+                '^[0-9]+$',
+                $through_date
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Page View Count snapshot query failed.');
+            }
+
+            return [
+                'boundary' => [
+                    'max_id' => max(0, (int) $max_id),
+                    'through_date' => $through_date,
+                ],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Page View Count origin or snapshot.');
+            }
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'available') {
+                throw new RuntimeException('Page View Count source table became unavailable or incompatible.');
+            }
+
+            $boundary = $snapshot['boundary'];
+            $max_id = isset($boundary['max_id']) ? absint($boundary['max_id']) : -1;
+            $through_date = isset($boundary['through_date']) ? (string) $boundary['through_date'] : '';
+            $date = DateTime::createFromFormat('!Y-m-d', $through_date);
+            if ($max_id < 0 || !$date || $date->format('Y-m-d') !== $through_date) {
+                throw new RuntimeException('Invalid Page View Count snapshot boundary.');
+            }
+
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_value = $checkpoint['cursor'];
+                if ($cursor_value !== null) {
+                    $cursor_id = absint($cursor_value);
+                }
+            } elseif (is_numeric($checkpoint)) {
+                $cursor_id = absint($checkpoint);
+            }
+
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT MAX(d.id) AS id, d.time, d.postnum, SUM(d.postcount) AS postcount
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS d
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p
+                   ON p.ID = CAST(d.postnum AS UNSIGNED)
+                  AND p.post_type = %s
+                 WHERE d.postnum REGEXP %s
+                   AND d.id <= %d
+                   AND d.time <= %s
+                 GROUP BY d.time, d.postnum
+                 HAVING MAX(d.id) > %d
+                 ORDER BY MAX(d.id) ASC
+                 LIMIT %d',
+                'product',
+                '^[0-9]+$',
+                $max_id,
+                $through_date,
+                $cursor_id,
+                $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Page View Count batch query failed.');
+            }
+
+            $has_more = count($rows) > $limit;
+            if ($has_more) {
+                $rows = array_slice($rows, 0, $limit);
+            }
+            $next_checkpoint = $cursor_id;
+            if ($rows) {
+                $last = end($rows);
+                $next_checkpoint = absint($last['id']);
+            }
+
+            return [
+                'rows' => array_values($rows),
+                'has_more' => $has_more,
+                'next_checkpoint' => $next_checkpoint,
+                'boundary_applied' => true,
+            ];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) {
+                return null;
+            }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_raw = isset($record['postnum']) ? (string) $record['postnum'] : '';
+            $views_raw = $record['postcount'] ?? null;
+            $date = isset($record['time']) ? (string) $record['time'] : '';
+            if (!$record_id || !preg_match('/^[1-9][0-9]*$/D', $product_raw) || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) {
+                return null;
+            }
+            $parsed_date = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed_date || $parsed_date->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) {
+                return null;
+            }
+
+            $product_id = (int) $product_raw;
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'pvc_daily_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => $record_id,
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) {
+        return $adapters;
+    }
+    $adapter = new STATPL_Page_View_Count_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 30);
+
+/**
+ * WP Statistics adapter.
+ *
+ * Imports daily rows from statistics_pages where WP Statistics has explicitly
+ * classified the viewed resource as a WooCommerce product. The historical
+ * summary table is not read here: it no longer preserves a trustworthy date
+ * interval after detailed rows have been aggregated.
+ */
+if (!class_exists('STATPL_WP_Statistics_Historical_Adapter')) {
+    final class STATPL_WP_Statistics_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'wp_statistics_pages';
+        const SOURCE_KEY = 'wp_statistics';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_daily_pages';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'WP Statistics'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'statistics_pages';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) {
+                return ['status' => 'database_error', 'error' => (string) $wpdb->last_error];
+            }
+            if ($exists !== $table) {
+                return ['status' => 'missing_table'];
+            }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) {
+                return ['status' => 'database_error', 'error' => (string) $wpdb->last_error];
+            }
+            $names = [];
+            foreach ($columns as $column) {
+                if (isset($column['Field'])) { $names[] = (string) $column['Field']; }
+            }
+            if (array_diff(['page_id', 'uri', 'type', 'date', 'count', 'id'], $names)) {
+                return ['status' => 'incompatible_schema'];
+            }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'immutable_past_days' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('WP Statistics pages table is unavailable or incompatible.');
+            }
+            $through_date = current_datetime()->modify('-1 day')->format('Y-m-d');
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(s.page_id)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.id AND p.post_type = %s
+                 WHERE s.type = %s AND s.date <= %s',
+                'product', 'product', $through_date
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('WP Statistics snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_page_id' => max(0, (int) $max_id), 'through_date' => $through_date],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid WP Statistics origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('WP Statistics pages table became unavailable or incompatible.');
+            }
+            $boundary = $snapshot['boundary'];
+            $max_id = isset($boundary['max_page_id']) ? absint($boundary['max_page_id']) : -1;
+            $through_date = isset($boundary['through_date']) ? (string) $boundary['through_date'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+            if ($max_id < 0 || !$parsed || $parsed->format('Y-m-d') !== $through_date) {
+                throw new RuntimeException('Invalid WP Statistics snapshot boundary.');
+            }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) {
+                $cursor_id = absint($checkpoint);
+            }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT MAX(s.page_id) AS page_id, s.date, SUM(s.count) AS count, s.id
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.id AND p.post_type = %s
+                 WHERE s.type = %s AND s.page_id <= %d AND s.date <= %s
+                 GROUP BY s.date, s.id
+                 HAVING MAX(s.page_id) > %d
+                 ORDER BY MAX(s.page_id) ASC
+                 LIMIT %d',
+                'product', 'product', $max_id, $through_date, $cursor_id, $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('WP Statistics batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['page_id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['page_id']) ? absint($record['page_id']) : 0;
+            $product_id = isset($record['id']) ? absint($record['id']) : 0;
+            $views_raw = $record['count'] ?? null;
+            $date = isset($record['date']) ? (string) $record['date'] : '';
+            if (!$record_id || !$product_id || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'wp_statistics_product_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => $record_id,
+            ];
+        }
+    }
+}
+
+/**
+ * Post Views Counter adapter.
+ *
+ * Reads only type=0 daily rows from wp_post_views. Week, month, year and total
+ * rows are deliberately excluded because they are overlapping rollups of the
+ * same views. Past-day rows are used so the source counts are stable while the
+ * importer runs; today's row is still mutable and is left to live tracking.
+ */
+if (!class_exists('STATPL_Post_Views_Counter_Historical_Adapter')) {
+    final class STATPL_Post_Views_Counter_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'post_views_counter';
+        const SOURCE_KEY = 'post_views_counter';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'daily_product_views';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Post Views Counter'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'post_views';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = (string) $column['Field']; } }
+            if (array_diff(['id', 'type', 'period', 'count'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'immutable_past_days' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Post Views Counter table is unavailable or incompatible.');
+            }
+            $through_date = current_datetime()->modify('-1 day')->format('Ymd');
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+            // phpcs:ignore WordPress.DB.PreparedSQLPlaceholders.ReplacementsWrongNumber -- The query has four fixed value placeholders and receives four values; the two table identifiers are independently validated SQL identifiers.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_period = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(v.period)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS v
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = v.id AND p.post_type = %s
+                 WHERE v.type = %d AND v.period REGEXP %s AND v.period <= %s',
+                'product', 0, '^[0-9]{8}$', $through_date
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Post Views Counter snapshot query failed.');
+            }
+            if (!is_string($max_period) || !preg_match('/^[0-9]{8}$/D', $max_period)) { $max_period = ''; }
+            return [
+                'boundary' => ['max_period' => $max_period],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Post Views Counter origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Post Views Counter table became unavailable or incompatible.');
+            }
+            $max_period = isset($snapshot['boundary']['max_period']) ? (string) $snapshot['boundary']['max_period'] : '';
+            if ($max_period !== '' && !preg_match('/^[0-9]{8}$/D', $max_period)) { throw new RuntimeException('Invalid Post Views Counter snapshot boundary.'); }
+            $cursor_period = '';
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor']) && is_array($checkpoint['cursor'])) {
+                $cursor_period = isset($checkpoint['cursor']['period']) ? (string) $checkpoint['cursor']['period'] : '';
+                $cursor_id = isset($checkpoint['cursor']['id']) ? absint($checkpoint['cursor']['id']) : 0;
+            }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+            if ($max_period === '') { $rows = []; }
+            else {
+                $cursor_sql = '';
+                $args = ['product', 0, '^[0-9]{8}$', $max_period];
+                if ($cursor_period !== '') {
+                    if (!preg_match('/^[0-9]{8}$/D', $cursor_period)) { throw new RuntimeException('Invalid Post Views Counter cursor.'); }
+                    $cursor_sql = ' AND (v.period > %s OR (v.period = %s AND v.id > %d))';
+                    $args[] = $cursor_period;
+                    $args[] = $cursor_period;
+                    $args[] = $cursor_id;
+                }
+                $batch_sql = 'SELECT v.id, v.period, v.count
+                     FROM ' . $this->quoted_table_name() . ' AS v
+                     INNER JOIN ' . $posts_table . ' AS p ON p.ID = v.id AND p.post_type = %s
+                     WHERE v.type = %d AND v.period REGEXP %s AND v.period <= %s' . $cursor_sql . '
+                     ORDER BY v.period ASC, v.id ASC
+                     LIMIT %d';
+                if ($cursor_period !== '') {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                    $rows = statpl_db_get_results(statpl_db_prepare(
+                        /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                        'product', 0, '^[0-9]{8}$', $max_period,
+                        $cursor_period, $cursor_period, $cursor_id, $limit + 1
+                    ), ARRAY_A);
+                } else {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                    $rows = statpl_db_get_results(statpl_db_prepare(
+                        /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                        'product', 0, '^[0-9]{8}$', $max_period, $limit + 1
+                    ), ARRAY_A);
+                }
+            }
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Post Views Counter batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = ($cursor_period !== '') ? ['period' => $cursor_period, 'id' => $cursor_id] : null;
+            if ($rows) { $last = end($rows); $next = ['period' => (string) $last['period'], 'id' => absint($last['id'])]; }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $product_id = isset($record['id']) ? absint($record['id']) : 0;
+            $period = isset($record['period']) ? (string) $record['period'] : '';
+            $views_raw = $record['count'] ?? null;
+            if (!$product_id || !preg_match('/^[0-9]{8}$/D', $period) || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Ymd', $period);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Ymd') !== $period || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $date = $parsed->format('Y-m-d');
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'post_views_counter_day_' . $period . '_' . $product_id,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => ['period' => $period, 'id' => $product_id],
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $wp_statistics = new STATPL_WP_Statistics_Historical_Adapter();
+    if ($wp_statistics->should_register_adapter()) { $adapters[] = $wp_statistics; }
+    $post_views_counter = new STATPL_Post_Views_Counter_Historical_Adapter();
+    if ($post_views_counter->should_register_adapter()) { $adapters[] = $post_views_counter; }
+    return $adapters;
+}, 31);
+
+/**
+ * Statify adapter.
+ *
+ * Statify stores one immutable row per page view, but its schema contains only
+ * a calendar date and target URL (not a timestamp or WordPress post ID). The
+ * adapter resolves same-site targets to published WooCommerce products and
+ * explicitly skips non-product rows. It does not issue cross-source fingerprints:
+ * a date-only row cannot be safely matched one-to-one against another provider's
+ * event stream without risking suppression of legitimate repeat views.
+ */
+if (!class_exists('STATPL_Statify_Historical_Adapter')) {
+    final class STATPL_Statify_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'statify';
+        const SOURCE_KEY = 'statify';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'page_view_events';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Statify'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'statify';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = (string) $column['Field']; } }
+            if (array_diff(['id', 'created', 'referrer', 'target'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'event_date_only', 'target_requires_product_resolution' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Statify table is unavailable or incompatible.');
+            }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var('SELECT MAX(id) FROM ' . $this->quoted_table_name());
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Statify snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_id' => max(0, (int) $max_id)],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Statify origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Statify table became unavailable or incompatible.');
+            }
+            $max_id = isset($snapshot['boundary']['max_id']) ? absint($snapshot['boundary']['max_id']) : -1;
+            if ($max_id < 0) { throw new RuntimeException('Invalid Statify snapshot boundary.'); }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && array_key_exists('cursor', $checkpoint)) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) {
+                $cursor_id = absint($checkpoint);
+            }
+            $limit = max(1, min(100, absint($limit)));
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT id, created, referrer, target
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . '
+                 WHERE id > %d AND id <= %d
+                 ORDER BY id ASC
+                 LIMIT %d',
+                $cursor_id,
+                $max_id,
+                $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Statify batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        private function resolve_product_id($target) {
+            if (!is_string($target) || trim($target) === '' || !function_exists('url_to_postid')) { return 0; }
+            $target = trim($target);
+            if (preg_match('#^https?://#i', $target)) {
+                $url = $target;
+            } elseif (strpos($target, '//') === 0) {
+                return 0;
+            } else {
+                $url = home_url('/' . ltrim($target, '/'));
+            }
+            $target_host = strtolower((string) wp_parse_url($url, PHP_URL_HOST));
+            $home_host = strtolower((string) wp_parse_url(home_url('/'), PHP_URL_HOST));
+            if ($target_host === '' || $home_host === '' || $target_host !== $home_host) { return 0; }
+            $product_id = absint(url_to_postid($url));
+            if (!$product_id || get_post_type($product_id) !== 'product') { return 0; }
+            return $product_id;
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $record_key = $record_id ? 'statify_view_' . $record_id : '';
+            $cursor = $record_id;
+            if (!$record_id) { return null; }
+            $date = isset($record['created']) ? (string) $record['created'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) {
+                return null;
+            }
+            $product_id = $this->resolve_product_id(isset($record['target']) ? (string) $record['target'] : '');
+            if (!$product_id) {
+                return ['skip' => true, 'source_record_key' => $record_key, 'cursor' => $cursor];
+            }
+            $referrer = isset($record['referrer']) ? (string) $record['referrer'] : '';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => $record_key,
+                'views' => 1,
+                'record_type' => 'event',
+                'period_start' => $date . ' 00:00:00',
+                'period_end' => $date . ' 23:59:59',
+                'cursor' => $cursor,
+                'source_referrer_hash' => hash('sha256', $referrer),
+            ];
+        }
+
+        public function get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event) {
+            return [
+                'source' => 'statify',
+                'date_precision' => 'calendar_day_only',
+                'referrer_sha256' => isset($normalized_record['source_referrer_hash']) ? $normalized_record['source_referrer_hash'] : null,
+                'overlap_assessment' => 'possible_but_not_proven',
+                'automatic_suppression' => false,
+                'reason' => 'Statify has no per-view timestamp or stable cross-provider event identifier; a one-to-one match would risk suppressing legitimate repeat views.',
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Statify_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 32);
+
+/**
+ * WP Popular Posts adapter.
+ *
+ * Imports the per-post/per-day summary table only. The all-time data table is
+ * deliberately excluded because it overlaps the daily summary and carries no
+ * date range. WPP's configurable log retention determines how much daily
+ * history remains available at the time Statora captures its snapshot.
+ */
+if (!class_exists('STATPL_WP_Popular_Posts_Historical_Adapter')) {
+    final class STATPL_WP_Popular_Posts_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'wp_popular_posts';
+        const SOURCE_KEY = 'wp_popular_posts';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_daily_summary';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'WP Popular Posts'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'popularpostssummary';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            if (array_diff(['id', 'postid', 'pageviews', 'view_date', 'last_viewed'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'immutable_past_days' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('WP Popular Posts summary table is unavailable or incompatible.');
+            }
+            $through_date = current_datetime()->modify('-1 day')->format('Y-m-d');
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(s.ID)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.postid AND p.post_type = %s
+                 WHERE s.view_date <= %s',
+                'product', $through_date
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('WP Popular Posts snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_id' => max(0, (int) $max_id), 'through_date' => $through_date],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid WP Popular Posts origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('WP Popular Posts summary table became unavailable or incompatible.');
+            }
+            $boundary = $snapshot['boundary'];
+            $max_id = isset($boundary['max_id']) ? absint($boundary['max_id']) : -1;
+            $through_date = isset($boundary['through_date']) ? (string) $boundary['through_date'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+            if ($max_id < 0 || !$parsed || $parsed->format('Y-m-d') !== $through_date) {
+                throw new RuntimeException('Invalid WP Popular Posts snapshot boundary.');
+            }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) { $cursor_id = absint($checkpoint); }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT s.ID AS id, s.postid, s.pageviews, s.view_date
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.postid AND p.post_type = %s
+                 WHERE s.ID > %d AND s.ID <= %d AND s.view_date <= %s
+                 ORDER BY s.ID ASC
+                 LIMIT %d',
+                'product', $cursor_id, $max_id, $through_date, $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('WP Popular Posts batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_id = isset($record['postid']) ? absint($record['postid']) : 0;
+            $views_raw = $record['pageviews'] ?? null;
+            $date = isset($record['view_date']) ? (string) $record['view_date'] : '';
+            if (!$record_id || !$product_id || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'wp_popular_posts_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => $record_id,
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_WP_Popular_Posts_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 33);
+
+/**
+ * WebberZone Top 10 adapter.
+ *
+ * Imports only the per-post hourly rows from top_ten_daily, grouped into local
+ * calendar-day totals. The all-time table, visits funnel and visits log are not
+ * imported in parallel: the funnel/log feed the same daily and lifetime counts.
+ * A two-day safety lag allows Top 10's background aggregation cron to drain
+ * completed days before the snapshot is taken.
+ */
+if (!class_exists('STATPL_Top_Ten_Historical_Adapter')) {
+    final class STATPL_Top_Ten_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'webberzone_top_10';
+        const SOURCE_KEY = 'webberzone_top_10';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_daily_counts';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'WebberZone Top 10'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->base_prefix . 'top_ten_daily';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            if (array_diff(['postnumber', 'cntaccess', 'dp_date', 'blog_id'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available', 'has_feed_column' => in_array('feedcnt', $names, true)];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'source_storage_granularity' => 'hourly', 'immutable_past_days' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Top 10 daily table is unavailable or incompatible.');
+            }
+            $through_date = current_datetime()->modify('-2 days')->format('Y-m-d');
+            return [
+                'boundary' => ['through_date' => $through_date, 'blog_id' => absint(get_current_blog_id())],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Top 10 origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Top 10 daily table became unavailable or incompatible.');
+            }
+            $through_date = isset($snapshot['boundary']['through_date']) ? (string) $snapshot['boundary']['through_date'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+            $blog_id = isset($snapshot['boundary']['blog_id']) ? absint($snapshot['boundary']['blog_id']) : 0;
+            if (!$parsed || $parsed->format('Y-m-d') !== $through_date || !$blog_id) {
+                throw new RuntimeException('Invalid Top 10 snapshot boundary.');
+            }
+            $cursor_date = '';
+            $cursor_product = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor']) && is_array($checkpoint['cursor'])) {
+                $cursor_date = isset($checkpoint['cursor']['date']) ? (string) $checkpoint['cursor']['date'] : '';
+                $cursor_product = isset($checkpoint['cursor']['product_id']) ? absint($checkpoint['cursor']['product_id']) : 0;
+            }
+            if ($cursor_date !== '' && (!preg_match('/^\d{4}-\d{2}-\d{2}$/D', $cursor_date) || !DateTime::createFromFormat('!Y-m-d', $cursor_date))) {
+                throw new RuntimeException('Invalid Top 10 cursor date.');
+            }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+            $inspection = $this->inspect_table();
+            $view_sum_sql = !empty($inspection['has_feed_column'])
+                ? 'SUM(GREATEST(t.cntaccess - t.feedcnt, 0))'
+                : 'SUM(t.cntaccess)';
+            if (!in_array($view_sum_sql, ['SUM(GREATEST(t.cntaccess - t.feedcnt, 0))', 'SUM(t.cntaccess)'], true)) {
+                throw new RuntimeException('Unsupported Top 10 view aggregation expression.');
+            }
+            $cursor_sql = '';
+            $args = ['product', $blog_id, $through_date];
+            if ($cursor_date !== '') {
+                $cursor_sql = ' HAVING (view_date > %s OR (view_date = %s AND product_id > %d))';
+                $args[] = $cursor_date;
+                $args[] = $cursor_date;
+                $args[] = $cursor_product;
+            }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $view_sum_sql is selected from two fixed aggregate expressions and checked against the same strict allowlist; all runtime values remain prepared placeholders.
+            $batch_sql = 'SELECT DATE(t.dp_date) AS view_date, t.postnumber AS product_id, ' . $view_sum_sql . ' AS views
+                 FROM ' . $this->quoted_table_name() . ' AS t
+                 INNER JOIN ' . $posts_table . ' AS p ON p.ID = t.postnumber AND p.post_type = %s
+                 WHERE t.blog_id = %d AND t.dp_date < DATE_ADD(%s, INTERVAL 1 DAY)
+                 GROUP BY DATE(t.dp_date), t.postnumber' . $cursor_sql . '
+                 ORDER BY view_date ASC, product_id ASC
+                 LIMIT %d';
+            if ($cursor_date !== '') {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                    'product', $blog_id, $through_date,
+                    $cursor_date, $cursor_date, $cursor_product, $limit + 1
+                ), ARRAY_A);
+            } else {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                    'product', $blog_id, $through_date, $limit + 1
+                ), ARRAY_A);
+            }
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Top 10 batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = ($cursor_date !== '') ? ['date' => $cursor_date, 'product_id' => $cursor_product] : null;
+            if ($rows) { $last = end($rows); $next = ['date' => (string) $last['view_date'], 'product_id' => absint($last['product_id'])]; }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $product_id = isset($record['product_id']) ? absint($record['product_id']) : 0;
+            $date = isset($record['view_date']) ? (string) $record['view_date'] : '';
+            $views_raw = $record['views'] ?? null;
+            if (!$product_id || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'top_10_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => ['date' => $date, 'product_id' => $product_id],
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Top_Ten_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 34);
+
+/**
+ * Koko Analytics adapter.
+ *
+ * Reads the per-page daily statistics table. Current Koko schemas use path_id
+ * and post_id; older schemas used id directly as the WordPress post ID. Rows
+ * are grouped by product/date because one product can be represented by more
+ * than one canonicalized path. Only completed days are imported.
+ */
+if (!class_exists('STATPL_Koko_Analytics_Historical_Adapter')) {
+    final class STATPL_Koko_Analytics_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'koko_analytics';
+        const SOURCE_KEY = 'koko_analytics';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_daily_stats';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Koko Analytics'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'koko_analytics_post_stats';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            if (!in_array('date', $names, true) || !in_array('pageviews', $names, true)) { return ['status' => 'incompatible_schema']; }
+            if (in_array('post_id', $names, true) && in_array('path_id', $names, true)) {
+                return ['status' => 'available', 'schema_mode' => 'path_id'];
+            }
+            if (in_array('id', $names, true)) {
+                return ['status' => 'available', 'schema_mode' => 'legacy_post_id'];
+            }
+            return ['status' => 'incompatible_schema'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'schema_mode' => isset($inspection['schema_mode']) ? $inspection['schema_mode'] : 'unknown'],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'available') {
+                throw new RuntimeException('Koko Analytics post statistics table is unavailable or incompatible.');
+            }
+            return [
+                'boundary' => [
+                    'through_date' => current_datetime()->modify('-1 day')->format('Y-m-d'),
+                    'schema_mode' => $inspection['schema_mode'],
+                ],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Koko Analytics origin or snapshot.');
+            }
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'available') {
+                throw new RuntimeException('Koko Analytics post statistics table became unavailable or incompatible.');
+            }
+            $boundary = $snapshot['boundary'];
+            $through_date = isset($boundary['through_date']) ? (string) $boundary['through_date'] : '';
+            $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+            $schema_mode = isset($boundary['schema_mode']) ? (string) $boundary['schema_mode'] : '';
+            if (!$parsed || $parsed->format('Y-m-d') !== $through_date || $schema_mode !== $inspection['schema_mode']) {
+                throw new RuntimeException('Invalid or changed Koko Analytics snapshot boundary.');
+            }
+            $cursor_date = '';
+            $cursor_product = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor']) && is_array($checkpoint['cursor'])) {
+                $cursor_date = isset($checkpoint['cursor']['date']) ? (string) $checkpoint['cursor']['date'] : '';
+                $cursor_product = isset($checkpoint['cursor']['product_id']) ? absint($checkpoint['cursor']['product_id']) : 0;
+            }
+            if ($cursor_date !== '' && (!preg_match('/^\d{4}-\d{2}-\d{2}$/D', $cursor_date) || !DateTime::createFromFormat('!Y-m-d', $cursor_date))) {
+                throw new RuntimeException('Invalid Koko Analytics cursor date.');
+            }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+            if (!in_array($schema_mode, ['path_id', 'id'], true)) {
+                throw new RuntimeException('Unsupported Koko Analytics schema mode.');
+            }
+            $post_id_column = $schema_mode === 'path_id' ? 's.post_id' : 's.id';
+            if (!in_array($post_id_column, ['s.post_id', 's.id'], true)) {
+                throw new RuntimeException('Unsupported Koko Analytics product identifier column.');
+            }
+            $cursor_sql = '';
+            $args = ['product', $through_date];
+            if ($cursor_date !== '') {
+                $cursor_sql = ' HAVING (view_date > %s OR (view_date = %s AND product_id > %d))';
+                $args[] = $cursor_date;
+                $args[] = $cursor_date;
+                $args[] = $cursor_product;
+            }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $post_id_column is selected from the fixed allowlist s.post_id/s.id after schema-mode validation; runtime values remain prepared placeholders.
+            $batch_sql = 'SELECT s.date AS view_date, ' . $post_id_column . ' AS product_id, SUM(s.pageviews) AS views
+                 FROM ' . $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . $posts_table . ' AS p ON p.ID = ' . $post_id_column . ' AND p.post_type = %s
+                 WHERE s.date <= %s
+                 GROUP BY s.date, ' . $post_id_column . $cursor_sql . '
+                 ORDER BY view_date ASC, product_id ASC
+                 LIMIT %d';
+            if ($cursor_date !== '') {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                    'product', $through_date,
+                    $cursor_date, $cursor_date, $cursor_product, $limit + 1
+                ), ARRAY_A);
+            } else {
+// phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter, WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $batch_sql,
+                    'product', $through_date, $limit + 1
+                ), ARRAY_A);
+            }
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Koko Analytics batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = ($cursor_date !== '') ? ['date' => $cursor_date, 'product_id' => $cursor_product] : null;
+            if ($rows) { $last = end($rows); $next = ['date' => (string) $last['view_date'], 'product_id' => absint($last['product_id'])]; }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $product_id = isset($record['product_id']) ? absint($record['product_id']) : 0;
+            $date = isset($record['view_date']) ? (string) $record['view_date'] : '';
+            $views_raw = $record['views'] ?? null;
+            if (!$product_id || !preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+            $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+            $errors = DateTime::getLastErrors();
+            if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+            $views = (int) $views_raw;
+            $period_start = $date . ' 00:00:00';
+            $period_end = $date . ' 23:59:59';
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'koko_analytics_' . $product_id . '_' . $date,
+                'views' => $views,
+                'record_type' => 'aggregate',
+                'period_start' => $period_start,
+                'period_end' => $period_end,
+                'cursor' => ['date' => $date, 'product_id' => $product_id],
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Koko_Analytics_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 35);
+
+/**
+ * Burst Statistics adapter.
+ *
+ * Imports raw product pageview rows from burst_statistics. Unlike aggregate
+ * providers, Burst stores a WordPress post ID and a Unix timestamp per hit, so
+ * product resolution is direct and each source row has a stable ID. Visitor
+ * identifiers and session data are intentionally not read or imported.
+ */
+if (!class_exists('STATPL_Burst_Statistics_Historical_Adapter')) {
+    final class STATPL_Burst_Statistics_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'burst_statistics';
+        const SOURCE_KEY = 'burst_statistics';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_pageview_events';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Burst Statistics'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name() {
+            global $wpdb;
+            return $wpdb->prefix . 'burst_statistics';
+        }
+
+        private function quoted_table_name() {
+            $table = $this->table_name();
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table() {
+            global $wpdb;
+            $table = $this->table_name();
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quoted_table_name(), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            if (array_diff(['id', 'page_id', 'page_type', 'time'], $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_table();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'event', 'timestamp_precision' => 'seconds', 'product_id_direct' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Burst Statistics table is unavailable or incompatible.');
+            }
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(s.ID)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.page_id AND p.post_type = %s
+                 WHERE s.page_id > 0 AND s.page_type = %s',
+                'product', 'product'
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Burst Statistics snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_id' => max(0, (int) $max_id)],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Burst Statistics origin or snapshot.');
+            }
+            if ($this->inspect_table()['status'] !== 'available') {
+                throw new RuntimeException('Burst Statistics table became unavailable or incompatible.');
+            }
+            $max_id = isset($snapshot['boundary']['max_id']) ? absint($snapshot['boundary']['max_id']) : -1;
+            if ($max_id < 0) { throw new RuntimeException('Invalid Burst Statistics snapshot boundary.'); }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) { $cursor_id = absint($checkpoint); }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table_name = $wpdb->posts;
+            if (!is_string($posts_table_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $posts_table_name)) {
+                throw new InvalidArgumentException('Invalid WordPress posts table identifier.');
+            }
+            $posts_table = '`' . $posts_table_name . '`';
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT s.ID AS id, s.page_id, s.time
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quoted_table_name() . ' AS s
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = s.page_id AND p.post_type = %s
+                 WHERE s.page_type = %s AND s.page_id > 0 AND s.ID > %d AND s.ID <= %d
+                 ORDER BY s.ID ASC
+                 LIMIT %d',
+                'product', 'product', $cursor_id, $max_id, $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Burst Statistics batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_id = isset($record['page_id']) ? absint($record['page_id']) : 0;
+            $timestamp = isset($record['time']) ? absint($record['time']) : 0;
+            if (!$record_id || !$product_id || !$timestamp || !function_exists('wp_date')) { return null; }
+            $datetime = wp_date('Y-m-d H:i:s', $timestamp);
+            if (!is_string($datetime) || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $datetime)) { return null; }
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'burst_statistic_' . $record_id,
+                'views' => 1,
+                'record_type' => 'event',
+                'period_start' => $datetime,
+                'period_end' => $datetime,
+                'cursor' => $record_id,
+            ];
+        }
+
+        public function get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event) {
+            return [
+                'source' => 'burst_statistics',
+                'timestamp_precision' => 'seconds',
+                'overlap_assessment' => 'possible_but_not_proven',
+                'automatic_suppression' => false,
+                'reason' => 'Burst supplies an exact local event timestamp and product ID, but other providers do not share its stable pageview ID or visitor identity.',
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Burst_Statistics_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 36);
+
+/**
+ * Independent Analytics adapter.
+ *
+ * Imports one row per view from independent_analytics_views and resolves the
+ * resource through independent_analytics_resources.singular_id/post_type.
+ * Independent Analytics writes viewed_at in UTC. Only the timestamp and the
+ * product ID are imported; visitor/session identifiers are intentionally not
+ * accessed.
+ */
+if (!class_exists('STATPL_Independent_Analytics_Historical_Adapter')) {
+    final class STATPL_Independent_Analytics_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'independent_analytics';
+        const SOURCE_KEY = 'independent_analytics';
+        const ADAPTER_VERSION = '1.0.0';
+        const ORIGIN_KEY = 'product_view_events';
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'Independent Analytics'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function views_table() {
+            global $wpdb;
+            return $wpdb->prefix . 'independent_analytics_views';
+        }
+
+        private function resources_table() {
+            global $wpdb;
+            return $wpdb->prefix . 'independent_analytics_resources';
+        }
+
+        private function quote_table($table) {
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_tables() {
+            global $wpdb;
+            $found_any = false;
+            $missing_any = false;
+            foreach ([$this->views_table() => ['id', 'resource_id', 'viewed_at'], $this->resources_table() => ['id', 'singular_id', 'post_type']] as $table => $required) {
+                $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+                if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+                if ($exists !== $table) {
+                    $missing_any = true;
+                    continue;
+                }
+                $found_any = true;
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quote_table($table), ARRAY_A);
+                if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+                $names = [];
+                foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+                if (array_diff($required, $names)) { return ['status' => 'incompatible_schema']; }
+            }
+            if (!$found_any) { return ['status' => 'missing_table']; }
+            if ($missing_any) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $inspection = $this->inspect_tables();
+            if ($inspection['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $inspection = $this->inspect_tables();
+            if ($inspection['status'] === 'missing_table') { return []; }
+            return [[
+                'origin_key' => self::ORIGIN_KEY,
+                'capabilities' => ['product_views' => true, 'granularity' => 'event', 'timestamp_precision' => 'seconds', 'product_id_direct' => true],
+                'detection_status' => $inspection['status'],
+            ]];
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY) { return []; }
+            if ($this->inspect_tables()['status'] !== 'available') {
+                throw new RuntimeException('Independent Analytics tables are unavailable or incompatible.');
+            }
+            $posts_table = $this->quote_table($wpdb->posts);
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $max_id = statpl_db_get_var(statpl_db_prepare(
+                'SELECT MAX(v.id)
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->views_table()) . ' AS v
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->resources_table()) . ' AS r ON r.id = v.resource_id
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = r.singular_id AND p.post_type = %s
+                 WHERE r.post_type = %s AND r.singular_id > 0',
+                'product', 'product'
+            ));
+            if (!empty($wpdb->last_error)) {
+                throw new RuntimeException('Independent Analytics snapshot query failed.');
+            }
+            return [
+                'boundary' => ['max_id' => max(0, (int) $max_id)],
+                'initial_checkpoint' => null,
+                'captured_at' => current_time('mysql'),
+            ];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid Independent Analytics origin or snapshot.');
+            }
+            if ($this->inspect_tables()['status'] !== 'available') {
+                throw new RuntimeException('Independent Analytics tables became unavailable or incompatible.');
+            }
+            $max_id = isset($snapshot['boundary']['max_id']) ? absint($snapshot['boundary']['max_id']) : -1;
+            if ($max_id < 0) { throw new RuntimeException('Invalid Independent Analytics snapshot boundary.'); }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) {
+                $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']);
+            } elseif (is_numeric($checkpoint)) { $cursor_id = absint($checkpoint); }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table = $this->quote_table($wpdb->posts);
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $rows = statpl_db_get_results(statpl_db_prepare(
+                'SELECT v.id, r.singular_id AS product_id, v.viewed_at
+                 FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->views_table()) . ' AS v
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->resources_table()) . ' AS r ON r.id = v.resource_id
+                 INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = r.singular_id AND p.post_type = %s
+                 WHERE r.post_type = %s AND r.singular_id > 0 AND v.id > %d AND v.id <= %d
+                 ORDER BY v.id ASC
+                 LIMIT %d',
+                'product', 'product', $cursor_id, $max_id, $limit + 1
+            ), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($rows)) {
+                throw new RuntimeException('Independent Analytics batch query failed.');
+            }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if ($origin_key !== self::ORIGIN_KEY || !is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_id = isset($record['product_id']) ? absint($record['product_id']) : 0;
+            $viewed_at = isset($record['viewed_at']) ? trim((string) $record['viewed_at']) : '';
+            if (!$record_id || !$product_id || $viewed_at === '') { return null; }
+            $timestamp = strtotime(str_replace('T', ' ', $viewed_at) . ' UTC');
+            if (!$timestamp || !function_exists('wp_date')) { return null; }
+            $datetime = wp_date('Y-m-d H:i:s', $timestamp);
+            if (!is_string($datetime) || !preg_match('/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/D', $datetime)) { return null; }
+            return [
+                'product_id' => $product_id,
+                'source_record_key' => 'independent_analytics_view_' . $record_id,
+                'views' => 1,
+                'record_type' => 'event',
+                'period_start' => $datetime,
+                'period_end' => $datetime,
+                'cursor' => $record_id,
+            ];
+        }
+
+        public function get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event) {
+            return [
+                'source' => 'independent_analytics',
+                'timestamp_precision' => 'seconds',
+                'overlap_assessment' => 'possible_but_not_proven',
+                'automatic_suppression' => false,
+                'reason' => 'Independent Analytics provides a per-view timestamp and product ID, but no stable event identifier shared with other providers.',
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_Independent_Analytics_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 37);
+
+/**
+ * PulseViews adapter.
+ *
+ * Uses disjoint date windows: completed daily aggregates through two days ago,
+ * then non-bot raw events after that boundary. Weekly/monthly rollups and the
+ * lifetime totals cache are never imported, preventing overlap. PulseViews
+ * prunes raw events after 90 days but retains its daily aggregate history.
+ */
+if (!class_exists('STATPL_PulseViews_Historical_Adapter')) {
+    final class STATPL_PulseViews_Historical_Adapter implements STATPL_Historical_View_Adapter {
+        const ADAPTER_KEY = 'pulseviews';
+        const SOURCE_KEY = 'pulseviews';
+        const ADAPTER_VERSION = '1.0.0';
+        const DAILY_ORIGIN = 'daily_aggregates';
+        const RAW_ORIGIN = 'recent_raw_views';
+        private $snapshot_through_date = null;
+        private $snapshot_captured_at = null;
+
+        private function get_snapshot_through_date() {
+            if ($this->snapshot_through_date === null) {
+                $this->snapshot_through_date = current_datetime()->modify('-2 days')->format('Y-m-d');
+            }
+            return $this->snapshot_through_date;
+        }
+
+        private function get_snapshot_captured_at() {
+            if ($this->snapshot_captured_at === null) {
+                $this->snapshot_captured_at = current_time('mysql');
+            }
+            return $this->snapshot_captured_at;
+        }
+
+        public function get_adapter_key() { return self::ADAPTER_KEY; }
+        public function get_source_key() { return self::SOURCE_KEY; }
+        public function get_display_name() { return 'PulseViews'; }
+        public function get_adapter_version() { return self::ADAPTER_VERSION; }
+
+        private function table_name($kind) {
+            global $wpdb;
+            if (!in_array($kind, ['daily', 'raw'], true)) {
+                throw new InvalidArgumentException('Unsupported PulseViews table kind.');
+            }
+            return $wpdb->prefix . ($kind === 'daily' ? 'pulseviews_aggregates' : 'pulseviews_views');
+        }
+
+        private function quote_table($table) {
+            if (!is_string($table) || !preg_match('/^[A-Za-z0-9_]+$/D', $table)) {
+                throw new InvalidArgumentException('Invalid historical analytics table identifier.');
+            }
+            return '`' . $table . '`';
+        }
+
+        private function inspect_table($kind) {
+            global $wpdb;
+            $table = $this->table_name($kind);
+            $exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($table)));
+            if (!empty($wpdb->last_error)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            if ($exists !== $table) { return ['status' => 'missing_table']; }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $columns = statpl_db_get_results('SHOW COLUMNS FROM ' . $this->quote_table($table), ARRAY_A);
+            if (!empty($wpdb->last_error) || !is_array($columns)) { return ['status' => 'database_error', 'error' => (string) $wpdb->last_error]; }
+            $names = [];
+            foreach ($columns as $column) { if (isset($column['Field'])) { $names[] = strtolower((string) $column['Field']); } }
+            $required = $kind === 'daily'
+                ? ['id', 'post_id', 'period_date', 'period_type', 'view_count']
+                : ['id', 'post_id', 'viewed_at', 'is_bot'];
+            if (array_diff($required, $names)) { return ['status' => 'incompatible_schema']; }
+            return ['status' => 'available'];
+        }
+
+        public function should_register_adapter() {
+            global $wpdb;
+            $daily = $this->inspect_table('daily');
+            $raw = $this->inspect_table('raw');
+            if ($daily['status'] !== 'missing_table' || $raw['status'] !== 'missing_table') { return true; }
+            $registry_name = $wpdb->prefix . 'statpl_view_sources';
+            if (!is_string($registry_name) || !preg_match('/^[A-Za-z0-9_]+$/D', $registry_name)) {
+                throw new InvalidArgumentException('Invalid Statora source registry table identifier.');
+            }
+            $registry_table = '`' . $registry_name . '`';
+            $registry_exists = statpl_db_get_var(statpl_db_prepare('SHOW TABLES LIKE %s', $wpdb->esc_like($registry_name)));
+            if (!empty($wpdb->last_error)) { return true; }
+            if ($registry_exists !== $registry_name) { return false; }
+            // phpcs:ignore PluginCheck.Security.DirectDB.UnescapedDBParameter -- $registry_table is the quoted WordPress-prefixed Statora registry identifier; its raw name is validated against ^[A-Za-z0-9_]+$ before quoting, while source_key is a prepared value.
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+            $source_id = statpl_db_get_var(statpl_db_prepare('SELECT id FROM ' . $registry_table . ' WHERE source_key = %s LIMIT 1', self::SOURCE_KEY));
+            return !empty($wpdb->last_error) || !empty($source_id);
+        }
+
+        public function discover_origins() {
+            $origins = [];
+            $daily = $this->inspect_table('daily');
+            if ($daily['status'] !== 'missing_table') {
+                $origins[] = [
+                    'origin_key' => self::DAILY_ORIGIN,
+                    'capabilities' => ['product_views' => true, 'granularity' => 'daily_aggregate', 'window' => 'through_two_days_ago'],
+                    'detection_status' => $daily['status'],
+                ];
+            }
+            $raw = $this->inspect_table('raw');
+            if ($raw['status'] !== 'missing_table') {
+                $origins[] = [
+                    'origin_key' => self::RAW_ORIGIN,
+                    'capabilities' => ['product_views' => true, 'granularity' => 'event', 'window' => 'after_daily_aggregate_boundary', 'bot_filtered' => true],
+                    'detection_status' => $raw['status'],
+                ];
+            }
+            return $origins;
+        }
+
+        public function get_origin_snapshot($origin_key) {
+            global $wpdb;
+            $through_date = $this->get_snapshot_through_date();
+            $posts_table = $this->quote_table($wpdb->posts);
+            if ($origin_key === self::DAILY_ORIGIN) {
+                if ($this->inspect_table('daily')['status'] !== 'available') {
+                    throw new RuntimeException('PulseViews daily aggregate table is unavailable or incompatible.');
+                }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $max_id = statpl_db_get_var(statpl_db_prepare(
+                    'SELECT MAX(a.id)
+                     FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->table_name('daily')) . ' AS a
+                     INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = a.post_id AND p.post_type = %s
+                     WHERE a.period_type = %s AND a.period_date <= %s',
+                    'product', 'day', $through_date
+                ));
+                if (!empty($wpdb->last_error)) { throw new RuntimeException('PulseViews daily snapshot query failed.'); }
+                return ['boundary' => ['max_id' => max(0, (int) $max_id), 'through_date' => $through_date], 'initial_checkpoint' => null, 'captured_at' => current_time('mysql')];
+            }
+            if ($origin_key === self::RAW_ORIGIN) {
+                if ($this->inspect_table('raw')['status'] !== 'available') {
+                    throw new RuntimeException('PulseViews raw views table is unavailable or incompatible.');
+                }
+                $after_datetime = $through_date . ' 23:59:59';
+                $captured_at = $this->get_snapshot_captured_at();
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $max_id = statpl_db_get_var(statpl_db_prepare(
+                    'SELECT MAX(v.id)
+                     FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->table_name('raw')) . ' AS v
+                     INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = v.post_id AND p.post_type = %s
+                     WHERE v.is_bot = 0 AND v.viewed_at > %s AND v.viewed_at <= %s',
+                    'product', $after_datetime, $captured_at
+                ));
+                if (!empty($wpdb->last_error)) { throw new RuntimeException('PulseViews raw snapshot query failed.'); }
+                return ['boundary' => ['max_id' => max(0, (int) $max_id), 'after_datetime' => $after_datetime, 'captured_at' => $captured_at], 'initial_checkpoint' => null, 'captured_at' => $captured_at];
+            }
+            return [];
+        }
+
+        public function get_product_view_batch($origin_key, $checkpoint, $snapshot, $limit) {
+            global $wpdb;
+            if (!is_array($snapshot) || empty($snapshot['boundary']) || !is_array($snapshot['boundary'])) {
+                throw new RuntimeException('Invalid PulseViews snapshot.');
+            }
+            $cursor_id = 0;
+            if (is_array($checkpoint) && isset($checkpoint['cursor'])) { $cursor_id = $checkpoint['cursor'] === null ? 0 : absint($checkpoint['cursor']); }
+            elseif (is_numeric($checkpoint)) { $cursor_id = absint($checkpoint); }
+            $max_id = isset($snapshot['boundary']['max_id']) ? absint($snapshot['boundary']['max_id']) : -1;
+            if ($max_id < 0) { throw new RuntimeException('Invalid PulseViews snapshot boundary.'); }
+            $limit = max(1, min(100, absint($limit)));
+            $posts_table = $this->quote_table($wpdb->posts);
+            if ($origin_key === self::DAILY_ORIGIN) {
+                if ($this->inspect_table('daily')['status'] !== 'available') { throw new RuntimeException('PulseViews daily aggregate table became unavailable.'); }
+                $through_date = isset($snapshot['boundary']['through_date']) ? (string) $snapshot['boundary']['through_date'] : '';
+                $parsed = DateTime::createFromFormat('!Y-m-d', $through_date);
+                if (!$parsed || $parsed->format('Y-m-d') !== $through_date) { throw new RuntimeException('Invalid PulseViews daily boundary.'); }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    'SELECT a.id, a.post_id, a.period_date, a.view_count
+                     FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->table_name('daily')) . ' AS a
+                     INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = a.post_id AND p.post_type = %s
+                     WHERE a.period_type = %s AND a.id > %d AND a.id <= %d AND a.period_date <= %s
+                     ORDER BY a.id ASC
+                     LIMIT %d',
+                    'product', 'day', $cursor_id, $max_id, $through_date, $limit + 1
+                ), ARRAY_A);
+            } elseif ($origin_key === self::RAW_ORIGIN) {
+                if ($this->inspect_table('raw')['status'] !== 'available') { throw new RuntimeException('PulseViews raw views table became unavailable.'); }
+                $after_datetime = isset($snapshot['boundary']['after_datetime']) ? (string) $snapshot['boundary']['after_datetime'] : '';
+                $captured_at = isset($snapshot['boundary']['captured_at']) ? (string) $snapshot['boundary']['captured_at'] : '';
+                if ($after_datetime === '' || $captured_at === '') { throw new RuntimeException('Invalid PulseViews raw boundary.'); }
+// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- This query is prepared at execution; dynamic identifiers/fragments are constrained by validated identifiers, fixed allowlists or generated placeholders, and runtime values use placeholders.
+                $rows = statpl_db_get_results(statpl_db_prepare(
+                    'SELECT v.id, v.post_id, v.viewed_at
+                     FROM ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $this->quote_table($this->table_name('raw')) . ' AS v
+                     INNER JOIN ' . /* phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared -- The flagged fragment is part of a prepared statement; dynamic identifiers/fragments are built from validated WordPress table names or fixed allowlists, while runtime values use placeholders. */ $posts_table . ' AS p ON p.ID = v.post_id AND p.post_type = %s
+                     WHERE v.is_bot = 0 AND v.id > %d AND v.id <= %d AND v.viewed_at > %s AND v.viewed_at <= %s
+                     ORDER BY v.id ASC
+                     LIMIT %d',
+                    'product', $cursor_id, $max_id, $after_datetime, $captured_at, $limit + 1
+                ), ARRAY_A);
+            } else {
+                throw new RuntimeException('Unknown PulseViews origin.');
+            }
+            if (!empty($wpdb->last_error) || !is_array($rows)) { throw new RuntimeException('PulseViews batch query failed.'); }
+            $has_more = count($rows) > $limit;
+            if ($has_more) { $rows = array_slice($rows, 0, $limit); }
+            $next = $cursor_id;
+            if ($rows) { $last = end($rows); $next = absint($last['id']); }
+            return ['rows' => array_values($rows), 'has_more' => $has_more, 'next_checkpoint' => $next, 'boundary_applied' => true];
+        }
+
+        public function normalize_record($origin_key, $record) {
+            if (!is_array($record)) { return null; }
+            $record_id = isset($record['id']) ? absint($record['id']) : 0;
+            $product_id = isset($record['post_id']) ? absint($record['post_id']) : 0;
+            if (!$record_id || !$product_id) { return null; }
+            if ($origin_key === self::DAILY_ORIGIN) {
+                $date = isset($record['period_date']) ? (string) $record['period_date'] : '';
+                $views_raw = $record['view_count'] ?? null;
+                if (!preg_match('/^(0|[1-9][0-9]*)$/D', (string) $views_raw)) { return null; }
+                $parsed = DateTime::createFromFormat('!Y-m-d', $date);
+                $errors = DateTime::getLastErrors();
+                if (!$parsed || $parsed->format('Y-m-d') !== $date || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+                $views = (int) $views_raw;
+                $period_start = $date . ' 00:00:00';
+                $period_end = $date . ' 23:59:59';
+                return ['product_id' => $product_id, 'source_record_key' => 'pulseviews_day_' . $product_id . '_' . $date, 'views' => $views, 'record_type' => 'aggregate', 'period_start' => $period_start, 'period_end' => $period_end, 'cursor' => $record_id];
+            }
+            if ($origin_key === self::RAW_ORIGIN) {
+                $viewed_at = isset($record['viewed_at']) ? (string) $record['viewed_at'] : '';
+                $parsed = DateTime::createFromFormat('!Y-m-d H:i:s', $viewed_at);
+                $errors = DateTime::getLastErrors();
+                if (!$parsed || $parsed->format('Y-m-d H:i:s') !== $viewed_at || ($errors !== false && (!empty($errors['warning_count']) || !empty($errors['error_count'])))) { return null; }
+                return ['product_id' => $product_id, 'source_record_key' => 'pulseviews_view_' . $record_id, 'views' => 1, 'record_type' => 'event', 'period_start' => $viewed_at, 'period_end' => $viewed_at, 'cursor' => $record_id];
+            }
+            return null;
+        }
+
+        public function get_reconciliation_evidence($origin_key, $normalized_record, $candidate_event) {
+            return [
+                'source' => 'pulseviews',
+                'origin' => $origin_key,
+                'overlap_assessment' => 'possible_but_not_proven',
+                'automatic_suppression' => false,
+                'reason' => 'PulseViews event rows have local timestamps but no stable cross-provider event identifier; daily aggregates are matched only on exact product/date/count dimensions.',
+            ];
+        }
+    }
+}
+
+add_filter('statpl_historical_view_adapters', static function ($adapters) {
+    if (!is_array($adapters)) { return $adapters; }
+    $adapter = new STATPL_PulseViews_Historical_Adapter();
+    if ($adapter->should_register_adapter()) { $adapters[] = $adapter; }
+    return $adapters;
+}, 38);