includes/Insight/class-ai-adaptive.php
AI Adaptive optimization — RUM → heuristic/auto-tune via suggestions.
Class AI_Adaptive
Learns from RUM + trends + asset-usage heuristics and produces suggestion objects for file_optimisation / preload_settings.
class AI_AdaptiveConstants
| Constant | Visibility | Value | Line |
|---|---|---|---|
OPTION | public | \'wppo_ai_model\' | 42 |
LEARN_LOCK | private | \'wppo_ai_learn_lock\' | 49 |
INP_P75_DELAY_THRESHOLD_MS | public | 200.0 | 628 |
INP_P75_EAGER_THRESHOLD_MS | public | 500.0 | 638 |
LCP_P75_DELAY_THRESHOLD_MS | public | 2500.0 | 649 |
LCP_P75_EAGER_THRESHOLD_MS | public | 3500.0 | 657 |
Properties
| Property | Visibility | Type | Default | Line |
|---|---|---|---|---|
$model_memo | private static | ?array | null | 35 |
$disabled_assets_cache | private static | array | array() | 1930 |
publicstatic is_enabled()
public static function is_enabled(): boolWhether AI adaptive optimization is enabled.
Return: bool.
publicstatic get_model()
public static function get_model(): arrayGet the stored model (per-request memoized).
Return: array.
publicstatic reset_model_memo()
public static function reset_model_memo(): voidReset the per-request model memo (for testing).
Return: void.
publicstatic reset_runtime_state()
public static function reset_runtime_state(): voidReset all AI-owned per-blog request memos.
Return: void.
publicstatic reset_rum_anomaly_digest_memo()
public static function reset_rum_anomaly_digest_memo(): voidFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::reset_rum_anomaly_digest_memo}.
Return: void.
publicstatic update_model()
public static function update_model(array $model): voidPersist the model with autoload=no. Parameter Type Default Description $modelarray— Model data.
Return: void.
publicstatic is_commerce_or_auth_context()
public static function is_commerce_or_auth_context(): boolWhether the current request runs in a commerce or authenticated context.
Return: bool — True when a commerce/auth context is detected.
privatestatic detect_commerce_or_auth_context()
private static function detect_commerce_or_auth_context(): boolInternal helper to detect commerce or auth context using early returns.
Return: bool — True when a commerce/auth context is detected.
publicstatic get_commerce_exclude_paths()
public static function get_commerce_exclude_paths(): arrayCommerce/auth URL exclusion patterns for speculation suggestions.
Return: string[].
privatestatic is_frontend_context()
private static function is_frontend_context(): boolWhether the current request is a frontend visitor context.
Return: bool — True when the request looks like a frontend visit.
privatestatic normalize_eagerness()
private static function normalize_eagerness($eagerness): stringNormalize an eagerness value: allowlist then commerce/auth cap. Parameter Type Default Description $eagernessmixed— Raw eagerness value.
Return: string — Normalized eagerness value.
publicstatic maybe_cap_eagerness()
public static function maybe_cap_eagerness(string $eagerness): stringCap an AI-learned eagerness value at `moderate` in commerce/auth contexts. Parameter Type Default Description $eagernessstring— Learned eagerness value.
Return: string — Capped eagerness value.
publicstatic is_wp_ai_client_enabled()
public static function is_wp_ai_client_enabled(): boolWhether the optional WordPress AI client path is enabled.
Return: bool.
privatestatic is_valid_suggestion()
private static function is_valid_suggestion($s): boolValidate a suggestion object shape before display. Parameter Type Default Description $smixed— Candidate suggestion.
Return: bool — True when the shape is valid.
publicstatic learn()
public static function learn(): arrayLearn from RUM + trends + disabled-script frequency.
Return: array — The updated model.
privatestatic learn_via_ai_client()
private static function learn_via_ai_client(?array=null $rum, ?array=null $trends): ?arrayAttempt learning via WP 7.0 AI Client when available. Parameter Type Default Description $rum?array=null— Optional pre-loaded RUM aggregate (loaded once per learn run). $trends?array=null— Optional pre-loaded trends aggregate.
Return: array|null — Model or null on fallback.
privatestatic segmented_field_lcp()
private static function segmented_field_lcp(int=1 $min_samples): arrayRead segmented field-LCP p75 rows (device × template × connection) fail-open. Parameter Type Default Description $min_samplesint=1— Minimum samples per segment (1 = observe all).
Return: array[] — Rows of array(path,device,template,connection,n,p75).
privatestatic segmented_field_inp()
private static function segmented_field_inp(int=1 $min_samples): arrayRead segmented field-INP p75 rows (device × template × connection) fail-open. Parameter Type Default Description $min_samplesint=1— Minimum samples per segment (1 = observe all).
Return: array[] — Rows of array(path,device,template,connection,n,p75).
privatestatic segment_connection()
private static function segment_connection($row): stringExtract the connection segment from a RUM segment row fail-open. Parameter Type Default Description $rowmixed— Segment row.
Return: string — Allowlisted connection type or \’unknown\’.
privatestatic segment_descriptor()
private static function segment_descriptor($row): arrayBuild a segment descriptor from a RUM segment row fail-open. Parameter Type Default Description $rowmixed— Segment row.
Return: array{path:string,device:string,template:string,connection:string} — Segment descriptor.
privatestatic slowest_segment_row()
private static function slowest_segment_row(array $rows): ?arrayPick the slowest-p75 segment row from qualified rows (slowest-first). Parameter Type Default Description $rowsarray— Qualified segment rows.
Return: array|null — Slowest row or null when empty.
publicstatic get_slow_top_path_state()
public static function get_slow_top_path_state(): arrayRUM-driven slow-top-path state for heuristic auto-tune (read-only, fail-open).
Return: array{slow:bool,path:string,segment:array|null,p75:float,samples:int,min_samples:int,preload_url:string} — Slow-path state.
publicstatic get_slow_path_downgrade_target()
public static function get_slow_path_downgrade_target(string $eagerness): stringDowngrade target for a slow top path (one eagerness step down, floored). Parameter Type Default Description $eagernessstring— Current learned eagerness.
Return: string — Downgraded eagerness.
privatestatic eagerness_level()
private static function eagerness_level(string $eagerness): intNumeric level for an allowlisted eagerness value (ladder helper). Parameter Type Default Description $eagernessstring— Allowlisted eagerness value.
Return: int — Numeric ladder level (0-2).
privatestatic eagerness_from_level()
private static function eagerness_from_level(int $level): stringEagerness value for a numeric ladder level (ladder helper). Parameter Type Default Description $levelint— Numeric ladder level.
Return: string — Allowlisted eagerness value.
privatestatic slow_segment_labels()
private static function slow_segment_labels($segment): arrayDevice/template/connection labels for a slow-path segment. Parameter Type Default Description $segmentmixed— Segment descriptor (or null).
Return: array{0:string,1:string,2:string} — Device, template, connection labels.
privatestatic sanitize_slow_preload_url()
private static function sanitize_slow_preload_url($url): stringSanitize a persisted/live slow-path preload URL for suggestion copy. Parameter Type Default Description $urlmixed— Raw URL value.
Return: string — Sanitized URL or \’\’ when invalid.
publicstatic get_dismissed_suggestions()
public static function get_dismissed_suggestions(): arrayDismissed AI suggestion metrics (persisted, per-site).
Return: string[] — Dismissed metric identifiers.
publicstatic is_suggestion_dismissed()
public static function is_suggestion_dismissed(string $metric): boolWhether an AI suggestion metric has been dismissed. Parameter Type Default Description $metricstring— Suggestion metric identifier.
Return: bool — True when dismissed.
publicstatic get_rum_gated_delay_state()
public static function get_rum_gated_delay_state(): arrayRUM-gated, INP-aware delay-JS state (read-only, fail-open).
Return: array{qualified:bool,level:string,inp_p75:float,lcp_p75:float,samples:int,min_samples:int,provisional:bool,segment:array|null} — Gated state.
privatestatic field_lcp_min_samples()
private static function field_lcp_min_samples(): intResolve the field-LCP minimum-sample threshold for auto-tune.
Return: int — Minimum samples (>=1).
privatestatic format_p75_seconds()
private static function format_p75_seconds(float $p75_ms): stringFormat a p75 millisecond value as seconds for suggestion copy. Parameter Type Default Description $p75_msfloat— p75 in milliseconds.
Return: string — e.g. \”3.8s\”.
privatestatic summarize_aggregates_for_prompt()
private static function summarize_aggregates_for_prompt(array $rum, array $trends): arraySummarize large aggregates into a bounded prompt projection. Parameter Type Default Description $rumarray— RUM aggregate. $trendsarray— Trends aggregate.
Return: array{rum:array,trends:array} — Bounded summary.
privatestatic heuristic_learn()
private static function heuristic_learn(?array=null $rum, ?array=null $trends): arrayHeuristic fallback learning. Parameter Type Default Description $rum?array=null— Optional pre-loaded RUM aggregate. $trends?array=null— Optional pre-loaded trends aggregate.
Return: array.
publicstatic get_deploy_notes()
public static function get_deploy_notes(): arrayFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::get_deploy_notes}.
Return: array — Result (see Ai_Anomaly).
publicstatic add_deploy_note()
public static function add_deploy_note(string $note, ?int=null $ts): boolFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::add_deploy_note}. Parameter Type Default Description $notestring— Parameter (see Ai_Anomaly). $ts?int=null— Parameter (see Ai_Anomaly).
Return: bool — Result (see Ai_Anomaly).
publicstatic find_deploy_note_near()
public static function find_deploy_note_near(int $breach_ts): stringFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::find_deploy_note_near}. Parameter Type Default Description $breach_tsint— Parameter (see Ai_Anomaly).
Return: string — Result (see Ai_Anomaly).
publicstatic get_breach_state()
public static function get_breach_state(): arrayFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::get_breach_state}.
Return: array — Result (see Ai_Anomaly).
publicstatic set_breach_state()
public static function set_breach_state(array $state): voidFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::set_breach_state}. Parameter Type Default Description $statearray— Parameter (see Ai_Anomaly).
Return: void.
publicstatic detect_recoveries()
public static function detect_recoveries(?array=null $trends, ?int=null $now): arrayFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::detect_recoveries}. Parameter Type Default Description $trends?array=null— Parameter (see Ai_Anomaly). $now?int=null— Parameter (see Ai_Anomaly).
Return: array — Result (see Ai_Anomaly).
publicstatic get_last_anomaly_alarm()
public static function get_last_anomaly_alarm(): intFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::get_last_anomaly_alarm}.
Return: int — Result (see Ai_Anomaly).
publicstatic set_last_anomaly_alarm()
public static function set_last_anomaly_alarm(int $ts): voidFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::set_last_anomaly_alarm}. Parameter Type Default Description $tsint— Parameter (see Ai_Anomaly).
Return: void.
publicstatic is_anomaly_cooled_down()
public static function is_anomaly_cooled_down(?int=null $now): boolFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::is_anomaly_cooled_down}. Parameter Type Default Description $now?int=null— Parameter (see Ai_Anomaly).
Return: bool — Result (see Ai_Anomaly).
publicstatic get_rum_anomaly_digest()
public static function get_rum_anomaly_digest(?array=null $rum, ?int=null $now): arrayFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::get_rum_anomaly_digest}. Parameter Type Default Description $rum?array=null— Parameter (see Ai_Anomaly). $now?int=null— Parameter (see Ai_Anomaly).
Return: array — Result (see Ai_Anomaly).
publicstatic detect_anomalies()
public static function detect_anomalies(?array=null $trends, ?array=null $rum, ?int=null $now): arrayFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::detect_anomalies}. Parameter Type Default Description $trends?array=null— Parameter (see Ai_Anomaly). $rum?array=null— Parameter (see Ai_Anomaly). $now?int=null— Parameter (see Ai_Anomaly).
Return: array — Result (see Ai_Anomaly).
publicstatic is_css_refresh_enabled()
public static function is_css_refresh_enabled(): boolFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::is_css_refresh_enabled}.
Return: bool — Result (see Ai_Anomaly).
publicstatic css_refresh_cooldown_days()
public static function css_refresh_cooldown_days(): intFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::css_refresh_cooldown_days}.
Return: int — Result (see Ai_Anomaly).
publicstatic resolve_anomaly_url()
public static function resolve_anomaly_url(string $trend_key): stringFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::resolve_anomaly_url}. Parameter Type Default Description $trend_keystring— Parameter (see Ai_Anomaly).
Return: string — Result (see Ai_Anomaly).
publicstatic is_homepage_url()
public static function is_homepage_url(string $url): boolFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::is_homepage_url}. Parameter Type Default Description $urlstring— Parameter (see Ai_Anomaly).
Return: bool — Result (see Ai_Anomaly).
publicstatic resolve_front_page_post_id()
public static function resolve_front_page_post_id(): intFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::resolve_front_page_post_id}.
Return: int — Result (see Ai_Anomaly).
publicstatic resolve_anomaly_post_id()
public static function resolve_anomaly_post_id(string $url): intFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::resolve_anomaly_post_id}. Parameter Type Default Description $urlstring— Parameter (see Ai_Anomaly).
Return: int — Result (see Ai_Anomaly).
publicstatic get_css_refresh_snapshot()
public static function get_css_refresh_snapshot(string $url): arrayFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::get_css_refresh_snapshot}. Parameter Type Default Description $urlstring— Parameter (see Ai_Anomaly).
Return: array — Result (see Ai_Anomaly).
publicstatic maybe_queue_css_refresh()
public static function maybe_queue_css_refresh(array $anomaly, ?int=null $now): arrayFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::maybe_queue_css_refresh}. Parameter Type Default Description $anomalyarray— Parameter (see Ai_Anomaly). $now?int=null— Parameter (see Ai_Anomaly).
Return: array — Result (see Ai_Anomaly).
publicstatic get_anomaly_provisional_state()
public static function get_anomaly_provisional_state(?array=null $trends, ?array=null $rum, ?int=null $now): arrayFacade proxy (ARCH-010): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ai_Anomaly::get_anomaly_provisional_state}. Parameter Type Default Description $trends?array=null— Parameter (see Ai_Anomaly). $rum?array=null— Parameter (see Ai_Anomaly). $now?int=null— Parameter (see Ai_Anomaly).
Return: array — Result (see Ai_Anomaly).
publicstatic reset_disabled_assets_cache()
public static function reset_disabled_assets_cache(): voidReset the per-request disabled-asset memo (for testing).
Return: void.
privatestatic top_disabled_handles()
private static function top_disabled_handles(array $rows): arrayRank serialized handle lists into top-3 handles by frequency. Parameter Type Default Description $rowsarray— Raw meta_value strings.
Return: string[].
privatestatic get_disabled_assets()
private static function get_disabled_assets(string $meta_key): arrayGet most-frequently disabled assets from postmeta. Parameter Type Default Description $meta_keystring— The meta key to query.
Return: string[].
publicstatic get_prefetch_urls()
public static function get_prefetch_urls(): arrayGet AI-learned prefetch URLs (top-2).
Return: string[].
privatestatic get_prefetch_urls_from_model()
private static function get_prefetch_urls_from_model(array $model): arrayExtract top-2 sanitized prefetch URLs from a model array. Parameter Type Default Description $modelarray— Model data.
Return: string[].
publicstatic get_suggestions()
public static function get_suggestions(): arrayGenerate suggestion objects for the suggestion engine.
Return: array[].
publicstatic is_speculation_rum_gating_enabled()
public static function is_speculation_rum_gating_enabled(): boolWhether RUM-gated speculation eagerness is enabled.
Return: bool — True when RUM gating applies.
publicstatic is_speculation_autotune_enabled()
public static function is_speculation_autotune_enabled(): boolWhether RUM-segmented speculation auto-tune is enabled (issue #1425).
Return: bool — True when the RUM-segmented per-URL auto-tune applies.
publicstatic speculation_min_samples()
public static function speculation_min_samples(): intMinimum RUM samples for the speculation auto-tune (issue #1425).
Return: int — Minimum samples (>=1).
publicstatic speculation_max_urls()
public static function speculation_max_urls(): intMaximum per-URL list-rule URLs for the speculation auto-tune (issue #1425).
Return: int — Maximum URLs (1-5).
publicstatic trim_speculation_urls_to_budget()
public static function trim_speculation_urls_to_budget(array $urls, int=1024 $budget_bytes): arrayTrim a candidate list-rule URL set so its JSON delta stays under budget. Parameter Type Default Description $urlsarray— Candidate absolute URLs (rank-ordered). $budget_bytesint=1024— Maximum encoded size in bytes.
Return: string[].
publicstatic get_rum_gated_speculation_state()
public static function get_rum_gated_speculation_state(?bool=null $gating_enabled, ?int=null $min_samples_override): arrayRUM-gated speculation eagerness state (read-only, fail-open). Parameter Type Default Description $gating_enabled?bool=null— Pre-resolved gating flag. Null resolves via is_speculation_rum_gating_enabled(). $min_samples_override?int=null— Optional minimum-samples override (e.g. speculation_min_samples()). Null uses the shared field_lcp_min_samples() gate.
Return: array{qualified:bool,eagerness:string,lcp_p75:float,inp_p75:float,samples:int,min_samples:int,gated:bool} — Gated state.
privatestatic validate_speculation_threshold()
private static function validate_speculation_threshold($value, float $fallback): floatValidate a RUM-gated speculation p75 threshold from a filter value. Parameter Type Default Description $valuemixed— Raw filter value. $fallbackfloat— Fallback threshold.
Return: float — Validated threshold (>= 0 and finite).
privatestatic is_speculation_commerce_url()
private static function is_speculation_commerce_url(string $url, array $excludes): boolWhether an absolute URL falls under a commerce exclude prefix. Parameter Type Default Description $urlstring— Absolute URL. $excludesarray— Commerce exclude prefixes (e.g. `/cart/*`).
Return: bool — True when the URL path matches a commerce prefix.
publicstatic peak_rum_metric_samples()
public static function peak_rum_metric_samples(array $metrics): intPeak per-bucket sample count across all RUM metrics (issue #1425). Parameter Type Default Description $metricsarray— Single path-bucket metric map.
Return: int — Peak `n` (>= 0).
publicstatic get_rum_top_speculation_urls()
public static function get_rum_top_speculation_urls(int=5 $limit): arrayTop RUM (real-visit) URLs for the RUM-gated speculation list rule. Parameter Type Default Description $limitint=5— Maximum URLs to return.
Return: string[].
privatestatic is_speculation_hard_suppressed()
private static function is_speculation_hard_suppressed(): boolWhether the AI speculation rule is hard-suppressed for this request.
Return: bool — True when no AI rule must be emitted.
privatestatic get_autotuned_speculation_rule()
private static function get_autotuned_speculation_rule($rules, ?int=null $min_override, ?int=null $max_override)Build the RUM-segmented auto-tuned list rule (issue #1425). Parameter Type Default Description $rulesarray— Incoming speculation rules (core default). $min_override?int=null— Optional pre-resolved minimum samples (avoids an extra settings read on the hot path). $max_override?int=null— Optional pre-resolved maximum URLs (avoids an extra settings read on the hot path).
Return: array|null — Rules with the auto-tuned list rule appended, the input unchanged, or null on failure.
privatestatic sanitize_speculation_rules_after_filter()
private static function sanitize_speculation_rules_after_filter($filtered, array $fallback, int $max, bool=true $strict): arrayRe-apply the auto-tune guard pipeline to post-filter speculation rules. Parameter Type Default Description $filteredmixed— Filtered rules (untrusted). $fallbackarray— Pre-filter rules (guarded). $maxint— Maximum URLs per list rule (1-5). $strictbool=true— When false, commerce/eager guards are contextual.
Return: array — Sanitized rules.
publicstatic filter_speculation_rules()
public static function filter_speculation_rules($rules)Inject AI-learned prefetch URLs into speculation rules. Parameter Type Default Description $rulesarray— Speculation rules array.
Return: array.
privatestatic filter_same_site_urls()
private static function filter_same_site_urls(array $urls): arrayKeep only same-site, non-admin, non-commerce list URLs. Parameter Type Default Description $urlsarray— Candidate URLs.
Return: string[].
privatestatic dedupe_against_existing_lists()
private static function dedupe_against_existing_lists(array $urls, array $rules): arrayRemove URLs already covered by an existing list-source rule. Parameter Type Default Description $urlsarray— Candidate AI URLs. $rulesarray— Existing speculation rules.
Return: string[].
publicstatic init()
public static function init(): voidRegister hooks.
Return: void.
Hooks
Hooks referenced in includes/Insight/class-ai-adaptive.php: Hook Type Line Notes wppo_ai_adaptive_enabledfilter 70 @param ×1 wppo_ai_adaptive_commerce_contextfilter 179 @param ×1 wppo_ai_adaptive_use_wp_clientfilter 442 @param ×1 wppo_ai_adaptive_eagernessfilter 1570 @param ×2 wppo_ai_speculation_rum_gatingfilter 2934 @param ×1 wppo_ai_speculation_autotune_enabledfilter 2966 @param ×1 wppo_ai_speculation_lcp_thresholdfilter 3192 @param ×1 wppo_ai_speculation_inp_thresholdfilter 3199 @param ×1 wppo_ai_speculation_eagernessfilter 3214 @param ×2 wppo_ai_speculation_top_urlsfilter 3446 @param ×1 wppo_ai_adaptive_speculation_rulesfilter 3647 @param ×2 wppo_ai_speculation_autotune_enabledfilter 3802 — wppo_ai_speculation_rum_gatingfilter 3813 — wppo_ai_adaptive_speculation_rulesfilter 3910 @param ×2