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

package/dist/server/normaliseContentRelationships.js

@@ -0,0 +1,62 @@
+import { contentBlocks } from '../transitions/contentFields.js';
+const object = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value);
+const id = (value)=>object(value) && 'id' in value ? value.id : value;
+/** Undo depth expansion only where the collection schema declares relationships.
+ * Hidden fields and field-level afterRead hooks are unaffected by depth, so
+ * relationship expansion is the only depth-dependent transformation to undo.
+ * Other objects (especially JSON content with its own ids) must stay intact.
+ */ export function normaliseContentRelationships(data, fields, blocks = [], locales = []) {
+    // With locale 'all', a localized field's value is { [locale]: value }: normalise each locale's value.
+    const localeMap = (value)=>locales.length > 0 && object(value) && Object.keys(value).length > 0 && Object.keys(value).every((key)=>locales.includes(key));
+    function lexical(value) {
+        if (!object(value)) return value;
+        const result = {
+            ...value
+        };
+        if (value.type === 'upload' || value.type === 'relationship') result.value = id(value.value);
+        if (Array.isArray(value.children)) result.children = value.children.map(lexical);
+        if (object(value.root)) result.root = lexical(value.root);
+        return result;
+    }
+    function fieldValue(value, field) {
+        if (field.type === 'relationship' || field.type === 'upload') {
+            const one = (entry)=>Array.isArray(field.relationTo) && object(entry) ? {
+                    ...entry,
+                    value: id(entry.value)
+                } : id(entry);
+            return field.hasMany && Array.isArray(value) ? value.map(one) : one(value);
+        }
+        if (field.type === 'richText') return lexical(value);
+        if (field.type === 'array' && Array.isArray(value)) return value.map((row)=>walk(row, field.fields));
+        if (field.type === 'blocks' && Array.isArray(value)) return value.map((row)=>{
+            const block = object(row) && contentBlocks(field, blocks).find((block)=>block.slug === row.blockType);
+            return block ? walk(row, block.fields) : row;
+        });
+        return 'fields' in field ? walk(value, field.fields) : value;
+    }
+    function walk(value, schema) {
+        if (!object(value)) return value;
+        let result = {
+            ...value
+        };
+        for (const field of schema){
+            if (field.type === 'tabs') {
+                for (const tab of field.tabs){
+                    if ('name' in tab && tab.name) {
+                        if (tab.name in result) result[tab.name] = walk(result[tab.name], tab.fields);
+                    } else result = walk(result, tab.fields);
+                }
+            } else if ('name' in field && field.name) {
+                if (field.name in result) {
+                    const value = result[field.name];
+                    result[field.name] = 'localized' in field && field.localized && localeMap(value) ? Object.fromEntries(Object.entries(value).map(([locale, entry])=>[
+                            locale,
+                            fieldValue(entry, field)
+                        ])) : fieldValue(value, field);
+                }
+            } else if ('fields' in field) result = walk(result, field.fields);
+        }
+        return result;
+    }
+    return walk(data, fields);
+}

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.d.ts

@@ -1,5 +1,5 @@
 import type { CollectionAfterChangeHook, CollectionBeforeChangeHook } from 'payload';
-/** Paired beforeChange capture: previousDoc may be an autosaved draft. */
+/** Paired raw beforeChange capture: previousDoc may be an autosaved draft. */
 export declare function capturePublishedContent({ req, collection, originalDoc, operation }: Parameters<CollectionBeforeChangeHook>[0]): Promise<void>;
 type ContentChangeArgs = Pick<Parameters<CollectionAfterChangeHook>[0], 'doc' | 'previousDoc' | 'req' | 'collection'>;
 /** Publish-only host helper. Audit failures are logged, never thrown into saves. */

package/dist/server/recordContentChange.js

@@ -1,9 +1,15 @@
+import { EXPERIMENT_BLOCK_SLUG, hostBlocks } from '../blocks/model.js';
 import { safeError } from '../log.js';
 import { isDeepStrictEqual } from 'node:util';
