@delmaredigital/payload-experiments 0.2.0-rc.7 → 0.3.0-rc.4

package/dist/server/linkIdentity.js

@@ -2,33 +2,35 @@ import { safeError } from '../log.js';
 import { NextRequest } from 'next/server.js';
 import { insertIdentityOnOwnConnection } from '../db/identities.js';
 import { readUnitCookie } from '../runtime/cookie.js';
-export async function linkIdentity(serverRuntime, opts) {
+/**
+ * verified: true means this request proves, in this browser, that the person owns
+ * the account: a magic-link or one-time-code callback, password sign-in, or OAuth
+ * callback. It does not mean "a session exists" or "the email is verified".
+ * Never throws into registration or sign-in.
+ */ export async function linkIdentity(serverRuntime, opts) {
     let payload;
     try {
         const runtime = serverRuntime.proxyRuntime;
         // Consent sees cookies and headers only; the URL is a placeholder.
-        let consent = true;
-        try {
-            consent = runtime.cookie.consent?.(new NextRequest('http://consent.invalid/', {
-                headers: opts.headers
-            })) !== false;
-        } catch  {
-            console.error('[payload-experiments] consent failed; treating consent as false');
-            consent = false;
-        }
-        if (!consent) return;
+        const consent = runtime.cookie.consent?.(new NextRequest('http://consent.invalid/', {
+            headers: opts.headers
+        })) !== false;
+        if (!consent) return 'skipped';
         const anonymousId = readUnitCookie(opts.headers, runtime);
-        if (!anonymousId) return;
+        if (!anonymousId) return 'skipped';
         payload = await serverRuntime.getPayload();
-        await insertIdentityOnOwnConnection(payload, {
+        return await insertIdentityOnOwnConnection(payload, {
             anonymousId,
-            userId: opts.userId
+            userId: opts.userId,
+            verified: opts.verified
         });
     } catch (error) {
         try {
-            payload?.logger.error({
+            if (payload) payload.logger.error({
                 err: safeError(error)
             }, 'Experiments: linkIdentity failed');
+            else console.error('[payload-experiments] linkIdentity failed', safeError(error));
         } catch  {}
+        return 'failed';
     }
 }

package/dist/server/metadata.d.ts

@@ -1,5 +1,10 @@
 import type { Metadata } from 'next';
 import type { ExperimentsServerRuntime } from '../types/runtime.js';
+/**
+ * Reads the signed request context via `headers()`, so it decides from the URL the visitor requested, not the
+ * rewritten route. Call it only from a dynamic `generateMetadata`, never inside `'use cache'`. `path` is the
+ * fallback when the proxy did not run.
+ */
 export declare function experimentMetadata<TUser extends {
     id: string | number;
 } = {

package/dist/server/metadata.js

@@ -1,18 +1,33 @@
 import { findNormalisedPathKey, normalisePath } from '../runtime/normalisePath.js';
+import { headers } from 'next/headers.js';
+import { serverRequest } from './request.js';
 import { serverManifest } from './context.js';
-export async function experimentMetadata(serverRuntime, path) {
+/**
+ * Reads the signed request context via `headers()`, so it decides from the URL the visitor requested, not the
+ * rewritten route. Call it only from a dynamic `generateMetadata`, never inside `'use cache'`. `path` is the
+ * fallback when the proxy did not run.
+ */ export async function experimentMetadata(serverRuntime, path) {
+    const { request, hasContext } = serverRequest(new Headers(await headers()), serverRuntime.proxyRuntime.secrets);
+    if (hasContext) path = request.nextUrl.pathname;
     const manifest = await serverManifest(serverRuntime.proxyRuntime);
     const live = manifest?.experiments.find((e)=>e.kind === 'page' && e.arms.some((a)=>a.pageTarget !== undefined && normalisePath(a.pageTarget) === normalisePath(path)));
     if (live) {
         const controlPath = live.arms.find((a)=>a.kind === 'control')?.pageTarget;
-        return controlPath && normalisePath(path) !== normalisePath(controlPath) ? {
+        if (!controlPath) return {};
+        // The Original's URL may be served with a variant's route: its canonical must stay on the Original,
+        // never the (noindexed) variant route the host would otherwise derive.
+        return normalisePath(path) !== normalisePath(controlPath) ? {
             robots: {
                 index: false
             },
             alternates: {
                 canonical: controlPath
             }
-        } : {};
+        } : {
+            alternates: {
+                canonical: controlPath
+            }
+        };
     }
     const archivedPath = manifest ? findNormalisedPathKey(manifest.archivedPages, path) : undefined;
     const archived = archivedPath === undefined ? undefined : manifest?.archivedPages[archivedPath];

package/dist/server/normaliseContentRelationships.d.ts

@@ -0,0 +1,7 @@
+import type { Block, Field } from 'payload';
+/** 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 declare function normaliseContentRelationships(data: unknown, fields: Field[], blocks?: Block[], locales?: readonly string[]): unknown;

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/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,10 @@
 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 { withTransition } from '../transitions/kernel.js';
+import { normaliseContentRelationships } from './normaliseContentRelationships.js';
 const slots = [
     'control',
     'variantA',
@@ -54,8 +55,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 +64,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,8 +97,8 @@ 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 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));
         return [
             ...new Set([
@@ -107,12 +107,21 @@ 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;
+        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));
         const experiments = new Map();
         for (const binding of changed){
             const experiment = await runningContentExperiment(executor, binding);

package/dist/server/runResults.d.ts

@@ -1,10 +1,11 @@
-import type { Payload } from 'payload';
+import { type Payload } from 'payload';
+import type { MetricUnavailableReason } from '../types/reasons.js';
 import type { DocId } from '../types/contracts.js';
 type UnavailableMetric = {
     experimentId: DocId;
     phase: number;
     metricId: DocId;
-    reason: string;
+    reason: MetricUnavailableReason;
 };
 export declare function runResults(payload: Payload, { budgetMs, experimentId, sweep }?: {
     budgetMs?: number;

package/dist/server/runResults.js

@@ -1,4 +1,6 @@
+import { XpAnalysisError } from '../errors.js';
 import { safeError } from '../log.js';
+import { createLocalReq } from 'payload';
 import { resultsCandidates, resultsExecutor, writeSnapshots } from '../db/snapshots.js';
 import { sweepEvents } from '../db/sweep.js';
 import { armMismatchCount, identityRows, metricEventRows, phaseExposureRows, rolloutExposureRows } from '../db/results.js';
@@ -6,8 +8,8 @@ import { raceDeadline, ResultsBudgetError, RESULTS_TIMEOUT_MARGIN_MS } from '../
 import { analysePhase } from '../results/analyse.js';
 import { firstExposures, perUnitValues, timestampMs } from '../results/aggregate.js';
 import { rolloutAnalysisUnits } from '../results/rolloutUnits.js';
-import { creditUserEvents } from '../results/identityCredit.js';
-async function analyseCandidate(exec, candidate, options, now, deadline, unavailableMetrics) {
+import { creditUserEvents, eligibleIdentityLinks } from '../results/identityCredit.js';
+async function analyseCandidate(exec, candidate, options, now, deadline, unavailableMetrics, logger) {
     const { phase } = candidate;
     // Rollout assignment preserves the original test ranges, but its SRM compares
     // only the shipped group against holdout with weights {100-h, h}.
@@ -59,23 +61,54 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
         ...new Set(identities.map((identity)=>identity.userId))
     ];
     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).events;
-        return userKeyed ? credited : [
-            ...events.filter((event)=>event.userId == null || !linked.has(event.userId)),
+        const credited = creditUserEvents(units, identities, userEvents, (userId)=>identityConflicts.add(userId)).events;
+        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
         ];
     };
-    const diagnostics = creditUserEvents(units, identities, []);
     const metricData = [];
     for (const definition of phase.metricDefinitions){
         try {
@@ -89,7 +122,7 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
             let events, covariates;
             if (definition.source.startsWith('events:')) {
                 const eventName = definition.source.slice(7);
-                if (!options.eventSources?.some((source)=>source.name === eventName)) throw new Error('Metric source unavailable');
+                if (!options.eventSources?.some((source)=>source.name === eventName)) throw new XpAnalysisError('source-unavailable');
                 const read = async (start)=>{
                     if (candidate.unitType === 'user') return metricEventRows(exec, {
                         eventName,
@@ -109,9 +142,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);
@@ -132,9 +166,9 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
                 }
             } else {
                 const source = options.metricSources?.find((source)=>source.id === definition.source);
-                if (!source || source.kind !== kind || definition.keyedBy && source.keyedBy !== definition.keyedBy) throw new Error('Metric source unavailable');
+                if (!source || source.kind !== kind || definition.keyedBy && source.keyedBy !== definition.keyedBy) throw new XpAnalysisError('source-unavailable');
                 const userKeyed = source.keyedBy === 'user' && candidate.unitType === 'visitor';
-                if (candidate.unitType === 'user' && source.keyedBy !== 'user') throw new Error('Metric unit type unavailable');
+                if (candidate.unitType === 'user' && source.keyedBy !== 'user') throw new XpAnalysisError('unit-type-unavailable');
                 const sourceIds = userKeyed ? userIds : ids;
                 events = credit(await raceDeadline(deadline, ()=>source.query({
                         from,
@@ -142,35 +176,51 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
                         unitIds: sourceIds
                     })), userKeyed);
                 if (phase.analysis.cuped === 'auto' && source.covariate) {
-                    const sourceUnits = userKeyed ? creditUserEvents(units, identities, userIds.map((userId)=>({
-                            userId,
-                            ts: now,
-                            value: 0
-                        }))).events.map((event)=>({
-                            unitId: identities.find((identity)=>identity.anonymousId === event.unitId).userId,
-                            firstExposureTs: units.get(event.unitId).firstTs
+                    const userUnits = new Map();
+                    if (userKeyed) for (const link of identities){
+                        const unit = units.get(link.anonymousId);
+                        if (!unit) continue;
+                        // Hosts aggregate pre-period values in SQL; per-event rows over 14 days would break the one-row-per-unit contract and multiply host traffic.
+                        // CUPED only reduces variance: mis-credited pre-exposure values add noise, but cannot bias the effect because they are independent of assignment.
+                        if (!eligibleIdentityLinks([
+                            link
+                        ], unit.firstTs).length) continue;
+                        const previous = userUnits.get(link.userId);
+                        if (!previous || +unit.firstTs < +previous.firstExposureTs || +unit.firstTs === +previous.firstExposureTs && link.anonymousId < previous.unitId) {
+                            userUnits.set(link.userId, {
+                                unitId: link.anonymousId,
+                                firstExposureTs: unit.firstTs
+                            });
+                        }
+                    }
+                    const sourceUnits = userKeyed ? [
+                        ...userUnits
+                    ].map(([unitId, unit])=>({
+                            unitId,
+                            firstExposureTs: unit.firstExposureTs
                         })) : [
                         ...units
                     ].map(([unitId, unit])=>({
                             unitId,
-                            firstExposureTs: unit.firstTs
+                            firstExposureTs: new Date(timestampMs(unit.firstTs))
                         }));
                     const pre = await raceDeadline(deadline, ()=>source.covariate({
                             units: sourceUnits,
                             lookbackDays: 14
                         }));
-                    if (pre.some((row)=>!Number.isFinite(row.value))) throw new Error('Covariates must be finite');
-                    const credited = credit(pre.map((row)=>({
-                            ...row,
-                            ts: now
-                        })), userKeyed);
-                    covariates = new Map(credited.map((row)=>[
-                            row.unitId,
-                            row.value
-                        ]));
+                    if (pre.some((row)=>!Number.isFinite(row.value))) throw new XpAnalysisError('non-finite-covariates');
+                    covariates = new Map(pre.flatMap((row)=>{
+                        const unitId = userKeyed ? userUnits.get(row.unitId)?.unitId : row.unitId;
+                        return unitId === undefined ? [] : [
+                            [
+                                unitId,
+                                row.value
+                            ]
+                        ];
+                    }));
                 }
             }
-            if (events.some((event)=>!Number.isFinite(event.value))) throw new Error('Metric values must be finite');
+            if (events.some((event)=>!Number.isFinite(event.value))) throw new XpAnalysisError('non-finite-values');
             metricData.push({
                 metricId: definition.metricId,
                 values: perUnitValues(units, events, {
@@ -183,7 +233,22 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
                 } : {}
             });
         } catch (error) {
-            const reason = error instanceof Error ? error.message : 'Metric source unavailable';
+            let reason = error instanceof ResultsBudgetError ? 'budget' : 'source-failed';
+            if (error instanceof XpAnalysisError) {
+                switch(error.code){
+                    case 'source-unavailable':
+                    case 'unit-type-unavailable':
+                    case 'non-finite-values':
+                    case 'non-finite-covariates':
+                        reason = error.code;
+                        break;
+                }
+            }
+            logger.error({
+                err: safeError(error),
+                experimentId: phase.experiment,
+                metricId: definition.metricId
+            }, 'Experiment metric source failed');
             metricData.push({
                 metricId: definition.metricId,
                 values: new Map(),
@@ -205,9 +270,14 @@ async function analyseCandidate(exec, candidate, options, now, deadline, unavail
         units,
         metricData,
         status,
+        onMetricError: (error, metricId)=>logger.error({
+                err: safeError(error),
+                experimentId: phase.experiment,
+                metricId
+            }, 'Experiment metric analysis failed'),
         excludedMultiArm: exposed.excludedMultiArm,
         armMismatch: await armMismatchCount(exec, query),
-        identityConflictShare: userIds.length ? diagnostics.conflicts / userIds.length : 0,
+        identityConflictShare: userIds.length ? identityConflicts.size / userIds.length : 0,
         ...phase.phaseKind === 'rollout' ? {
             winnerArm: phase.arms.find((arm)=>arm.kind !== 'holdout').key
         } : {}
@@ -252,8 +322,8 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
             experimentId
         }, 'Experiment scheduling failed');
     }
-    // Query order is oldest phase snapshot first; grouping keeps each experiment's
-    // phases together while preserving that scheduling priority.
+    // Analysis precedes health-only refreshes, then oldest phase snapshots first;
+    // grouping keeps each experiment's phases together with that priority.
     const experiments = new Map();
     for (const candidate of candidates){
         const id = candidate.phase.experiment;
@@ -272,10 +342,62 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
             const snapshots = [];
             for (const phase of phases){
                 if (Date.now() >= analysisDeadline) throw new ResultsBudgetError();
-                snapshots.push(await analyseCandidate(exec, phase, options, now, analysisDeadline, summary.unavailableMetrics));
+                // Health refreshes must not reopen inference after the late-beacon grace.
+                snapshots.push(phase.frozenSnapshot ? {
+                    ...phase.frozenSnapshot,
+                    computedAt: now.toISOString()
+                } : 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'));
+            if (current) {
+                const req = await raceDeadline(analysisDeadline, ()=>createLocalReq({}, payload));
+                const health = [];
+                // Decided tests serve only the winner and Original, including rollouts.
+                const arms = current.phase.phaseKind === 'rollout' ? [
+                    ...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 ? [
+                        arm.pageTarget
+                    ] : []));
+                for (const path of targets){
+                    let published = false, found = false, unchecked = false;
+                    for (const collection of options.pages?.collections ?? []){
+                        try {
+                            const page = await raceDeadline(analysisDeadline, ()=>collection.findByPath(path, req));
+                            found ||= page != null;
+                            published ||= page?.published === true;
+                        } catch (error) {
+                            if (error instanceof ResultsBudgetError) throw error;
+                            payload.logger.error({
+                                err: safeError(error),
+                                experimentId: id
+                            }, 'Experiment version page lookup failed');
+                            unchecked = true;
+                        }
+                    }
+                    if (!published) health.push({
+                        code: !found && (unchecked || !options.pages?.collections.length) ? 'version-page-unchecked' : 'version-page-unavailable',
+                        path
+                    });
+                }
+                for (const snapshot of snapshots)snapshot.health = health;
             }
             if (Date.now() >= analysisDeadline) throw new ResultsBudgetError();
-            await writeSnapshots(exec, snapshots);
+            // 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));
+            // Unchanged health is a successful refresh with nothing to write.
+            if (!changed.length) {
+                summary.ran++;
+                continue;
+            }
+            await writeSnapshots(exec, changed);
             summary.ran++;
             if (summary.processedIds.length < 100) summary.processedIds.push(id);
         } catch (error) {

package/dist/targeting/values.d.ts

@@ -0,0 +1,4 @@
+/** Trim and deduplicate list inputs while preserving commas inside array items. */
+export declare function coerceListValue(raw: unknown): string[];
+/** Only the read boundary accepts legacy comma-separated document values. */
+export declare function readListValue(raw: unknown): string[];

package/dist/targeting/values.js

@@ -0,0 +1,10 @@
+/** Trim and deduplicate list inputs while preserving commas inside array items. */ export function coerceListValue(raw) {
+    return [
+        ...new Set((Array.isArray(raw) ? raw.map(String) : [
+            String(raw ?? '')
+        ]).map((value)=>value.trim()).filter(Boolean))
+    ];
+}
+/** Only the read boundary accepts legacy comma-separated document values. */ export function readListValue(raw) {
+    return coerceListValue(typeof raw === 'string' ? raw.split(',') : raw);
+}

package/dist/transitions/addMetric.js

@@ -1,3 +1,4 @@
+import { lockMetricsForFreeze } from '../db/metricUsage.js';
 import { readState } from '../db/state.js';
 import { XpRefusal } from '../errors.js';
 import { relationshipId } from './checkStart.js';
@@ -44,7 +45,14 @@ export async function addMetric(req, { experimentId, metric, role, options }) {
         if (ids.some((id)=>id !== undefined && String(id) === String(metric))) refuse('duplicate-metric', {
             message: 'This metric is already part of the experiment.'
         });
+        const lockedMetrics = await lockMetricsForFreeze(exec, caps.definitions.map((metric)=>metric.id));
+        if (!lockedMetrics) {
+            throw new XpRefusal('stale-draft', 'This goal was deleted. Choose another goal.', undefined, 409);
+        }
         const definition = caps.definitions[0];
+        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');
         // §7.8: phase lookup serves the access-authorised transition write.
         const phases = await req.payload.find({

package/dist/transitions/archive.js

@@ -1,3 +1,4 @@
+import { contentDone } from '../contentDone.js';
 import { relationshipId } from './checkStart.js';
 import { expectedConfirm, matchesConfirm, storedWinnerLabel } from './confirmPhrases.js';
 import { withTransition } from './kernel.js';
@@ -14,9 +15,7 @@ export async function archive(req, { experimentId, mode, confirmation }) {
         if (mode === 'stopped' ? current.status !== 'stopped' : current.status !== 'decided') refuse('invalid-status');
         if (mode === 'hard-coded' && current.kind !== 'code') refuse('invalid-status');
         if (mode === 'after-content') {
-            const report = decision?.contentReport;
-            const docs = Array.isArray(report) ? report : report?.docs;
-            if (!Array.isArray(docs) || !docs.every((doc)=>doc?.ok === true)) refuse('invalid-status');
+            if (!contentDone(decision?.contentReport)) refuse('invalid-status');
         }
         if (mode === 'discard' && !matchesConfirm(expectedConfirm('discard', ''), confirmation)) refuse('confirmation-required');
         if (mode === 'hard-coded') {