__( 'Signal inventory (what this site measures)', 'ai-eshop-optimizer' ), 'description' => __( 'The plugin\'s curated catalogue of the signals it computes— label, what it measures, grain, table, producing class/sproc, cron hook, consumers — enriched with live health: row counts, whether the producing cron is scheduled, and a state (healthy / empty / dormant / absent / unconsumed). Call this BEFORE proposing or building any new metric, scorer or rollup: most behavioural, order, customer, forecasting and SEO signals already exist here. Also the fastest way to answer "why is this report empty" (the answer is usually a dormant producer or a starved upstream) and "what are we computing that nobody reads". NOT exhaustive: it is a hand-maintained catalogue of the measurement estate, not a scan of every table, so a miss here is NOT proof the capability is absent — grep the tree before concluding anything has to be built.', 'ai-eshop-optimizer' ), 'category' => \AIEO\Claude\Bootstrap::CATEGORY, 'input_schema' => self::input_schema(), 'output_schema' => array( 'type' => 'object' ), 'execute_callback' => array( __CLASS__, 'execute' ), 'permission_callback' => array( __CLASS__, 'permission_check' ), 'meta' => array( 'annotations' => array( 'readonly' => true, 'idempotent' => true, ), 'show_in_rest' => true, ), ) ); } public static function permission_check( $input = null ) { unset( $input ); return current_user_can( 'manage_woocommerce' ) || current_user_can( 'manage_options' ); } private static function input_schema() { return array( 'default' => array(), 'type' => 'object', 'properties' => array( 'state' => array( 'type' => 'string', 'enum' => array( 'any', 'healthy', 'empty', 'dormant', 'absent', 'unconsumed', 'not_applicable' ), 'default' => 'any', 'description' => 'Filter by health state. "dormant" = code ships but the signal has never produced output and nothing schedules it. "unconsumed" = rows are produced but nothing in the plugin reads them. Both are actionable findings. "not_applicable" = the signal is gated off for this site profile (e.g. an order metric on a content-only site) or needs an integration this site lacks (ERP, physical stores) — NOT a defect, and never report it as one.', ), 'grain' => array( 'type' => 'string', 'description' => 'Filter by grain bucket, e.g. product, session, order, customer, content, marketing initiative. Substring match.', ), 'search' => array( 'type' => 'string', 'description' => 'Free-text match over id, label, what it measures, table, producer and consumers. Use this to check whether a metric already exists before building it.', ), 'id' => array( 'type' => 'string', 'description' => 'Return one signal by its registry id (e.g. seo_opportunities, product_session_metrics).', ), 'verbose' => array( 'type' => 'boolean', 'default' => false, 'description' => 'Include the full measures/notes text and per-table detail. Default false returns a compact row.', ), ), ); } public static function execute( $input ) { if ( ! class_exists( 'AIEO_Signal_Registry' ) && defined( 'AIEO_DIR' ) ) { $f = AIEO_DIR . 'includes/class-aieo-signal-registry.php'; if ( is_readable( $f ) ) { require_once $f; } } if ( ! class_exists( 'AIEO_Signal_Registry' ) ) { return array( 'available' => false, 'note' => __( 'AIEO_Signal_Registry is not present in this build.', 'ai-eshop-optimizer' ), ); } $input = is_array( $input ) ? $input : array(); $state = isset( $input['state'] ) ? (string) $input['state'] : 'any'; $grain = isset( $input['grain'] ) ? mb_strtolower( trim( (string) $input['grain'] ) ) : ''; $search = isset( $input['search'] ) ? mb_strtolower( trim( (string) $input['search'] ) ) : ''; $only_id = isset( $input['id'] ) ? trim( (string) $input['id'] ) : ''; $verbose = ! empty( $input['verbose'] ) || '' !== $only_id; $status = \AIEO_Signal_Registry::status(); $signals = isset( $status['signals'] ) ? $status['signals'] : array(); $rows = array(); foreach ( $signals as $s ) { if ( '' !== $only_id && $s['id'] !== $only_id ) { continue; } if ( 'any' !== $state && $s['state'] !== $state ) { continue; } if ( '' !== $grain ) { $bucket = mb_strtolower( \AIEO_Signal_Registry::grain_bucket( $s['grain'] ) ); if ( false === mb_strpos( $bucket, $grain ) && false === mb_strpos( mb_strtolower( $s['grain'] ), $grain ) ) { continue; } } if ( '' !== $search && ! self::matches( $s, $search ) ) { continue; } $rows[] = self::shape( $s, $verbose ); if ( count( $rows ) >= self::MAX_ROWS ) { break; } } return array( 'available' => true, 'total' => count( $signals ), 'returned' => count( $rows ), 'state_counts' => isset( $status['counts'] ) ? $status['counts'] : array(), 'measured_at' => gmdate( 'Y-m-d H:i:s', (int) $status['generated'] ) . ' UTC', 'signals' => $rows, 'guidance' => __( 'Before proposing a new metric, scorer or rollup, check this list for an existing one — AIEO_SEO_Opportunity_Scorer (id seo_opportunities) already does traffic x conversion quadrants with hidden-winner detection, tunable thresholds and shop/catalog/content profiles. A "dormant" state means the capability exists and simply is not scheduled; the fix is scheduling it, never rebuilding it. An "unconsumed" state means the site pays to compute something nightly that nothing reads — either wire a reader or ask the operator whether to retire it. A "partial" block on a row means the headline hides a dead component: `rows` is the SUM over the signal\'s tables and `cron_scheduled` is ANY-of its hooks, so treat the named tables/hooks as unproven. Finally: this catalogue is hand-maintained and does NOT cover every table the plugin owns, so never answer "we do not have that" from its silence alone.', 'ai-eshop-optimizer' ), ); } private static function matches( array $s, $needle ) { $hay = mb_strtolower( implode( ' ', array( $s['id'], $s['label'], $s['measures'], $s['grain'], $s['producer'], $s['consumers'], $s['notes'], implode( ' ', $s['tables'] ), implode( ' ', $s['cron_hooks'] ), ) ) ); return false !== mb_strpos( $hay, $needle ); } private static function shape( array $s, $verbose ) { $h = $s['health']; $row = array( 'id' => $s['id'], 'label' => $s['label'], 'grain' => $s['grain'], 'grain_bucket' => \AIEO_Signal_Registry::grain_bucket( $s['grain'] ), 'state' => $s['state'], 'state_reason' => $s['state_reason'], 'tables' => $s['tables'], 'rows' => $h['rows'], 'cron_hooks' => $s['cron_hooks'], 'cron_scheduled' => (bool) $h['scheduled'], 'cron_missing' => (bool) $h['cron_missing'], 'unconfigured' => ! empty( $h['unconfigured'] ), 'partial' => empty( $h['partial'] ) ? null : array_filter( array( 'empty_tables' => isset( $h['empty_tables'] ) ? $h['empty_tables'] : array(), 'missing_tables' => isset( $h['missing_tables'] ) ? $h['missing_tables'] : array(), 'crons_unscheduled' => isset( $h['crons_unscheduled'] ) ? $h['crons_unscheduled'] : array(), ) ), 'site_profiles' => $s['site_profiles'], 'producer' => $s['producer'], 'consumers' => '' === trim( (string) $s['consumers'] ) ? null : $s['consumers'], ); if ( ! $verbose ) { $row['measures'] = self::clip( $s['measures'], 150 ); $row['producer'] = self::clip( $s['producer'], 120 ); $row['consumers'] = ( null === $row['consumers'] ) ? null : self::clip( $s['consumers'], 160 ); return $row; } $row['measures'] = $s['measures']; $row['notes'] = $s['notes']; $row['tables_detail'] = $h['tables']; $row['cron_detail'] = $h['crons']; $row['last_run'] = $h['last_run'] ? gmdate( 'Y-m-d H:i:s', (int) $h['last_run'] ) . ' UTC' : null; $row['next_run'] = $h['next_run'] ? gmdate( 'Y-m-d H:i:s', (int) $h['next_run'] ) . ' UTC' : null; return $row; } private static function clip( $s, $max ) { $s = trim( (string) $s ); return ( mb_strlen( $s ) > $max ) ? mb_substr( $s, 0, $max - 1 ) . '…' : $s; } }