Search relevance: learned ranking for Lunar search (spec 0084)

[glennjacobs]

Summary

Implements spec 0084 (specs/0084-search-relevance.md): a learned, engine-agnostic ranking layer for Lunar search, in two parts.

lunarphp/search hooks (Part 1)

• lunar.search.pipelines.request / .results, run by every built-in engine through Illuminate\Pipeline\Pipeline with Lunar\Search\Pipelines\SearchRequest / SearchResponse passables.
• AbstractEngine::page(), getPage(), getPerPage(), withParams() (merged into the engine request last; null removes a key), pipeRequest(), pipeResults().
• SearchHit::$meta and SearchResults::$meta (defaults, non-breaking). Typesense fills meta['score'] from text_match, Meilisearch from _rankingScore (now requested).
• Retrieval baseline fixes from the prototype: Typesense distance_threshold on the hybrid vector query (lunar.search.typesense.vector_distance_threshold, default 0.6), Meilisearch hybrid config (embedder, semantic_ratio, ranking_score_threshold), skus_normalised on the product index, ScoutIndexer::getExactMatchFields() and lunar:meilisearch:setup disabling typo tolerance on those fields.

lunarphp/search-relevance (Part 2, new package)

• Logs every search (search_queries) and shopper events (search_events), scores them nightly into search_query_scores, and reranks results within buckets from the learned scores.
• Pipeline stages PartNumberRetrieval, WidenRequest, RankResults; contracts QueryNormaliser, Signal, Ranker, ScoreAggregator bound from config so hosts can swap any of them.
• Storefront tracking: a new npm package @lunarphp/search-relevance (framework-agnostic client plus a Vue useSearchTracking composable and v-lunar-search-hit directive) for the Inertia/Vue storefront starter kit; the Blade component <x-lunar-search-relevance::tracking /> inlines the same client's IIFE build, with lunar_search_attrs() for markup. POST /lunar/search/events for anything else. SearchHit/SearchResults meta are typed for the generated Lunar.Search types. Basket and purchase attribution through cart line meta.
• Commands lunar:search-relevance:score (scheduled daily), :replay (proves uplift before switching on), :prune (weekly).
• Modes off / shadow (default) / on, set in config or LUNAR_SEARCH_RELEVANCE_MODE like every other store setting. The panel settings page is read-only.
• Abuse guards: event window and one-event-per-type dedupe (unique index on search_events), per-session dedupe and trusted-sessions-only in scoring, crawler user agents skipped, purchases forgotten on cancel/refund, and staff overrides (exclude a product from learning, reset a query) with panel controls. The bucketed ranker already caps the blast radius: nothing can enter the first bucket unless the engine put it there.
• Panel add-on: Search relevance section (KPIs, uplift, top / zero-result / no-click queries, per-query explainability with exclude and reset overrides), read-only settings screen, dashboard widget, product edit slot, global search source. Compiled bundle committed under packages/search-relevance/build.

Docs PR: lunarphp/docs#52

Test plan

• vendor/bin/pest --testsuite search --parallel
• vendor/bin/pest --testsuite search-relevance --parallel
• vendor/bin/pest --testsuite core --parallel
• vendor/bin/pest --testsuite panel --parallel
• vendor/bin/pest --group=cross-db on mysql / pgsql (CI)
• vendor/bin/phpstan analyse
• npm run build --workspace @lunarphp/search-relevance-addon
• npm test && npm run type-check && npm run build --workspace @lunarphp/search-relevance

🤖 Generated with Claude Code