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

package/dist/puck/xpGoalField.js

@@ -0,0 +1,6 @@
+/** Prop config only. Components render xpGoal as data-xp-goal. */ export function xpGoalPuckField() {
+    return {
+        type: 'text',
+        label: 'Click goal'
+    };
+}

package/dist/results/health.d.ts

@@ -0,0 +1,4 @@
+import type { Snapshot, SnapshotHealth } from '../types/snapshot.js';
+/** Refresh page health while retaining health produced by other checks. */
+export declare function mergePageHealth(previous: readonly SnapshotHealth[], pages: readonly SnapshotHealth[]): SnapshotHealth[];
+export declare function canonicalHealth(snapshot: Pick<Snapshot, 'health' | 'goalFairnessNotice'>, ignoreUncheckedPlacements?: boolean): string;

package/dist/results/health.js

@@ -0,0 +1,27 @@
+const healthKey = (row)=>JSON.stringify(row.code === 'placement-unchecked' ? [
+        row.code,
+        row.detail.collection ?? '',
+        row.detail.id ?? '',
+        row.detail.path ?? ''
+    ] : [
+        row.code,
+        'path' in row ? row.path : '',
+        'metricId' in row ? row.metricId : ''
+    ]);
+/** Refresh page health while retaining health produced by other checks. */ export function mergePageHealth(previous, pages) {
+    return [
+        ...new Map([
+            ...previous.filter((row)=>row.code === 'goal-in-some-versions' || row.code === 'placement-unchecked'),
+            ...pages
+        ].map((row)=>[
+                healthKey(row),
+                row
+            ])).values()
+    ];
+}
+export function canonicalHealth(snapshot, ignoreUncheckedPlacements = false) {
+    return JSON.stringify([
+        snapshot.goalFairnessNotice ?? '',
+        ...(snapshot.health ?? []).filter((row)=>!ignoreUncheckedPlacements || row.code !== 'placement-unchecked').map(healthKey).sort()
+    ]);
+}

package/dist/results/snapshot.js

@@ -7,6 +7,7 @@ const count = (value)=>number(value) && Number.isInteger(value) && value >= 0;
 const string = (value)=>typeof value === 'string';
 const boolean = (value)=>typeof value === 'boolean';
 const nullable = (check)=>(value)=>value === null || check(value);