-import { appendContentChange, contentChangeSavepoint, previousPublishedContent, runningContentExperiment } from '../db/appends.js';
+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 = [
     'control',
     'variantA',
@@ -54,8 +60,7 @@ function bindings(data, puck) {
     return found;
 }
 const baselineKey = (collection, id)=>`${collection}:${id}`;
-/** Paired beforeChange capture: previousDoc may be an autosaved draft. */ export async function capturePublishedContent({ req, collection, originalDoc, operation }) {
-    if (!collection.versions || !collection.versions.drafts) return;
+/** Paired raw beforeChange capture: previousDoc may be an autosaved draft. */ export async function capturePublishedContent({ req, collection, originalDoc, operation }) {
     if (await req.transactionID == null) {
         req.payload.logger?.debug('[payload-experiments] contentChanges baseline skipped without a transaction');
         return;
@@ -64,7 +69,7 @@ const baselineKey = (collection, id)=>`${collection}:${id}`;
     const baselines = req.context.xpPublishedContent ??= {};
     const key = baselineKey(collection.slug, id);
     delete baselines[key];
-    const audit = await contentChangeSavepoint(txExecutor(req), async ()=>operation === 'create' ? undefined : previousPublishedContent(req, collection.slug, id));
+    const audit = await contentChangeSavepoint(txExecutor(req), async ()=>operation === 'create' ? undefined : collection.versions && collection.versions.drafts ? previousPublishedContent(req, collection.slug, id) : storedContent(req, collection.slug, id));
     if (!audit.ok) throw audit.error;
     baselines[key] = {
         collection: collection.slug,
@@ -97,9 +102,33 @@ 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 after = bindings(registration ? doc[registration.field] : doc, Boolean(registration));
-    const changes = (previous)=>{
-        const before = bindings(registration && object(previous) ? previous[registration.field] : previous, Boolean(registration));
+    const changes = (previous, current)=>{
+        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(),
@@ -107,21 +136,51 @@ async function auditContentChange({ doc, previousDoc, req, collection }) {
             ])
         ].filter((key)=>!isDeepStrictEqual(before.get(key)?.contents, after.get(key)?.contents)).map((key)=>after.get(key) ?? before.get(key));
     };
-    if (!drafts && !changes(previousDoc).length) return;
     // Include discovery reads in the savepoint: a SQL read error also aborts Postgres.
     // An explicit host call must supply its afterChange request's transaction.
     const executor = txExecutor(req);
     const audit = await contentChangeSavepoint(executor, async ()=>{
-        const changed = changes(drafts ? baseline?.doc : previousDoc);
+        // Compare like with like. A captured baseline is adapter-raw, so it meets the stored row after the
+        // write. Without one, previousDoc and doc are both afterRead documents (same locale projection,
+        // hidden fields and field hooks) that differ only in depth, so only relationships are normalised.
+        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.');
+            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';
@@ -62,19 +64,50 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
     ];
     const linked = new Set(userIds);
     const identityConflicts = new Set();
+    const userByVisitor = new Map(identities.map((identity)=>[
+            identity.anonymousId,
+            identity.userId
+        ]));
+    const linksByUser = new Map();
+    for (const identity of identities){
+        const links = linksByUser.get(identity.userId) ?? [];
+        links.push(identity);
+        linksByUser.set(identity.userId, links);
+    }
+    // Last arm credited per user: enough to detect that a user's credited events span arms (a conflict).
+    const creditedArms = new Map();
+    const noteCredit = (userId, unitId)=>{
+        const arm = units.get(unitId)?.arm;
+        if (arm === undefined) return;
+        const previous = creditedArms.get(userId);
+        if (previous !== undefined && previous !== arm) identityConflicts.add(userId);
+        creditedArms.set(userId, arm);
+    };
     const credit = (events, userKeyed)=>{
         if (candidate.unitType === 'user') return events.map((event)=>({
                 ...event,
                 unitId: event.userId ?? event.unitId
             }));
-        const userEvents = events.filter((event)=>userKeyed || event.userId != null && linked.has(event.userId)).map((event)=>({
+        // §8.3's earliest exposed linked visitor applies only when the event has no
+        // exposed unit of its own. A visitor-keyed event stays on its own exposed
+        // browser even if an earlier linked browser saw another arm or is ineligible.
+        const direct = userKeyed ? [] : events.filter((event)=>units.has(event.unitId) || event.userId == null || !linked.has(event.userId));
+        const userEvents = events.filter((event)=>userKeyed || !units.has(event.unitId) && event.userId != null && linked.has(event.userId)).map((event)=>({
                 userId: String(event.userId ?? event.unitId),
                 value: event.value,
                 ts: event.ts
             }));
         const credited = creditUserEvents(units, identities, userEvents, (userId)=>identityConflicts.add(userId)).events;
-        return userKeyed ? credited : [
-            ...events.filter((event)=>event.userId == null || !linked.has(event.userId)),
+        for (const event of direct)if (event.userId != null && linked.has(event.userId)) {
+            noteCredit(event.userId, event.unitId);
+            // Keep the eligible-link diagnostic when direct credit bypasses the helper.
+            const arms = new Set(eligibleIdentityLinks(linksByUser.get(event.userId), event.ts).map((link)=>units.get(link.anonymousId).arm));
+            arms.add(units.get(event.unitId).arm);
+            if (arms.size > 1) identityConflicts.add(event.userId);
+        }
+        for (const event of credited)noteCredit(userByVisitor.get(event.unitId), event.unitId);
+        return [
+            ...direct,
             ...credited
         ];
     };
@@ -89,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,
@@ -111,9 +144,10 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
                         from: start,
                         to
                     });
+                    // The two lookups overlap when a linked user's own browser was exposed.
                     return [
                         ...direct,
-                        ...signedIn
+                        ...signedIn.filter((event)=>!units.has(event.unitId))
                     ];
                 };
                 events = credit(await read(phase.analysis.cuped === 'auto' ? preFrom : from), false);
@@ -189,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
@@ -317,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 = [];
@@ -326,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;
@@ -350,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
         } : {}