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

package/dist/server/recordContentChange.js

@@ -1,8 +1,13 @@
+import { EXPERIMENT_BLOCK_SLUG, hostBlocks } from '../blocks/model.js';
 import { safeError } from '../log.js';
 import { isDeepStrictEqual } from 'node:util';
 import { appendContentChange, contentChangeSavepoint, previousPublishedContent, runningContentExperiment, storedContent } from '../db/appends.js';
 import { txExecutor } from '../db/executor.js';
-import { puckCollections } from '../options.js';
+import { pageContentBindings } from '../db/pageBindings.js';
+import { sortLockKeys } from '../db/locks.js';
+import { normalisePath } from '../runtime/normalisePath.js';
+import { comparableContent } from '../transitions/pageVersions.js';
+import { documentEditor, puckCollections } from '../options.js';
 import { withTransition } from '../transitions/kernel.js';
 import { normaliseContentRelationships } from './normaliseContentRelationships.js';
 const slots = [
@@ -98,8 +103,32 @@ async function auditContentChange({ doc, previousDoc, req, collection }) {
     const options = req.payload.config.custom?.xp;
     const registration = puckCollections(options ?? {}).find((entry)=>entry.slug === collection.slug);
     const changes = (previous, current)=>{
-        const after = bindings(registration && object(current) ? current[registration.field] : current, Boolean(registration));
-        const before = bindings(registration && object(previous) ? previous[registration.field] : previous, Boolean(registration));
+        const after = bindings(registration && object(current) ? current[registration.field] : current, Boolean(registration) && documentEditor(options ?? {}, collection.slug, object(current) ? current : {}) === 'puck');
+        const before = bindings(registration && object(previous) ? previous[registration.field] : previous, Boolean(registration) && documentEditor(options ?? {}, collection.slug, object(previous) ? previous : {}) === 'puck');
+        const blockRegistration = options?.blocks?.collections.find((entry)=>entry.slug === collection.slug);
+        for (const [row, found] of [
+            [
+                previous,
+                before
+            ],
+            [
+                current,
+                after
+            ]
+        ]){
+            if (!blockRegistration || !object(row) || documentEditor(options ?? {}, collection.slug, row) !== 'blocks') continue;
+            for (const block of hostBlocks(row[blockRegistration.field])){
+                if (block.blockType !== (blockRegistration.blockSlug ?? EXPERIMENT_BLOCK_SLUG) || typeof block.experiment !== 'string') continue;
+                const key = 'slug:' + block.experiment;
+                const binding = found.get(key) ?? {
+                    field: 'slug',
+                    value: block.experiment,
+                    contents: []
+                };
+                binding.contents.push(block.slots);
+                found.set(key, binding);
+            }
+        }
         return [
             ...new Set([
                 ...before.keys(),
@@ -117,20 +146,41 @@ async function auditContentChange({ doc, previousDoc, req, collection }) {
         const locales = req.payload.config.localization ? req.payload.config.localization.localeCodes : [];
         const normalise = (value)=>normaliseContentRelationships(value, collection.fields, req.payload.config.blocks, locales);
         let changed;
+        let beforeRow, afterRow;
         if (baseline) {
             const current = await storedContent(req, collection.slug, doc.id);
             if (!current) throw new Error('The saved content row was not found.');
-            changed = changes(baseline.doc, current);
-        } else changed = changes(normalise(previousDoc), normalise(doc));
+            beforeRow = baseline.doc;
+            afterRow = current;
+            changed = changes(beforeRow, afterRow);
+        } else {
+            beforeRow = normalise(previousDoc);
+            afterRow = normalise(doc);
+            changed = changes(beforeRow, afterRow);
+        }
         const experiments = new Map();
         for (const binding of changed){
             const experiment = await runningContentExperiment(executor, binding);
             if (experiment) experiments.set(String(experiment.id), experiment.id);
         }
+        const page = options?.pages?.collections.find((entry)=>entry.slug === collection.slug);
+        if (page?.contentOf && !isDeepStrictEqual(comparableContent(object(beforeRow) ? page.contentOf(beforeRow) : undefined), comparableContent(object(afterRow) ? page.contentOf(afterRow) : undefined))) {
+            const paths = [
+                beforeRow,
+                afterRow
+            ].flatMap((row)=>{
+                const path = object(row) ? page.pathOf(row) : null;
+                return path === null ? [] : [
+                    normalisePath(path)
+                ];
+            });
+            for (const id of (await pageContentBindings(executor, collection.slug, paths)))experiments.set(String(id), id);
+        }
         // Successful audit locks persist until commit; acquire multiple E locks in order.
-        for (const [, experimentId] of [
-            ...experiments
-        ].sort(([a], [b])=>a.localeCompare(b))){
+        for (const key of sortLockKeys([
+            ...experiments.keys()
+        ])){
+            const experimentId = experiments.get(key);
             await withTransition(req, {
                 experimentId,
                 bump: false,

package/dist/server/resolveExperimentBlocks.d.ts

@@ -0,0 +1,5 @@
+import type { Assignments } from '../types/assignments.js';
+import { type ResolvedExperimentBlocks } from '../blocks/model.js';
+export declare function resolveExperimentBlocks(blocks: unknown, assignments: Assignments, { blockSlug }?: {
+    blockSlug?: string;
+}): ResolvedExperimentBlocks;

package/dist/server/resolveExperimentBlocks.js

@@ -0,0 +1,54 @@
+import { BLOCK_SLOTS, EXPERIMENT_BLOCK_SLUG, hostBlocks, slotBlocks } from '../blocks/model.js';
+import { manifestOf, suppressExposure } from './context.js';
+export function resolveExperimentBlocks(blocks, assignments, { blockSlug = EXPERIMENT_BLOCK_SLUG } = {}) {
+    const result = {
+        blocks: [],
+        rendered: [],
+        groups: []
+    };
+    const exposed = new Set();
+    for (const block of hostBlocks(blocks)){
+        if (block.blockType !== blockSlug) {
+            const clean = {
+                ...block
+            };
+            delete clean.xpGroup;
+            result.blocks.push(clean);
+            continue;
+        }
+        const slug = typeof block.experiment === 'string' ? block.experiment : '';
+        const assignment = Object.hasOwn(assignments.bySlug, slug) ? assignments.bySlug[slug] : undefined;
+        const experiment = manifestOf(assignments)?.experiments.find((e)=>e.slug === slug);
+        const arm = experiment?.arms.find((a)=>a.key === assignment?.arm);
+        const archived = Object.hasOwn(assignments.archivedWinners, slug) ? assignments.archivedWinners[slug] : undefined;
+        const slot = assignment ? assignment.arm === 'holdout' ? 'control' : arm?.slot ?? assignment.arm : archived ?? 'control';
+        const selected = BLOCK_SLOTS.includes(slot) ? slotBlocks(block, slot) : [];
+        const content = selected.length ? selected : slotBlocks(block, 'control');
+        const group = {
+            slug
+        };
+        if (selected.length && assignment?.exposable && !suppressExposure(assignments)) {
+            const exposure = {
+                slug,
+                arm: assignment.arm,
+                phase: assignment.phase
+            };
+            if (assignment.policy === 'render' && !exposed.has(slug)) {
+                result.rendered.push(exposure);
+                exposed.add(slug);
+            }
+            if (assignment.policy === 'viewport') group.expose = exposure;
+        }
+        const start = result.blocks.length;
+        result.blocks.push(...content.map((row)=>({
+                ...row,
+                xpGroup: group
+            })));
+        if (content.length) result.groups.push({
+            ...group,
+            start,
+            end: result.blocks.length
+        });
+    }
+    return result;
+}

package/dist/server/runResults.js

@@ -1,4 +1,6 @@
+import { asymmetricGoal, goalContent, goalPlacementDetail, LEGACY_FAIRNESS } from '../goals/fairness.js';
 import { XpAnalysisError } from '../errors.js';
+import { canonicalHealth, mergePageHealth } from '../results/health.js';
 import { safeError } from '../log.js';
 import { createLocalReq } from 'payload';
 import { resultsCandidates, resultsExecutor, writeSnapshots } from '../db/snapshots.js';
@@ -120,9 +122,9 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
             ].reduce((earliest, unit)=>Math.min(earliest, +unit.firstTs), timestampMs(phase.startedAt)));
             const preFrom = new Date(+from - 14 * 86_400_000);
             let events, covariates;
-            if (definition.source.startsWith('events:')) {
-                const eventName = definition.source.slice(7);
-                if (!options.eventSources?.some((source)=>source.name === eventName)) throw new XpAnalysisError('source-unavailable');
+            if (definition.source.startsWith('events:') || definition.source.startsWith('click:')) {
+                const eventName = definition.source.startsWith('click:') ? definition.source : definition.source.slice(7);
+                if (!definition.source.startsWith('click:') && !options.eventSources?.some((source)=>source.name === eventName)) throw new XpAnalysisError('source-unavailable');
                 const read = async (start)=>{
                     if (candidate.unitType === 'user') return metricEventRows(exec, {
                         eventName,
@@ -221,9 +223,12 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
                 }
             }
             if (events.some((event)=>!Number.isFinite(event.value))) throw new XpAnalysisError('non-finite-values');
+            // The click-goal delta supersedes whole-phase attribution for mid-test adds.
+            // Retain pre-period events for CUPED above; exclude them from the outcome.
+            const outcomeEvents = definition.source.startsWith('click:') && definition.addedAt ? events.filter((event)=>timestampMs(event.ts) >= timestampMs(definition.addedAt)) : events;
             metricData.push({
                 metricId: definition.metricId,
-                values: perUnitValues(units, events, {
+                values: perUnitValues(units, outcomeEvents, {
                     kind,
                     windowHours,
                     endedAt: to
@@ -349,7 +354,7 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
                 } : await analyseCandidate(exec, phase, options, now, analysisDeadline, summary.unavailableMetrics, payload.logger));
             }
             if (Date.now() >= analysisDeadline) throw new ResultsBudgetError();
-            const current = phases.find((candidate)=>candidate.kind === 'page' && candidate.phase.phase === candidate.currentPhase && (candidate.status === 'running' || candidate.status === 'decided'));
+            const current = phases.find((candidate)=>candidate.phase.phase === candidate.currentPhase && (candidate.status === 'running' || candidate.status === 'decided'));
             if (current) {
                 const req = await raceDeadline(analysisDeadline, ()=>createLocalReq({}, payload));
                 const health = [];
@@ -358,12 +363,12 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
                     ...current.phase.arms.filter((arm)=>arm.kind !== 'holdout'),
                     ...current.testArms.filter((arm)=>arm.kind === 'control')
                 ] : current.testArms.filter((arm)=>arm.kind !== 'holdout' && (current.status !== 'decided' || arm.kind === 'control' || arm.key === current.winnerArm));
-                const targets = new Set(arms.flatMap((arm)=>arm.pageTarget ? [
+                const targets = new Set((current.kind === 'page' ? arms : []).flatMap((arm)=>arm.pageTarget ? [
                         arm.pageTarget
                     ] : []));
                 for (const path of targets){
                     let published = false, found = false, unchecked = false;
-                    for (const collection of options.pages?.collections ?? []){
+                    for (const collection of current.pageCollection ? options.pages?.collections.filter((entry)=>entry.slug === current.pageCollection) ?? [] : options.pages?.collections ?? []){
                         try {
                             const page = await raceDeadline(analysisDeadline, ()=>collection.findByPath(path, req));
                             found ||= page != null;
@@ -382,16 +387,52 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
                         path
                     });
                 }
-                for (const snapshot of snapshots)snapshot.health = health;
+                const clicks = current.phase.metricDefinitions.filter((metric)=>metric.source.startsWith('click:'));
+                const content = clicks.length ? await raceDeadline(analysisDeadline, ()=>goalContent(req, options, {
+                        id,
+                        slug: current.slug ?? String(id),
+                        kind: current.kind ?? 'code',
+                        arms: arms,
+                        pageCollection: current.pageCollection
+                    }, current.testPlacementDocs ?? null)) : undefined;
+                const goals = clicks.filter((metric)=>content && asymmetricGoal(content, metric.source, arms)).map((metric)=>({
+                        code: 'goal-in-some-versions',
+                        metricId: metric.metricId,
+                        name: metric.name
+                    }));
+                const unchecked = (content?.unchecked ?? []).map((placement)=>({
+                        code: 'placement-unchecked',
+                        detail: goalPlacementDetail(placement)
+                    }));
+                for (const [index, snapshot] of snapshots.entries()){
+                    const previous = phases[index].previousHealth ?? phases[index].frozenSnapshot?.health ?? [];
+                    const unjudged = previous.filter((row)=>row.code === 'goal-in-some-versions' && content && content.unchecked.length > 0 && clicks.some((metric)=>metric.metricId === row.metricId && !asymmetricGoal(content, metric.source, arms)));
+                    snapshot.health = mergePageHealth(unjudged, [
+                        ...health,
+                        ...goals,
+                        ...unchecked
+                    ]);
+                    if (content?.skipped && current.kind === 'block') snapshot.goalFairnessNotice = LEGACY_FAIRNESS;
+                    else delete snapshot.goalFairnessNotice;
+                }
             }
             if (Date.now() >= analysisDeadline) throw new ResultsBudgetError();
-            // Order and optional empty health are semantically identical. Frozen
-            // inference gets a new row only when its page availability changes.
-            const canonicalHealth = (snapshot)=>JSON.stringify((snapshot.health ?? []).map(({ code, path })=>[
-                        code,
-                        path
-                    ]).map((entry)=>JSON.stringify(entry)).sort((a, b)=>a < b ? -1 : a > b ? 1 : 0));
-            const changed = snapshots.filter((snapshot, index)=>!phases[index].frozenSnapshot || canonicalHealth(snapshot) !== canonicalHealth(phases[index].frozenSnapshot));
+            // New read failures alone do not rewrite frozen inference. Recovery must
+            // clear an unchecked row stored alongside a real health change.
+            const changed = snapshots.filter((snapshot, index)=>{
+                const frozen = phases[index].frozenSnapshot;
+                if (!frozen || canonicalHealth(snapshot, true) !== canonicalHealth(frozen, true)) return true;
+                const freshUnchecked = new Set((snapshot.health ?? []).filter((row)=>row.code === 'placement-unchecked').map((row)=>canonicalHealth({
+                        health: [
+                            row
+                        ]
+                    })));
+                return (frozen.health ?? []).some((row)=>row.code === 'placement-unchecked' && !freshUnchecked.has(canonicalHealth({
+                        health: [
+                            row
+                        ]
+                    })));
+            });
             // Unchanged health is a successful refresh with nothing to write.
             if (!changed.length) {
                 summary.ran++;

package/dist/server/toClientAssignments.js

@@ -40,7 +40,8 @@ export function toClientAssignments(assignments, opts) {
         apiRoute: opts.apiRoute ?? '/api',
         experiments,
         flagPoints,
-        pageviews: []
+        pageviews: [],
+        clickGoalsArmed: !blocked && Object.values(assignments.bySlug).some((a)=>a.exposable)
     };
     if (!blocked) for (const e of manifest?.experiments ?? []){
         const a = assignments.bySlug[e.slug];

package/dist/transitions/addMetric.d.ts

@@ -1,6 +1,6 @@
 import type { PayloadRequest } from 'payload';
 import type { DocId, ResolvedOptions } from '../types/contracts.js';
-import type { AddMetricBody } from '../types/endpoints.js';
+import type { AddMetricBody, AddMetricWarning } from '../types/endpoints.js';
 export declare function addMetric<TUser extends {
     id: DocId;
 }>(req: PayloadRequest, { experimentId, metric, role, options }: AddMetricBody & {
@@ -11,6 +11,7 @@ export declare function addMetric<TUser extends {
         metricId: DocId;
         message: string;
     }[] | undefined;
+    warnings: AddMetricWarning[];
     doc: import("payload").JsonObject & import("payload").TypeWithID;
     revision: number;
 }>;

package/dist/transitions/addMetric.js

@@ -1,3 +1,4 @@
+import { asymmetricGoal, goalContent, goalPlacementDetail } from '../goals/fairness.js';
 import { lockMetricsForFreeze } from '../db/metricUsage.js';
 import { readState } from '../db/state.js';
 import { XpRefusal } from '../errors.js';
@@ -23,6 +24,31 @@ export async function addMetric(req, { experimentId, metric, role, options }) {
     });
     if (!found.docs[0]) throw new XpRefusal('not-found', 'Metric not found', undefined, 404);
     const metricId = found.docs[0].id;
+    const warnings = [];
+    if (String(found.docs[0].source).startsWith('click:')) {
+        const content = await goalContent(req, options, before);
+        if (asymmetricGoal(content, String(found.docs[0].source), before.arms)) {
+            const detail = {
+                metricId,
+                name: found.docs[0].name
+            };
+            if (role === 'guardrail') refuse('goal-in-some-versions', detail);
+            warnings.push({
+                code: 'goal-in-some-versions',
+                detail
+            });
+        }
+        warnings.push(...content.unchecked.map((placement)=>({
+                code: 'placement-unchecked',
+                detail: goalPlacementDetail(placement)
+            })));
+        warnings.push({
+            code: 'goal-added-mid-test',
+            detail: {
+                metricId
+            }
+        });
+    }
     const at = new Date();
     // §5.4: cap history ends at the phase start, never inside the running phase.
     const started = before.startedAt;
@@ -53,7 +79,7 @@ export async function addMetric(req, { experimentId, metric, role, options }) {
         if (lockedMetrics[0].slug !== definition.slug || lockedMetrics[0].source !== definition.source) {
             throw new XpRefusal('stale-draft', 'This goal changed. Review it again before adding it.', undefined, 409);
         }
-        if (current.unitType === 'user' && definition.keyedBy === 'visitor' && !definition.source.startsWith('events:')) refuse('unit-source-mismatch');
+        if (current.unitType === 'user' && definition.keyedBy === 'visitor' && !definition.source.startsWith('events:') && !definition.source.startsWith('click:')) refuse('unit-source-mismatch');
         // §7.8: phase lookup serves the access-authorised transition write.
         const phases = await req.payload.find({
             collection: 'xp-phases',
@@ -127,6 +153,7 @@ export async function addMetric(req, { experimentId, metric, role, options }) {
     });
     return {
         ...result,
+        warnings,
         ...caps.detail.length ? {
             detail: caps.detail
         } : {}

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-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 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,6 +52,15 @@ 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'>[];

package/dist/transitions/checkStart.js

@@ -1,3 +1,4 @@
+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';
@@ -18,6 +19,11 @@ export const relationshipId = (value)=>value == null ? undefined : typeof value
  * 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)=>{
@@ -61,6 +67,28 @@ 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, {
@@ -79,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], {
@@ -97,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,4 +1,7 @@
+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 { lockPagePaths } from '../db/locks.js';
@@ -10,6 +13,8 @@ import { readPhaseRecord, setPhaseEndedAt, writePhaseRecord } from './phaseRecor
 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),
@@ -47,6 +52,13 @@ 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.
@@ -59,6 +71,18 @@ export async function decide(req, { experimentId, winnerArm, note, confirmation
             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');

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(),