+const union = (...checks)=>(value)=>checks.some((check)=>check(value));
 const list = (check)=>(value)=>Array.isArray(value) && value.every(check);
 const oneOf = (...values)=>(value)=>values.includes(value);
 const isObject = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -140,10 +141,22 @@ const shape = object({
         by: nullable(id)
     }))
 }, {
-    health: list(object({
+    goalFairnessNotice: string,
+    health: list(union(object({
         code: oneOf('version-page-unavailable', 'version-page-unchecked'),
         path: string
-    }))
+    }), object({
+        code: oneOf('goal-in-some-versions'),
+        metricId: id,
+        name: string
+    }), object({
+        code: oneOf('placement-unchecked'),
+        detail: object({}, {
+            collection: string,
+            id,
+            path: string
+        })
+    })))
 });
 /** Validate the frozen JSON shape and headline/rollout invariants before storage.
  * This also accepts the shared CORE-13/admin fixtures without any I/O.

package/dist/sanitizeReadinessDetail.js

@@ -16,12 +16,55 @@ const failure = (value)=>value === 'placements-failed' || value === 'forbidden'
  * counts and layer capacity, which are not identifiers).
  */ export function sanitizeReadinessDetail(code, detail) {
     switch(code){
+        case 'goal-in-some-versions':
+            {
+                const rows = Array.isArray(detail) ? detail : [
+                    detail
+                ];
+                return rows.filter(object).filter((row)=>key(row.metricId) || typeof row.metricId === 'number' && Number.isSafeInteger(row.metricId)).map((row)=>({
+                        metricId: row.metricId
+                    }));
+            }
+        case 'placement-unchecked':
+            return object(detail) ? Object.fromEntries(Object.entries(detail).filter(([k, v])=>k === 'path' ? path(v) : [
+                    'collection',
+                    'id'
+                ].includes(k) && (key(v) || typeof v === 'number' && Number.isSafeInteger(v)))) : undefined;
+        case 'placement-unpublished':
+        case 'duplicate-version-row':
+        case 'interacting-tests':
+            return Array.isArray(detail) ? detail.filter(object).map((row)=>Object.fromEntries(Object.entries(row).filter(([k, v])=>[
+                        'collection',
+                        'id',
+                        'experimentId',
+                        'slug'
+                    ].includes(k) ? key(v) || typeof v === 'number' && Number.isSafeInteger(v) : k === 'path' ? path(v) : k === 'status' ? [
+                        'running',
+                        'decided'
+                    ].includes(String(v)) : k === 'version' && typeof v === 'boolean'))) : undefined;
+        case 'version-same-address':
+            return object(detail) && arm(detail.arm) && arm(detail.otherArm) && path(detail.path) ? {
+                arm: detail.arm,
+                otherArm: detail.otherArm,
+                path: detail.path
+            } : undefined;
+        case 'version-identical':
+            return object(detail) && arm(detail.arm) && key(detail.collection) && (key(detail.id) || typeof detail.id === 'number' && Number.isSafeInteger(detail.id)) ? {
+                arm: detail.arm,
+                collection: detail.collection,
+                id: detail.id,
+                ...path(detail.path) ? {
+                    path: detail.path
+                } : {}
+            } : undefined;
         case 'block-path-rule':
             return object(detail) && Array.isArray(detail.rules) && detail.rules.length && detail.rules.every((index)=>Number.isSafeInteger(index) && index >= 0) ? {
                 rules: detail.rules
             } : undefined;
         case 'no-placements':
             return failure(detail) ? detail : undefined;
+        case 'placement-removed':
+            return undefined;
         case 'page-in-use':
             {
                 if (!object(detail) || !Array.isArray(detail.paths)) return undefined;

package/dist/server/pageKindSeoContract.d.ts

@@ -0,0 +1,27 @@
+import type { Manifest } from '../types/manifest.js';
+export interface PageKindSeoContractOptions {
+    secret: string;
+    original: string;
+    versions: string[];
+    state: 'running' | 'decided' | 'archived';
+    winner?: string;
+}
+export interface PageKindSeoContractRow {
+    requestPath: string;
+    servedPath: string;
+    headers: {
+        'x-xp-request': string;
+    };
+    expect: {
+        robots?: {
+            index: false;
+        };
+        canonical?: string;
+        inSitemap: boolean;
+    };
+}
+/** Host-test fixture: use this manifest in the runtime that serves the signed row headers. */
+export declare function pageKindSeoContract({ secret, original, versions, state, winner }: PageKindSeoContractOptions): {
+    manifest: Manifest;
+    rows: PageKindSeoContractRow[];
+};

package/dist/server/pageKindSeoContract.js

@@ -0,0 +1,80 @@
+import { sign } from '../runtime/signing.js';
+import { normalisePath } from '../runtime/normalisePath.js';
+/** Host-test fixture: use this manifest in the runtime that serves the signed row headers. */ export function pageKindSeoContract({ secret, original, versions, state, winner }) {
+    const paths = [
+        original,
+        ...versions
+    ];
+    if (!secret || paths.some((path)=>!path.startsWith('/') || /[\\\r\n#|]/.test(path)) || new Set(paths.map(normalisePath)).size !== paths.length || !versions.length || versions.length > 3 || state !== 'running' && (!winner || !paths.includes(winner))) throw new Error('Invalid page SEO contract');
+    const manifest = {
+        v: 1,
+        revision: 1,
+        experiments: [],
+        flagDefaults: {},
+        archivedWinners: {},
+        archivedPages: {}
+    };
+    if (state === 'archived') {
+        for (const path of paths)if (path !== winner) manifest.archivedPages[path] = {
+            slug: 'page-seo-contract',
+            winnerPath: winner
+        };
+    } else {
+        manifest.experiments.push({
+            id: 'page-seo-contract',
+            slug: 'page-seo-contract',
+            kind: 'page',
+            unitType: 'visitor',
+            status: state,
+            phase: 1,
+            phaseKind: 'test',
+            seed: 'page-seo-contract|',
+            coverage: 1,
+            targeting: [],
+            exposurePolicy: 'pageview',
+            deferrable: false,
+            arms: paths.map((path, index)=>({
+                    key: index === 0 ? 'control' : `variant${String.fromCharCode(64 + index)}`,
+                    kind: index === 0 ? 'control' : 'variant',
+                    weight: index === paths.length - 1 ? 100 - Math.floor(100 / paths.length) * index : Math.floor(100 / paths.length),
+                    pageTarget: path
+                })),
+            ...winner ? {
+                winnerArm: paths.indexOf(winner) === 0 ? 'control' : `variant${String.fromCharCode(64 + paths.indexOf(winner))}`
+            } : {}
+        });
+    }
+    const rows = [];
+    for (const requestPath of paths){
+        const servedPaths = state === 'running' ? paths : [
+            winner
+        ];
+        for (const servedPath of servedPaths){
+            const canonical = state === 'archived' ? requestPath === winner ? undefined : winner : original;
+            rows.push({
+                requestPath,
+                servedPath,
+                headers: {
+                    'x-xp-request': `GET|${requestPath}|c1|${sign(`xp:request:GET|${requestPath}|c1`, [
+                        secret
+                    ])}`
+                },
+                expect: {
+                    ...state !== 'archived' && requestPath !== original ? {
+                        robots: {
+                            index: false
+                        }
+                    } : {},
+                    ...canonical ? {
+                        canonical
+                    } : {},
+                    inSitemap: state === 'archived' ? requestPath === winner : requestPath === original
+                }
+            });
+        }
+    }
+    return {
+        manifest,
+        rows
+    };
+}

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,16 @@
+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' | 'placement-removed' | '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;
+    phase?: number;
+    pageCollection?: string | null;
     arms: Arm[];
     allocation: number;
     exposurePolicy: ExposurePolicy;
@@ -37,6 +40,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 +53,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'>[];