@delmaredigital/payload-experiments 0.3.0-rc.1 → 0.4.0-rc.1

package/dist/transitions/checkStart.d.ts

@@ -1,13 +1,15 @@
+import { type GoalContent } from '../goals/fairness.js';
 import type { Arm, DocId, ExperimentKind, ExposurePolicy, FlagPoint, MetricSource, ResolvedOptions, Status, TargetingRule, UnitType } from '../types/contracts.js';
 import type { ArmIssueCode, PreflightResult } from '../types/endpoints.js';
 import type { BlockPlacement, FlagPlacement } from './placements.js';
-export type ReadinessCode = ArmIssueCode | 'invalid-status' | 'no-planned-duration' | 'no-primary-metric' | 'no-reach-per-day' | 'page-no-targets' | 'page-target-unpublished' | 'page-targets-unchecked' | 'version-page-unavailable' | 'version-page-unchecked' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'no-placements' | 'empty-slot' | 'make-content-unsupported' | 'layer-unit-mismatch' | 'layer-full' | 'unknown-metric-source' | 'unit-source-mismatch' | 'block-path-rule' | 'undeclared-targeting-key' | 'invalid-targeting-rule';
+export type ReadinessCode = ArmIssueCode | 'goal-in-some-versions' | 'placement-unchecked' | 'invalid-status' | 'no-planned-duration' | 'no-primary-metric' | 'no-reach-per-day' | 'placement-unpublished' | 'duplicate-version-row' | 'interacting-tests' | 'version-identical' | 'version-same-address' | 'unknown-collection' | 'page-no-targets' | 'page-in-use' | 'page-target-unpublished' | 'page-targets-unchecked' | 'version-page-unavailable' | 'version-page-unchecked' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'no-placements' | 'empty-slot' | 'make-content-unsupported' | 'layer-unit-mismatch' | 'layer-full' | 'unknown-metric-source' | 'unit-source-mismatch' | 'block-path-rule' | 'undeclared-targeting-key' | 'invalid-targeting-rule';
 export interface StartExperiment {
     id: DocId;
     slug: string;
     status: Status;
     kind: ExperimentKind;
     unitType: UnitType;
+    pageCollection?: string | null;
     arms: Arm[];
     allocation: number;
     exposurePolicy: ExposurePolicy;
@@ -37,6 +39,7 @@ export interface StartExperiment {
 export interface StartMetric {
     id: DocId;
     source: string;
+    name?: string;
 }
 export type PlacementFailure = 'placements-failed' | 'forbidden' | 'not-found';
 export interface CheckStartInput {
@@ -49,8 +52,18 @@ export interface CheckStartInput {
     placementError?: PlacementFailure;
     flagPlacementError?: PlacementFailure;
     flagPointBusy?: boolean;
+    goalContent?: GoalContent;
+    interactions?: import('./placementInteractions.js').InteractionDetail[];
+    unknownPageCollection?: boolean;
+    identicalVersions?: Array<{
+        arm: string;
+        path: string;
+        collection: string;
+        id: DocId;
+    }>;
     unpublishedPageTargets?: string[];
     pageTargetsUnchecked?: boolean;
+    pageTestsInUse?: Pick<StartExperiment, 'id' | 'arms'>[];
     layer?: {
         unitType: UnitType;
         usedSlices: number[];
@@ -61,5 +74,8 @@ export declare const ARM_CHECK_ORDER: readonly ArmIssueCode[];
 export declare const relationshipId: (value: DocId | {
     id: DocId;
 } | null | undefined) => DocId | undefined;
+/** Every path the runtime would match for these arms (pageRewrite, experimentMetadata): any string
+ * pageTarget, holdout included, normalised the same way ('' is '/'). Occupancy and lock keys use this. */
+export declare const pageTargetPaths: (arms: readonly Arm[]) => string[];
 /** Pure Review/Start predicates in refusal order. Inapplicable checks pass. */
 export declare function checkStart(input: CheckStartInput): PreflightResult['checks'];

package/dist/transitions/checkStart.js

@@ -1,4 +1,6 @@
+import { asymmetricGoal } from '../goals/fairness.js';
 import { checkArms } from '../collections/experiments/armInvariants.js';
+import { normalisePath } from '../runtime/normalisePath.js';
 import { isOpValid } from '../targeting/ops.js';
 export const ARM_CHECK_ORDER = [
     'weights-total',
@@ -13,6 +15,15 @@ export const ARM_CHECK_ORDER = [
     'duplicate-slot'
 ];
 export const relationshipId = (value)=>value == null ? undefined : typeof value === 'object' ? value.id : value;
+/** Every path the runtime would match for these arms (pageRewrite, experimentMetadata): any string
+ * pageTarget, holdout included, normalised the same way ('' is '/'). Occupancy and lock keys use this. */ export const pageTargetPaths = (arms)=>[
+        ...new Set(arms.filter((arm)=>typeof arm.pageTarget === 'string').map((arm)=>normalisePath(arm.pageTarget)))
+    ].sort();
+const placementDetail = ({ collection, id, title })=>({
+        collection,
+        id,
+        title
+    });
 const positive = (value)=>typeof value === 'number' && Number.isFinite(value) && value > 0;
 function invalidParams(arms, point) {
     return arms.flatMap((arm)=>{
@@ -56,6 +67,33 @@ function invalidParams(arms, point) {
         'viewport'
     ].includes(e.exposurePolicy) || positive(e.analysis?.reachPerDay));
     add('page-no-targets', e.kind !== 'page' || e.arms.filter((arm)=>arm.kind !== 'holdout').every((arm)=>typeof arm.pageTarget === 'string' && arm.pageTarget.trim().length > 0));
+    add('interacting-tests', !input.interactions?.length, input.interactions);
+    add('unknown-collection', !input.unknownPageCollection);
+    const addressed = new Map();
+    const duplicate = e.kind === 'page' ? e.arms.filter((arm)=>arm.kind !== 'holdout' && arm.pageTarget).flatMap((arm)=>{
+        const path = normalisePath(arm.pageTarget);
+        const otherArm = addressed.get(path);
+        addressed.set(path, arm.key);
+        return otherArm ? [
+            {
+                arm: arm.key,
+                otherArm,
+                path
+            }
+        ] : [];
+    }) : [];
+    add('version-same-address', duplicate.length === 0, duplicate[0]);
+    for (const detail of input.identicalVersions ?? [])checks.push({
+        code: 'version-identical',
+        ok: true,
+        warning: true,
+        detail
+    });
+    const occupiedPaths = new Set((input.pageTestsInUse ?? []).filter((other)=>String(other.id) !== String(e.id)).flatMap((other)=>pageTargetPaths(other.arms)));
+    const sharedPaths = e.kind === 'page' ? pageTargetPaths(e.arms).filter((path)=>occupiedPaths.has(path)) : [];
+    add('page-in-use', sharedPaths.length === 0, {
+        paths: sharedPaths
+    });
     add('page-target-unpublished', !input.unpublishedPageTargets?.length, input.unpublishedPageTargets?.[0]);
     add('page-targets-unchecked', true);
     if (input.pageTargetsUnchecked) checks[checks.length - 1].warning = true;
@@ -69,12 +107,36 @@ function invalidParams(arms, point) {
     const failed = input.flagPlacements?.filter((placement)=>!placement.ok) ?? [];
     add('flag-placement-missing', e.kind !== 'flag' || !input.flagPlacementError && missing.length === 0 && failed.length === 0, input.flagPlacementError ?? {
         missing: missing.map((arm)=>arm.key),
-        placements: failed
+        placements: failed.map(({ arm, ok, detail })=>({
+                arm,
+                ok,
+                detail
+            }))
     });
     const placements = input.placements ?? [];
     add('no-placements', e.kind !== 'block' || !input.placementError && placements.length > 0, input.placementError);
-    const empty = placements.filter((placement)=>e.arms.some((arm)=>arm.kind !== 'holdout' && (!arm.slot || !(placement.slots[arm.slot] > 0))));
-    add('empty-slot', e.kind !== 'block' || empty.length === 0, empty);
+    const unpublished = placements.filter((p)=>!p.published && !placements.some((other)=>other.published && other.collection === p.collection && String(other.id) === String(p.id)));
+    add('placement-unpublished', unpublished.length === 0, unpublished.map(placementDetail));
+    const duplicates = placements.filter((p)=>p.published && p.duplicateRows);
+    add('duplicate-version-row', duplicates.length === 0, duplicates.map(placementDetail));
+    for (const p of placements.filter((p)=>p.published))for (const slot of p.identicalSlots ?? []){
+        if (e.arms.some((a)=>a.slot === slot && a.kind !== 'holdout')) checks.push({
+            code: 'version-identical',
+            ok: true,
+            warning: true,
+            detail: {
+                arm: slot,
+                collection: p.collection,
+                id: p.id,
+                title: p.title
+            }
+        });
+    }
+    const empty = placements.filter((placement)=>placement.published && e.arms.some((arm)=>arm.kind !== 'holdout' && (!arm.slot || !(placement.slots[arm.slot] > 0))));
+    add('empty-slot', e.kind !== 'block' || empty.length === 0, empty.map((placement)=>({
+            ...placementDetail(placement),
+            slots: placement.slots
+        })));
     add('make-content-unsupported', true);
     const localized = placements.find((placement)=>placement.localized);
     if (localized) Object.assign(checks[checks.length - 1], {
@@ -87,10 +149,40 @@ function invalidParams(arms, point) {
         available: free,
         requested: e.allocation
     });
-    const unknown = input.metrics.filter((metric)=>!metric.source.startsWith('events:') && !input.metricSources?.some((source)=>source.id === metric.source));
-    add('unknown-metric-source', unknown.length === 0, unknown);
-    const mismatches = input.metrics.filter((metric)=>!metric.source.startsWith('events:') && e.unitType === 'user' && input.metricSources?.some((source)=>source.id === metric.source && source.keyedBy === 'visitor'));
-    add('unit-source-mismatch', mismatches.length === 0, mismatches);
+    for (const detail of input.goalContent?.unchecked ?? [])checks.push({
+        code: 'placement-unchecked',
+        ok: true,
+        warning: true,
+        detail
+    });
+    const protectedGoals = [
+        relationshipId(e.metrics?.primary),
+        ...e.metrics?.guardrails?.map(relationshipId) ?? []
+    ].map(String);
+    const asymmetric = input.metrics.filter((metric)=>metric.source.startsWith('click:') && input.goalContent && asymmetricGoal(input.goalContent, metric.source, e.arms));
+    add('goal-in-some-versions', !asymmetric.some((metric)=>protectedGoals.includes(String(metric.id))), asymmetric.filter((metric)=>protectedGoals.includes(String(metric.id))).map((metric)=>({
+            metricId: metric.id,
+            name: metric.name
+        })));
+    for (const metric of asymmetric.filter((metric)=>!protectedGoals.includes(String(metric.id))))checks.push({
+        code: 'goal-in-some-versions',
+        ok: true,
+        warning: true,
+        detail: {
+            metricId: metric.id,
+            name: metric.name
+        }
+    });
+    const unknown = input.metrics.filter((metric)=>!metric.source.startsWith('events:') && !metric.source.startsWith('click:') && !input.metricSources?.some((source)=>source.id === metric.source));
+    add('unknown-metric-source', unknown.length === 0, unknown.map(({ id, source })=>({
+            id,
+            source
+        })));
+    const mismatches = input.metrics.filter((metric)=>!metric.source.startsWith('events:') && !metric.source.startsWith('click:') && e.unitType === 'user' && input.metricSources?.some((source)=>source.id === metric.source && source.keyedBy === 'visitor'));
+    add('unit-source-mismatch', mismatches.length === 0, mismatches.map(({ id, source })=>({
+            id,
+            source
+        })));
     const pathRules = (e.targeting ?? []).flatMap((rule, index)=>rule.attribute === 'path' ? [
             index
         ] : []);

package/dist/transitions/decide.js

@@ -1,13 +1,20 @@
+import { detached, scanPlacements, lockAndRescanPlacements, placementInteractions } from './placementInteractions.js';
 import { DEFAULT_SEQUENTIAL_TUNING_PARAMETER } from '../constants.js';
+import { refreshPlacementDocs } from '../db/placements.js';
+import { unpublishedPageTargets } from './preflightData.js';
 import { reclaimSlices } from '../db/slices.js';
 import { decideGuard } from '../results/decideGuard.js';
-import { relationshipId } from './checkStart.js';
+import { lockPagePaths } from '../db/locks.js';
+import { routedPageTests } from '../db/pageOccupancy.js';
+import { pageTargetPaths, relationshipId } from './checkStart.js';
 import { expectedConfirm, matchesConfirm, storedWinnerLabel } from './confirmPhrases.js';
 import { withTransition } from './kernel.js';
 import { readPhaseRecord, setPhaseEndedAt, writePhaseRecord } from './phaseRecord.js';
 import { readExperiment, refuse, updateExperiment } from './start.js';
 export async function decide(req, { experimentId, winnerArm, note, confirmation }) {
     const before = await readExperiment(req, experimentId);
+    const options = req.payload.config.custom?.xp;
+    const placements = before.status === 'stopped' && before.kind === 'block' ? await detached(req, ()=>scanPlacements(req, options, before.slug)) : [];
     const { result: doc, revision } = await withTransition(req, {
         experimentId,
         layerId: relationshipId(before.layer),
@@ -45,6 +52,38 @@ export async function decide(req, { experimentId, winnerArm, note, confirmation
         }
         const test = await readPhaseRecord(req, experimentId, current.phase);
         if (test.phaseKind !== 'test') refuse('invalid-status');
+        if (current.kind === 'block' && current.status === 'stopped') {
+            const rescan = await lockAndRescanPlacements(req, exec, options, {
+                ...current,
+                arms: test.arms
+            }, placements);
+            await refreshPlacementDocs(exec, experimentId, test.phase, rescan.docs);
+        }
+        if (current.kind === 'page' && current.status === 'stopped') {
+            // Deciding a stopped page test restores its routing: recheck page occupancy under the
+            // sorted path locks Start takes, so another test that started on these pages meanwhile wins.
+            // The frozen test-round arms are what decide restores; the stopped document's arms may have been edited.
+            const mine = pageTargetPaths(test.arms);
+            await lockPagePaths(exec, mine);
+            // Other tests' routed (frozen-round) arms, as the runtime matches them.
+            const occupied = new Set((await routedPageTests(exec)).filter((other)=>String(other.id) !== String(experimentId)).flatMap((other)=>pageTargetPaths(other.arms)));
+            const shared = mine.filter((path)=>occupied.has(path));
+            if (shared.length) refuse('page-in-use', {
+                paths: shared
+            });
+            const conflicts = await placementInteractions(req, exec, options, {
+                ...current,
+                arms: test.arms
+            }, mine);
+            if (conflicts.length) refuse('interacting-tests', conflicts);
+            if (options?.pages) {
+                const unpublished = await detached(req, ()=>unpublishedPageTargets(req, options, {
+                        ...current,
+                        arms: test.arms.filter((arm)=>arm.kind === 'control' || arm.key === winnerArm)
+                    }, true));
+                if (unpublished.length) refuse('page-target-unpublished', unpublished[0]);
+            }
+        }
         const winner = test.arms.find((arm)=>arm.key === winnerArm && arm.kind !== 'holdout');
         if (!winner) refuse('invalid-winner');
         // §7.8: decision snapshot lookup serves the authorised transition.

package/dist/transitions/deleteExperiment.d.ts

@@ -1,5 +1,7 @@
-import type { PayloadRequest } from 'payload';
+import type { PayloadRequest, Where } from 'payload';
 import type { DocId } from '../types/contracts.js';
+/** Lock the entire bulk scope before any per-document hook can take state. */
+export declare function prepareBulkDelete(req: PayloadRequest, where: Where): Promise<void>;
 /** Payload deleteByID owns the request transaction; never commit inside hooks. */
 export declare function deleteExperiment(req: PayloadRequest, experimentId: DocId): Promise<void>;
 export declare function deleteExperimentAfter(req: PayloadRequest, experimentId: DocId): Promise<void>;

package/dist/transitions/deleteExperiment.js

@@ -1,10 +1,33 @@
 import { safeError } from '../log.js';
+import { retireSlug } from '../db/slugs.js';
 import { txExecutor } from '../db/executor.js';
 import { deleteExperimentSnapshots, serializeDelete } from '../db/delete.js';
 import { deleteExperimentEvents } from '../db/events.js';
-import { lockTransitionScope } from '../db/locks.js';
+import { lockTransitionScope, sortLockKeys } from '../db/locks.js';
 import { buildAndStoreManifest } from '../manifest/compile.js';
 import { readExperiment, refuse } from './start.js';
+/** Lock the entire bulk scope before any per-document hook can take state. */ export async function prepareBulkDelete(req, where) {
+    await serializeDelete(req, async ()=>{
+        // §7.8 transition exception: hook read only discovers the lock set; delete still checks access.
+        const { docs } = await req.payload.find({
+            collection: 'xp-experiments',
+            req,
+            overrideAccess: true,
+            depth: 0,
+            limit: 0,
+            pagination: false,
+            select: {
+                id: true
+            },
+            where
+        });
+        for (const experimentId of sortLockKeys(docs.map((doc)=>String(doc.id)))){
+            await lockTransitionScope(txExecutor(req), {
+                experimentId
+            });
+        }
+    });
+}
 /** Payload deleteByID owns the request transaction; never commit inside hooks. */ export async function deleteExperiment(req, experimentId) {
     await serializeDelete(req, async (state)=>{
         const exec = txExecutor(req);
@@ -40,6 +63,7 @@ import { readExperiment, refuse } from './start.js';
             }
             await deleteExperimentSnapshots(exec, experimentId);
             await deleteExperimentEvents(exec, experimentId);
+            state.retiredSlugs.add(current.slug);
             state.excludedIds.set(String(experimentId), experimentId);
             const decision = current.decision;
             if (current.status !== 'archived' || decision?.discardedAt) state.pruneFlagDefaultIds.set(String(experimentId), experimentId);
@@ -54,6 +78,8 @@ import { readExperiment, refuse } from './start.js';
 }
 export async function deleteExperimentAfter(req, experimentId) {
     await serializeDelete(req, async (state)=>{
+        for (const slug of state.retiredSlugs)await retireSlug(txExecutor(req), slug);
+        state.retiredSlugs.clear();
         await buildAndStoreManifest(req, {
             excludeIds: [
                 ...state.excludedIds.values(),

package/dist/transitions/kernel.js

@@ -3,6 +3,7 @@ import { pooledExecutor, txExecutor } from '../db/executor.js';
 import { lockTransitionScope } from '../db/locks.js';
 import { currentTxid, txidStatus } from '../db/txid.js';
 import { contentChangeSavepoint } from '../db/appends.js';
+import { isPageBusy } from '../db/pageBusy.js';
 import { XpRefusal } from '../errors.js';
 import { buildAndStoreManifest } from '../manifest/compile.js';
 /** Runs transition writes on the request's transaction under ordered locks.
@@ -61,6 +62,9 @@ import { buildAndStoreManifest } from '../manifest/compile.js';
         };
     } catch (error) {
         if (!borrowedAudit) await killTransaction(req);
+        if (!scope.audit && isPageBusy(error)) throw new XpRefusal('page-busy', "One of this test's pages is being saved right now. Try again in a moment.", undefined, 409, {
+            cause: error
+        });
         throw error;
     } finally{
         if (hadTransition) req.context.xpTransition = previousTransition;

package/dist/transitions/makeContent.d.ts

@@ -10,6 +10,11 @@ type ContentDoc = {
     dismissedAt?: string;
     dismissedBy?: string | null;
 };
+/** Each placement commits independently while the outer transition retains its
+ * experiment locks. Keep the manager's exact req/user, temporarily lending it a
+ * fresh transaction; a denied host write must not kill the outer transaction.
+ */
+export declare function hostTransaction(req: PayloadRequest, experimentId: DocId, fn: () => Promise<void>): Promise<void>;
 export declare function makeContent<TUser extends {
     id: DocId;
 }>(req: PayloadRequest, { experimentId, options }: {

package/dist/transitions/makeContent.js

@@ -1,5 +1,7 @@
 import { Forbidden, NotFound, ValidationError, Locked, commitTransaction, initTransaction, killTransaction } from 'payload';
 import { latestDraftContent, publishedContent as readPublishedContent } from '../db/publishedContent.js';
+import { EXPERIMENT_BLOCK_SLUG, hostBlocks, slotBlocks } from '../blocks/model.js';
+import { findRegisteredBlocksField, freshBlockIds } from '../blocks/formState.js';
 import { contentBlocks, hasLocalizedFields } from './contentFields.js';
 import { safeError } from '../log.js';
 import { XpRefusal } from '../errors.js';
@@ -7,7 +9,7 @@ import { lockContentDefaults } from '../db/appends.js';
 import { pooledExecutor, txExecutor } from '../db/executor.js';
 import { currentTxid, txidStatus } from '../db/txid.js';
 import { buildAndStoreManifest } from '../manifest/compile.js';
-import { puckCollections } from '../options.js';
+import { documentEditor, puckCollections } from '../options.js';
 import { contentDone } from '../contentDone.js';
 import { archive } from './archive.js';
 import { relationshipId } from './checkStart.js';
@@ -162,9 +164,14 @@ async function fieldRefusal(fields, req, doc, operation = 'update', data = doc,
 /** Each placement commits independently while the outer transition retains its
  * experiment locks. Keep the manager's exact req/user, temporarily lending it a
  * fresh transaction; a denied host write must not kill the outer transaction.
- */ async function hostTransaction(req, fn) {
+ */ export async function hostTransaction(req, experimentId, fn) {
     const transactionID = req.transactionID;
     const transition = req.context.xpTransition;
+    const hadHeld = Object.hasOwn(req.context, 'xpHeldExperiments');
+    const held = req.context.xpHeldExperiments;
+    req.context.xpHeldExperiments = [
+        experimentId
+    ];
     delete req.transactionID;
     delete req.context.xpTransition;
     try {
@@ -178,6 +185,8 @@ async function fieldRefusal(fields, req, doc, operation = 'update', data = doc,
         throw error;
     } finally{
         req.transactionID = transactionID;
+        if (hadHeld) req.context.xpHeldExperiments = held;
+        else delete req.context.xpHeldExperiments;
         if (transition === undefined) delete req.context.xpTransition;
         else req.context.xpTransition = transition;
     }
@@ -217,7 +226,7 @@ export async function makeContent(req, { experimentId, options }) {
             if (retainDismissed(collection, id)) return;
             let missing = false;
             try {
-                await hostTransaction(req, async ()=>{
+                await hostTransaction(req, experimentId, async ()=>{
                     try {
                         await fn();
                     } catch (error) {
@@ -264,7 +273,10 @@ export async function makeContent(req, { experimentId, options }) {
         };
         if (current.kind === 'block') {
             if (!winner.slot) refuse('invalid-winner');
-            const registrations = puckCollections(options);
+            const registrations = [
+                ...puckCollections(options),
+                ...options.blocks?.collections ?? []
+            ];
             const scanned = [];
             for (const registration of registrations){
                 const transactionID = req.transactionID;
@@ -272,9 +284,8 @@ export async function makeContent(req, { experimentId, options }) {
                 try {
                     scanned.push(...await scanBlockPlacements(req, {
                         slug: current.slug,
-                        puckCollections: [
-                            registration
-                        ]
+                        puckCollections: puckCollections(options).filter((r)=>r === registration),
+                        blocksCollections: (options.blocks?.collections ?? []).filter((r)=>r === registration)
                     }));
                 } catch (error) {
                     // A collection made unreadable since the last attempt still has
@@ -330,7 +341,7 @@ export async function makeContent(req, { experimentId, options }) {
                     let detail = isNotFound(error) ? 'forbidden' : contentFailureReason(error);
                     if (isNotFound(error)) {
                         try {
-                            await hostTransaction(req, async ()=>{
+                            await hostTransaction(req, experimentId, async ()=>{
                                 missing = !await readPublishedContent(req, collection, id);
                             });
                         } catch (checkError) {
@@ -367,7 +378,7 @@ export async function makeContent(req, { experimentId, options }) {
             for (const [key, { collection, id }] of placements){
                 if (skipped.has(key)) continue;
                 await attempt(collection, id, async ()=>{
-                    const field = registrations.find((entry)=>entry.slug === collection)?.field;
+                    let field = registrations.find((entry)=>entry.slug === collection)?.field;
                     if (!field) throw new Error('This content collection is no longer configured.');
                     const config = req.payload.config.collections.find((config)=>config.slug === collection);
                     if (hasLocalizedFields(config?.fields ?? [], req.payload.config)) throw new LocalizedContent();
@@ -382,10 +393,27 @@ export async function makeContent(req, { experimentId, options }) {
                     const drafts = Boolean(config?.versions && config.versions.drafts);
                     const published = await readPublishedContent(req, collection, id);
                     if (!published) throw new NotFound();
+                    const editor = documentEditor(options, collection, published);
+                    const blockRegistration = options.blocks?.collections.find((r)=>r.slug === collection);
+                    const contentField = editor === 'blocks' ? blockRegistration?.field : field;
+                    if (!contentField) throw new Error('This content field is no longer configured.');
+                    field = contentField;
+                    const transform = (value)=>editor === 'blocks' ? !hostBlocks(value).some((block)=>block.blockType === (blockRegistration?.blockSlug ?? EXPERIMENT_BLOCK_SLUG) && block.experiment === current.slug) ? value : hostBlocks(value).flatMap((block)=>{
+                            if (block.blockType !== (blockRegistration?.blockSlug ?? EXPERIMENT_BLOCK_SLUG) || block.experiment !== current.slug) return [
+                                block
+                            ];
+                            const rows = Array.isArray(block.slots) ? block.slots : [];
+                            if (!rows.some((row)=>row?.slot === winner.slot)) throw new Error('The winning content slot is missing.');
+                            const registered = findRegisteredBlocksField(config?.fields ?? [], field);
+                            if (!registered) throw new Error('This content field is no longer configured.');
+                            return slotBlocks(freshBlockIds([
+                                block
+                            ], registered.field, req.payload.config)[0], winner.slot);
+                        }) : unwrap(value, current.slug, winner.slot);
                     const draft = drafts ? await latestDraftContent(req, collection, id) ?? published : published;
                     const draftValue = draft[field] ?? null;
-                    const draftContent = unwrap(draftValue, current.slug, winner.slot);
-                    const publishedContent = unwrap(published[field], current.slug, winner.slot);
+                    const draftContent = transform(draftValue);
+                    const publishedContent = transform(published[field]);
                     const changedDraft = JSON.stringify(draftContent) !== JSON.stringify(draftValue);
                     const changedPublished = JSON.stringify(publishedContent) !== JSON.stringify(published[field]);
                     if (!changedDraft && !changedPublished) return;

package/dist/transitions/pageCollection.d.ts

@@ -0,0 +1,10 @@
+import type { PayloadRequest } from 'payload';
+import type { ExperimentsPageCollection, ResolvedOptions } from '../types/contracts.js';
+/** A stored collection is authoritative. Legacy tests fall back by the Original's path. */
+export declare function resolvePageCollection(req: PayloadRequest, options: Pick<ResolvedOptions, 'pages'>, experiment: {
+    pageCollection?: string | null;
+    arms: readonly {
+        kind?: string;
+        pageTarget?: string;
+    }[];
+}, propagateErrors?: boolean): Promise<ExperimentsPageCollection | undefined>;

package/dist/transitions/pageCollection.js

@@ -0,0 +1,20 @@
+import { safeError } from '../log.js';
+/** A stored collection is authoritative. Legacy tests fall back by the Original's path. */ export async function resolvePageCollection(req, options, experiment, propagateErrors = false) {
+    const collections = options.pages?.collections ?? [];
+    if (experiment.pageCollection) return collections.find((entry)=>entry.slug === experiment.pageCollection);
+    if (collections.length === 1) return collections[0];
+    const path = experiment.arms.find((arm)=>arm.kind === 'control')?.pageTarget;
+    if (!path) return undefined;
+    for (const entry of collections){
+        try {
+            if (await entry.findByPath(path, req)) return entry;
+        } catch (cause) {
+            if (propagateErrors) throw cause;
+            req.payload.logger.error({
+                err: safeError(cause),
+                collection: entry.slug
+            }, 'Experiment page lookup failed');
+        }
+    }
+    return undefined;
+}

package/dist/transitions/pageVersions.d.ts

@@ -0,0 +1,10 @@
+import type { PayloadRequest } from 'payload';
+import type { Arm, ExperimentsPageCollection } from '../types/contracts.js';
+/** Page copies have fresh nested row ids and editor labels; neither is rendered content. */
+export declare function comparableContent(value: unknown): unknown;
+export declare function identicalPageVersions(req: PayloadRequest, collection: ExperimentsPageCollection | undefined, arms: Arm[]): Promise<{
+    arm: import("../types/contracts.js").ArmKey;
+    path: string;
+    collection: string;
+    id: string | number;
+}[]>;

package/dist/transitions/pageVersions.js

@@ -0,0 +1,44 @@
+import { safeError } from '../log.js';
+import { isDeepStrictEqual } from 'node:util';
+import { pageVersionContent } from '../db/pageContent.js';
+/** Page copies have fresh nested row ids and editor labels; neither is rendered content. */ export function comparableContent(value) {
+    if (Array.isArray(value)) return value.map(comparableContent);
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).filter(([key])=>key !== 'id' && key !== 'blockName').map(([key, nested])=>[
+            key,
+            comparableContent(nested)
+        ]));
+    return value;
+}
+export async function identicalPageVersions(req, collection, arms) {
+    if (!collection?.contentOf) return [];
+    const content = await Promise.all(arms.filter((arm)=>arm.kind !== 'holdout' && arm.pageTarget).map(async (arm)=>{
+        try {
+            const page = await collection.findByPath(arm.pageTarget, req);
+            if (!page?.published) return null;
+            const raw = await pageVersionContent(req, collection.slug, page.id);
+            if (!raw || raw._status === 'draft') return null;
+            return {
+                arm,
+                id: page.id,
+                value: comparableContent(collection.contentOf(raw))
+            };
+        } catch (cause) {
+            req.payload.logger.error({
+                err: safeError(cause),
+                collection: collection.slug,
+                id: arm.pageTarget
+            }, 'Experiment version comparison failed');
+            return null;
+        }
+    }));
+    const control = content.find((row)=>row?.arm.kind === 'control');
+    if (!control) return [];
+    return content.flatMap((row)=>row && row.arm.kind === 'variant' && isDeepStrictEqual(row.value, control.value) ? [
+            {
+                arm: row.arm.key,
+                path: row.arm.pageTarget,
+                collection: collection.slug,
+                id: row.id
+            }
+        ] : []);
+}

package/dist/transitions/phaseRecord.d.ts

@@ -16,6 +16,7 @@ export interface PhaseRecord {
     analysis?: Record<string, unknown> & {
         sequentialTuningParameter?: number | null;
     };
+    placementDocs?: import('../db/placements.js').PlacementDoc[] | null;
     contentChanges?: ContentChange[];
 }
 export declare function readPhaseRecord(req: PayloadRequest, experimentId: DocId, phase: number): Promise<PhaseRecord & {

package/dist/transitions/placementInteractions.d.ts

@@ -0,0 +1,40 @@
+import type { PayloadRequest } from 'payload';
+import type { Arm, DocId, ResolvedOptions } from '../types/contracts.js';
+import type { Executor } from '../db/executor.js';
+import { type PlacementDoc } from '../db/placements.js';
+import { type BlockPlacement } from './placements.js';
+export declare function detached<T>(req: PayloadRequest, fn: () => Promise<T>): Promise<T>;
+export declare function uniquePlacementDocs(placements: readonly Pick<BlockPlacement, 'collection' | 'id'>[]): PlacementDoc[];
+export declare function scanPlacements<TUser extends {
+    id: DocId;
+}>(req: PayloadRequest, options: ResolvedOptions<TUser>, slug: string): Promise<BlockPlacement[]>;
+export declare function placementPaths<TUser extends {
+    id: DocId;
+}>(req: PayloadRequest, options: ResolvedOptions<TUser>, docs: readonly PlacementDoc[]): Promise<string[]>;
+export interface InteractionDetail {
+    experimentId: DocId;
+    slug: string;
+    name: string;
+    status: string;
+    path: string;
+    version: boolean;
+}
+export declare function placementInteractions<TUser extends {
+    id: DocId;
+}>(req: PayloadRequest, exec: Executor, options: ResolvedOptions<TUser>, experiment: {
+    id: DocId;
+    kind: string;
+    arms: Arm[];
+    pageCollection?: string | null;
+}, paths: string[]): Promise<InteractionDetail[]>;
+export declare function lockAndRescanPlacements<TUser extends {
+    id: DocId;
+}>(req: PayloadRequest, exec: Executor, options: ResolvedOptions<TUser>, experiment: {
+    id: DocId;
+    slug: string;
+    kind: string;
+    arms: Arm[];
+}, before: readonly BlockPlacement[]): Promise<{
+    placements: BlockPlacement[];
+    docs: PlacementDoc[];
+}>;