feat(personalization): wire Intuit pzn + ixp onto aem-experimentation BYO hooks (frozen-API content model)

[ramboz]

What

Wires Intuit's personalization + experimentation onto the vendored aem-experimentation plugin's bring-your-own decision-engine hooks, in the frozen-API content model — Intuit's APIs return content (pznblock / IXP variation), so the hooks apply the engine's content rather than mapping a cell/arm to authored content.

It also folds two generic additions into the plugin itself (opt-in, no-op by default — these go upstream to adobe/aem-experimentation#73):

• resolveDecisions hook + serveDecisions lane — consumes the contract's already-defined decisions facet ("engine returns content per slot"), which nothing in the plugin used before.
• QA overrides invoke the BYO hooks — ?audience=/?experiment= now still call resolveAudiences/getAssignment for their resolution side-effect (the override still wins the plugin's own selection).

How it works

• PZN — the decisions-manifest lane (plugin serveDecisions). A sheet declares { selector, placement }. The plugin reads it and calls resolveDecisions(entries, context) once; byo.js's hook batches a single POST /api/pzn (with the marketing-profile / ZoomInfo enrichment) and returns { selector → { url: pznblock } }. The plugin applies each via renderDecision (→ applyFragment). No cache/indirection — the engine's fragment is returned directly.
• IXP — getAssignment (frozen). Native Experiment/Experiment Variants authoring gates the experiment (the variant href is a placeholder). getAssignment calls GET /api/ixp, reports the arm, and stashes the engine's variation (assetLocation); renderDecision applies the stash. The QA override now invokes getAssignment too, so content resolves under a forced arm (no lazy workaround needed).
• Hook bodies reuse the project's own decision.js/attributes.js/pzn-response.js/ixp-response.js + pzn.js's getMarketingProfile, unchanged. scripts/pzn.js/exp.js are untouched (for the perf A/B).

Contents

• Plugin (plugins/experimentation/, → media-text cards: migration-path cards drift from original in color, type scale, and spacing #73 upstream): resolveDecisions / serveDecisions / watchMutationsAndApplyDecisions + decisions-manifest metadata (additive, no-op by default); getResolvedAudiences / getExperimentConfig invoke the configured BYO hook under a QA override; getManifestEntriesForCurrentPage gains { requireUrl } (default preserves existing behavior); byo doc + README updated.
• Project: scripts/personalization/byo.js — the hooks (PZN collapsed onto resolveDecisions, net −62 lines); scripts/experiment-loader.js (spreads the hooks; isExperimentationEnabled recognizes decisions-manifest); blocks/pzn-hero/pzn-offer; aem-martech transport-only (personalization: false); demos + pzn-manifest.json (now { selector, placement }).

Test it (local)

npx @adobe/aem-cli up --no-open --html-folder drafts

• PZN: /drafts/pzn-cell-demo → hero + offer render the engine's pznblock (sticky per placement via pzn-mock-* cookies).
• IXP: /drafts/ixp-demo?experiment=ixp-hero-test/challenger-1 → the engine's variation; /control → control; no param → sticky mock.

Demos are local-only (drafts aren't served by the .aem.page preview; a shareable demo needs DA authoring).

Measure perf

PZN = one batched /api/pzn (via resolveDecisions) + renderDecision swaps; IXP = one /api/ixp + a variant swap. Drop the pzn-mock/ixp-mock metas to hit the real engine (the hooks call /api/pzn,/api/ixp via the existing Akamai transport) on the same content as scripts/pzn.js/exp.js for the head-to-head.

Verification

• npm run lint clean; project npm test 15 failed / 450 passed = main baseline (pre-existing testimonial-video*/lead-form-config).
• Plugin's own Playwright suite 141/141.
• Browser (both lanes): PZN renders the engine's pznblock via the new serveDecisions lane; IXP challenger/control render (challenger under the override confirms getAssignment runs); no console errors beyond the Intuit martech CORS baseline.

Caveats / follow-ups

• Draft — vendors #73 pre-merge. The plugin changes here also need pushing up to media-text cards: migration-path cards drift from original in color, type scale, and spacing #73 (git subtree push, or a direct commit to the media-text cards: migration-path cards drift from original in color, type scale, and spacing #73 branch) so the subtree stays in sync when media-text cards: migration-path cards drift from original in color, type scale, and spacing #73 merges. Everything added to the plugin is generic + no-op by default.
• Preview — the sim panel previews authored candidates; engine-returned content has none → needs a preview-mode engine call or listAudiences enumeration.
• Deletable after the perf A/B — collectSlots/runExperienceLayer/runExperiment in scripts/pzn.js/exp.js; the plugin owns that orchestration now. That's the real code reduction.

🤖 Generated with Claude Code

[aem-code-sync]

Hello, I'm the AEM Code Sync Bot and I will run some actions to deploy your branch and validate page speed.
In case there are problems, just click a checkbox below to rerun the respective action.

• Re-run all PSI checks
• Re-run failed PSI checks
• Re-sync branch

Commits

• f5fdbf9 ✅ (latest)
• 8a39b97 ✅
• 652c7b6 ✅
• 55e95c7 ✅
• 57841d8 ✅
• 21e60fa ✅
• 2b7839f ✅
• 7eec364 ✅
• 5879c9b ✅
• c8e943c ✅
• f135b79 ✅
• ea444fa ✅
• 85f8eeb ✅
• 5fb98e9 ✅
• 811383b ✅
• 2afdd9c ✅
• 93d82e8 ✅

[amol-anand]

@ramboz question about this ->

A sheet declares { selector, placement }

currently, the way we will know whether something needs to be replaced is based on page metadata or section metadata (or additional prop in section meta about block selector). Not from a sheet. So would want to make sure we can support this approach while rolling the changes into the OOTB plugin.

[amol-anand]

Also, there's not worker doing anything right now. calls are made to /api/zoominfo, /api/ixp or /api/pzn (and in the future it will be consolidated into one) and wired via Akamai instead of the edge worker.

[ramboz]

@amol-anand The plugin supports 3 layers of pzn/xp: page, section and "block" (but essentially any CSS selector).
The sheet is just used for the latter case so we can add all the metadata we need for a given "selector".

The worker you see if just cleanup I still need to do in the plugin itself. I had a dummy proxy worker as documentation to show how to route to an internal service, but it would not be used here.

Also since you have already a working version, I'd probably park the cleanup and changes to the experimentation pluging as post go-live.