feat(paid-keyword-optimizer): surface pageRecommendation at the opportunity level

[markomako]

Summary

Consumer side of the new ad-intent strategist output. mystique's ad-intent-gap crew now emits a strategist-reconciled, play-aware pageRecommendation block in the guidance SQS body — inferredPlay, playConfidence, a lever-first primary action, rankedActions, and alternatives. This surfaces it at the opportunity level: mapToKeywordOptimizerOpportunity now reads guidanceBody.pageRecommendation and includes it in the ad-intent-mismatch opportunity's data (alongside portfolioMetrics, resolvedPageHeading, pageTopics).

Changes

• src/paid-keyword-optimizer/guidance-opportunity-mapper.js — read pageRecommendation (nullish-coalesced to null) and add it to opportunity.data; JSDoc updated.
• test/audits/paid-keyword-optimizer/opportunity-mapper.test.js — passthrough test (present) + default-to-null test (absent and explicit null).

Backward compatibility

Additive and null-safe: older mystique payloads (no pageRecommendation key) and skipped/failed strategist passes (pageRecommendation: null) both collapse to null via ?? null — no consumer breakage. The opportunity data object is free-form JSON (no per-type schema), so no schema change is needed. guidance-opportunity-mapper.js stays at 100% coverage (191 passing in the paid-keyword-optimizer suite).

Producer side

experience-platform/mystique PR #3111 — feat(ad-intent-gap): brand context + ad-copy/misaligned-spend signals + SEM-strategist page recommendation (https://git.corp.adobe.com/experience-platform/mystique/pull/3111). That PR adds the pageRecommendation field to the emitted guidance body; this PR is what makes it visible on the opportunity. The SQS contract was verified compatible (no schema validation on the consumer path) before this change.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!