@delmaredigital/payload-experiments 0.2.0-rc.5 → 0.2.0-rc.7

package/dist/admin/copy/arms.d.ts

@@ -1,12 +1,6 @@
 import type { ArmIssueCode } from '../../types/endpoints.js';
+export { ARM_LABELS as GROUP_LABELS } from '../../labels/arms.js';
 export declare const ISSUE_COPY: Record<ArmIssueCode, string>;
-export declare const GROUP_LABELS: {
-    readonly control: "Original";
-    readonly variantA: "Variant A";
-    readonly variantB: "Variant B";
-    readonly variantC: "Variant C";
-    readonly holdout: "Holdout";
-};
 export declare const ARMS_COPY: {
     readonly holdout: "The holdout sees the Original and is measured but not compared during the test. After you decide, it keeps seeing the Original so the winner can be compared with it.";
     readonly pageRequired: "Enter a page path for this group.";

package/dist/admin/copy/arms.js

@@ -1,3 +1,4 @@
+export { ARM_LABELS as GROUP_LABELS } from '../../labels/arms.js';
 export const ISSUE_COPY = {
     'weights-total': 'Weights must add up to 100%. They add up to {total}% now.',
     'control-count': 'Include exactly one Original.',
@@ -10,13 +11,6 @@ export const ISSUE_COPY = {
     'slot-required': 'Choose the matching content slot for this group.',
     'invalid-key': 'Use the standard group names: Original, Variant A–C, Holdout.'
 };
-export const GROUP_LABELS = {
-    control: 'Original',
-    variantA: 'Variant A',
-    variantB: 'Variant B',
-    variantC: 'Variant C',
-    holdout: 'Holdout'
-};
 export const ARMS_COPY = {
     holdout: 'The holdout sees the Original and is measured but not compared during the test. After you decide, it keeps seeing the Original so the winner can be compared with it.',
     pageRequired: 'Enter a page path for this group.',

package/dist/admin/copy/testPage.d.ts

@@ -1,4 +1,6 @@
 export declare const TEST_PAGE: {
+    readonly staleEdit: "Someone else changed this test. Reload to see their changes.";
+    readonly reload: "Reload";
     readonly loading: "Loading test…";
     readonly forbidden: "You don't have access to this test.";
     readonly missing: "This test no longer exists.";

package/dist/admin/copy/testPage.js

@@ -1,4 +1,6 @@
 export const TEST_PAGE = {
+    staleEdit: 'Someone else changed this test. Reload to see their changes.',
+    reload: 'Reload',
     loading: 'Loading test…',
     forbidden: "You don't have access to this test.",
     missing: 'This test no longer exists.',

package/dist/admin/labels.d.ts

@@ -1,12 +1,7 @@
 import type { ExperimentKind, Status } from '../types/contracts.js';
 import type { VerdictCode } from '../types/snapshot.js';
-export declare const ARM_LABELS: {
-    control: string;
-    variantA: string;
-    variantB: string;
-    variantC: string;
-    holdout: string;
-};
+import { ARM_LABELS } from '../labels/arms.js';
+export { ARM_LABELS };
 export declare const STATUS_LABELS: {
     draft: string;
     running: string;

package/dist/admin/labels.js

@@ -1,10 +1,5 @@
-export const ARM_LABELS = {
-    control: 'Original',
-    variantA: 'Variant A',
-    variantB: 'Variant B',
-    variantC: 'Variant C',
-    holdout: 'Holdout'
-};
+import { ARM_LABELS } from '../labels/arms.js';
+export { ARM_LABELS };
 export const STATUS_LABELS = {
     draft: 'Draft',
     running: 'Running',

package/dist/admin/results/results.model.d.ts

@@ -92,7 +92,7 @@ export interface ResultsContext {
     allocation?: number;
 }
 /** Only selects stored counts; never estimates sample sizes or power in the UI. */
-export declare function collectingLine({ snapshot, phaseKind, status }: RoundLineInput, ctx?: ResultsContext): string | null;
+export declare function collectingLine({ snapshot, phaseKind }: RoundLineInput, ctx?: ResultsContext): string | null;
 export interface DataQualityItem {
     id: string;
     message: string;

package/dist/admin/results/results.model.js

@@ -117,9 +117,8 @@ function smallest(values) {
     if (!values.length || values.some((value)=>value === undefined || !Number.isFinite(value))) return undefined;
     return values.reduce((min, value)=>min === undefined || value !== undefined && value < min ? value : min, undefined);
 }
-/** Only selects stored counts; never estimates sample sizes or power in the UI. */ export function collectingLine({ snapshot, phaseKind, status }, ctx = {}) {
-    if (phaseKind === 'test' && status === 'decided') return null;
-    if (snapshot.verdict.code !== (phaseKind === 'rollout' ? 'rollout-collecting' : 'collecting')) return null;
+/** Only selects stored counts; never estimates sample sizes or power in the UI. */ export function collectingLine({ snapshot, phaseKind }, ctx = {}) {
+    if (phaseKind !== 'rollout' || snapshot.verdict.code !== 'rollout-collecting') return null;
     const keys = comparedKeys(snapshot, ctx.phase);
     const primary = snapshot.metrics.find((metric)=>metric.role === 'primary');
     return collectingCopy(formatCount(smallest(keys.map((key)=>snapshot.exposures.perArm[key]))), formatCount(snapshot.minExposuresPerArm ?? ctx.minExposuresPerArm), formatCount(smallest(keys.map((key)=>primary?.perArm.find((arm)=>arm.arm === key)?.converters))), formatCount(primary ? snapshot.params.minSampleSizes[primary.metricId] : undefined));

package/dist/admin/surface/ResultsRoute.js

@@ -1,5 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
 import { useTestDocument } from './useTestDocument.js';
 import { TestHeader } from './test/TestHeader.js';
 import { ResultsBody } from './results/ResultsBody.js';
@@ -17,6 +18,7 @@ function ManagedResults({ id, surface }) {
     const test = useTestDocument(id, {
         apiRoute: surface.apiRoute
     });
+    const [resultsVersion, setResultsVersion] = useState(0);
     // Add-goal changes metrics while status, phase and allocation stay the same.
     const bodyKey = test.doc ? JSON.stringify([
         test.doc.status,
@@ -31,7 +33,8 @@ function ManagedResults({ id, surface }) {
             test.loadState === 'ready' && test.doc ? /*#__PURE__*/ _jsx(TestHeader, {
                 test: test,
                 surface: surface,
-                view: "results"
+                view: "results",
+                resultsVersion: resultsVersion
             }) : /*#__PURE__*/ _jsx("p", {
                 role: "status",
                 children: test.loadState === 'forbidden' ? C.forbidden : test.loadState === 'missing' ? C.missing : test.loadState === 'error' ? C.error : C.loading
@@ -51,7 +54,8 @@ function ManagedResults({ id, surface }) {
             }) : null,
             test.loadState !== 'loading' && test.loadState !== 'missing' && test.loadState !== 'forbidden' ? /*#__PURE__*/ _jsx(ResultsBody, {
                 id: id,
-                surface: surface
+                surface: surface,
+                onRecomputed: ()=>setResultsVersion((value)=>value + 1)
             }, bodyKey) : null
         ]
     });

package/dist/admin/surface/contracts.d.ts

@@ -25,6 +25,7 @@ export interface SurfaceProps {
 export interface SectionProps {
     test: TestDocApi;
     surface: SurfaceProps;
+    resultsVersion?: number;
 }
 /** Kind-specific pieces the generic test page composes (Setting kind: ADM-22). */
 export interface KindParts {

package/dist/admin/surface/readiness/Banner.js

@@ -19,21 +19,22 @@ export function Banner(props) {
         ...props
     }, `${props.test.doc.id}/${props.test.doc.status}`) : null;
 }
-function BannerContent({ test, surface }) {
+function BannerContent({ test, surface, resultsVersion }) {
     const [selected, setSelected] = useState(null);
     const [people, setPeople] = useState(null);
     const transition = useTransition(test);
     const doc = test.doc;
     useEffect(()=>{
         let active = true;
-        setPeople(null);
+        // The id/status key resets the count; refreshes retain it while loading.
         if (surface.canReadResults && doc.status === 'running') {
             void createApi(surface.apiRoute).summary([
                 doc.id
             ]).then((result)=>{
-                const count = result.ok ? result.data?.[doc.id]?.exposures : undefined;
+                if (!result.ok) return;
+                const count = result.data?.[doc.id]?.exposures;
                 if (active) setPeople(typeof count === 'number' && Number.isFinite(count) ? count : null);
-            });
+            }).catch(()=>{});
         }
         return ()=>{
             active = false;
@@ -42,7 +43,8 @@ function BannerContent({ test, surface }) {
         doc.id,
         doc.status,
         surface.apiRoute,
-        surface.canReadResults
+        surface.canReadResults,
+        resultsVersion
     ]);
     const decision = doc.decision;
     const winner = actionGroupLabel(decision?.winnerArm ?? 'control', doc.arms.find((item)=>item.key === decision?.winnerArm)?.label);

package/dist/admin/surface/readiness/SaveStatus.js

@@ -17,7 +17,7 @@ export function SaveStatus({ test }) {
             setRetrying(false);
         }
     }
-    const message = test.saving === 'saving' ? C.saving : test.saving === 'saved' ? C.saved : test.saving === 'error' ? C.saveError : null;
+    const message = test.saving === 'saving' ? C.saving : test.saving === 'saved' ? C.saved : test.saving === 'error' && !test.stale ? C.saveError : null;
     return /*#__PURE__*/ _jsxs("div", {
         className: "xp-save-status",
         "aria-live": "polite",

package/dist/admin/surface/results/ResultsBody.d.ts

@@ -1,7 +1,10 @@
 import '../../styles.js';
 import type { DocId } from '../../../types/contracts.js';
 import type { SurfaceProps } from '../contracts.js';
-export declare function ResultsBody({ id, surface }: {
+type ResultsBodyProps = {
     id: DocId;
     surface: SurfaceProps;
-}): import("react").JSX.Element;
+    onRecomputed?: () => void;
+};
+export declare function ResultsBody({ id, surface, onRecomputed }: ResultsBodyProps): import("react").JSX.Element;
+export {};

package/dist/admin/surface/results/ResultsBody.js

@@ -18,14 +18,15 @@ import { armRows, collectingLine, dataQuality, defaultRound, guardrailChips, pow
 import { recommendation } from './recommendation.model.js';
 import { useResults } from './useResults.js';
 import { DecideDialog } from '../../actions/DecideDialog.js';
-export function ResultsBody({ id, surface }) {
+export function ResultsBody({ id, surface, onRecomputed }) {
     // A different test owns an independent selection and action lifecycle.
     return /*#__PURE__*/ _jsx(ResultsContent, {
         id: id,
-        surface: surface
+        surface: surface,
+        onRecomputed: onRecomputed
     }, `${surface.apiRoute}/${id}`);
 }
-function ResultsContent({ id, surface }) {
+function ResultsContent({ id, surface, onRecomputed }) {
     const results = useResults(id, surface);
     const { api, doc, round, phases, state, data } = results;
     const manage = surface.canManage && surface.canReadResults;
@@ -69,8 +70,10 @@ function ResultsContent({ id, surface }) {
         try {
             const result = await api.recompute(id);
             if (!mounted.current) return;
-            if (result.ok) results.reload();
-            else setActionError(result.message);
+            if (result.ok) {
+                results.reload();
+                onRecomputed?.();
+            } else setActionError(result.message);
         } finally{
             inFlight.current = false;
             if (mounted.current) setBusy(false);

package/dist/admin/surface/test/TestHeader.d.ts

@@ -1,4 +1,4 @@
 import type { SectionProps } from '../contracts.js';
-export declare function TestHeader({ test, surface, view }: SectionProps & {
+export declare function TestHeader({ test, surface, resultsVersion, view }: SectionProps & {
     view?: 'setup' | 'results';
 }): import("react").JSX.Element | null;

package/dist/admin/surface/test/TestHeader.js

@@ -6,7 +6,7 @@ import { readinessParts } from '../readiness/parts.js';
 import { statusPill } from '../../status.model.js';
 import { TEST_PAGE as C } from '../../copy/testPage.js';
 import { FieldErrors, reasonFor, save, TextEdit } from './fields.js';
-export function TestHeader({ test, surface, view = 'setup' }) {
+export function TestHeader({ test, surface, resultsVersion, view = 'setup' }) {
     const doc = test.doc;
     if (!doc) return null;
     const pill = statusPill({
@@ -62,7 +62,8 @@ export function TestHeader({ test, surface, view = 'setup' }) {
             }),
             /*#__PURE__*/ _jsx(readinessParts.Banner, {
                 test: test,
-                surface: surface
+                surface: surface,
+                resultsVersion: resultsVersion
             })
         ]
     });

package/dist/admin/surface/test/TestPage.js

@@ -43,9 +43,18 @@ export function TestPage({ id, surface }) {
             /*#__PURE__*/ _jsx(TestHeader, {
                 ...props
             }),
-            test.errors._section ? /*#__PURE__*/ _jsx("p", {
+            test.errors._section ? /*#__PURE__*/ _jsxs("div", {
                 role: "alert",
-                children: test.errors._section
+                children: [
+                    /*#__PURE__*/ _jsx("p", {
+                        children: test.errors._section
+                    }),
+                    test.stale ? /*#__PURE__*/ _jsx("button", {
+                        type: "button",
+                        onClick: ()=>void test.reload(),
+                        children: C.reload
+                    }) : null
+                ]
             }) : null,
             test.preflightError ? /*#__PURE__*/ _jsx("p", {
                 role: "alert",

package/dist/admin/surface/useTestDocument.d.ts

@@ -17,6 +17,7 @@ export declare function useTestDocument(id: DocId, { apiRoute }: {
     hasUnsaved: boolean;
     loadState: "loading" | "ready" | "forbidden" | "missing" | "error";
     saving: "idle" | "saving" | "saved" | "error";
+    stale: boolean;
     /** Path-specific validation errors; _section is the fallback for a section-wide refusal. */
     errors: Record<string, string>;
 };

package/dist/admin/surface/useTestDocument.js

@@ -1,6 +1,8 @@
 'use client';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { API_MESSAGES, refusalMessage } from '../copy/common.js';
+import { XP_IF_UPDATED_AT_HEADER } from '../../constants.js';
+import { TEST_PAGE } from '../copy/testPage.js';
 import { changedPatch, editablePatch, payloadFieldErrors } from './testDocument.model.js';
 // Saves outlive their mounted reader. Reopening the same document must wait for its queue.
 const drainingSaves = new Map();
@@ -12,6 +14,7 @@ const initialView = ()=>({
         hasUnsaved: false,
         loadState: 'loading',
         saving: 'idle',
+        stale: false,
         errors: {}
     });
 async function waitForDrain(draining, signal) {
@@ -49,7 +52,7 @@ function clearErrors(errors, patch) {
     return Object.fromEntries(Object.entries(errors).filter(([path])=>!Object.hasOwn(patch, path.split('.')[0])));
 }
 function stage(session, partial) {
-    if (!session.saved || session.reloading || session.view.loadState !== 'ready' || session.controller.signal.aborted) return;
+    if (!session.saved || session.view.stale || session.reloading || session.view.loadState !== 'ready' || session.controller.signal.aborted) return;
     const patch = editablePatch(session.saved.status, partial);
     if (!Object.keys(patch).length) return;
     session.pending = {
@@ -165,13 +168,14 @@ function stage(session, partial) {
         }
         // Capture each commit now, then diff against the latest server document when its turn arrives.
         function commit() {
-            if (!session.saved || session.reloading || controller.signal.aborted || !Object.keys(session.pending).length) return session.tail;
+            if (!session.saved || session.view.stale || session.reloading || controller.signal.aborted || !Object.keys(session.pending).length) return session.tail;
             const queued = session.pending;
             session.pending = {};
             session.queue.push(queued);
             session.view.saving = 'saving';
             session.publish();
             const step = async ()=>{
+                if (session.view.stale) return;
                 let saved = false;
                 let changed = false;
                 let failed = false;
@@ -180,17 +184,35 @@ function stage(session, partial) {
                     const patch = changedPatch(session.saved, queued);
                     changed = Object.keys(patch).length > 0;
                     if (changed) {
+                        const headers = {
+                            'Content-Type': 'application/json'
+                        };
+                        if (typeof session.saved.updatedAt === 'string') headers[XP_IF_UPDATED_AT_HEADER] = session.saved.updatedAt;
                         const response = await fetch(url, {
                             // Submitted saves belong to the queue, not the mounted reader's lifetime.
                             method: 'PATCH',
                             credentials: 'include',
-                            headers: {
-                                'Content-Type': 'application/json'
-                            },
+                            headers,
                             body: JSON.stringify(patch)
                         });
                         const body = await response.json().catch(()=>undefined);
-                        if (!response.ok) session.view.errors = {
+                        const errors = body?.errors;
+                        const staleError = response.status === 409 && Array.isArray(errors) ? errors.find((error)=>error?.code === 'stale-edit') : undefined;
+                        if (staleError) {
+                            session.view.stale = true;
+                            // Keep every typed value visible, but discard all queued sends until Reload.
+                            session.pending = [
+                                ...session.queue,
+                                session.pending
+                            ].reduce((draft, edit)=>({
+                                    ...draft,
+                                    ...edit
+                                }), {});
+                            session.queue = [];
+                            session.view.errors = {
+                                _section: staleError.message || TEST_PAGE.staleEdit
+                            };
+                        } else if (!response.ok) session.view.errors = {
                             ...session.view.errors,
                             ...payloadFieldErrors(body)
                         };
@@ -199,9 +221,12 @@ function stage(session, partial) {
                             const doc = body?.doc;
                             const readable = doc && doc.id != null && doc.status;
                             // A 2xx has applied even if its response body was lost. Preserve it while re-reading.
+                            // The old timestamp is no longer a valid baseline. Omit the header until a
+                            // readable PATCH or GET restores it, including when this read is aborted.
                             session.saved = readable ? doc : {
                                 ...session.saved,
-                                ...patch
+                                ...patch,
+                                updatedAt: undefined
                             };
                             saved = true;
                             // Keep readiness pending even while recovering an unreadable successful PATCH body.

package/dist/collections/experiments/config.js

@@ -7,7 +7,7 @@ import { flagControlParams } from './flagControlParams.js';
 import { lockHook } from './lockHook.js';
 import { deleteGuard, deleteGuardAfter } from './deleteGuard.js';
 import { checkArms } from './armInvariants.js';
-import { XpNotImplemented } from '../../errors.js';
+import { XpNotImplemented, XpRefusal } from '../../errors.js';
 const positiveInteger = (value)=>value != null && Number.isInteger(value) && value > 0 || 'Enter a positive whole number.';
 export function experimentsCollection(options) {
     const flagPoints = serializeFlagPoints(options);
@@ -91,6 +91,24 @@ export function experimentsCollection(options) {
             ],
             afterDelete: [
                 deleteGuardAfter
+            ],
+            afterError: [
+                ({ error })=>{
+                    // Payload preserves public Error status/message, but omits custom codes.
+                    if (error instanceof XpRefusal && error.code === 'stale-edit') {
+                        return {
+                            status: error.status,
+                            response: {
+                                errors: [
+                                    {
+                                        code: error.code,
+                                        message: error.message
+                                    }
+                                ]
+                            }
+                        };
+                    }
+                }
             ]
         },
         fields: [

package/dist/collections/experiments/lockHook.js

@@ -1,4 +1,7 @@
-import { XpLockedFieldError } from '../../errors.js';
+import { XpLockedFieldError, XpRefusal } from '../../errors.js';
+import { XP_IF_UPDATED_AT_HEADER } from '../../constants.js';
+import { txExecutor } from '../../db/executor.js';
+import { lockExperimentUpdatedAt } from '../../db/staleEdit.js';
 import { xpOptionsFromReq } from '../../options/fromReq.js';
 import { EDITABLE_BY_STATUS } from './editability.js';
 import { defaultArms } from './armInvariants.js';
@@ -60,6 +63,15 @@ const dates = new Set([
 const same = (a, b, path)=>JSON.stringify(normalize(a, path)) === JSON.stringify(normalize(b, path));
 export const lockHook = async ({ data, originalDoc, operation, req })=>{
     if (req.context.xpTransition === true) return data;
+    const baseline = req.headers.get(XP_IF_UPDATED_AT_HEADER);
+    if (operation === 'update' && baseline !== null) {
+        // originalDoc predates beforeChange; read again under a transaction row lock
+        // so a competing save observes the preceding save's committed timestamp.
+        const stored = await lockExperimentUpdatedAt(txExecutor(req), originalDoc.id);
+        if (stored === null || new Date(baseline).getTime() !== new Date(stored).getTime()) {
+            throw new XpRefusal('stale-edit', 'Someone else changed this test. Reload to see their changes.', undefined, 409);
+        }
+    }
     const admin = async ()=>{
         const options = xpOptionsFromReq(req);
         return await (options.access.admin ?? options.access.manage)({

package/dist/constants.d.ts

@@ -1,3 +1,4 @@
+export declare const DEFAULT_SEQUENTIAL_TUNING_PARAMETER = 5000;
 export declare const MAX_EVENTS_PER_BODY = 20;
 export declare const DEFAULT_MAX_BODY_BYTES = 8192;
 export declare const XP_COOKIE = "xp_id";
@@ -5,3 +6,4 @@ export declare const XP_HEADER = "x-xp-assignments";
 export declare const XP_PREVIEW_PARAM = "xp_preview";
 export declare const XP_MANIFEST_KEY_HEADER = "x-xp-manifest-key";
 export declare const XP_REQUEST_HEADER = "x-xp-request";
+export declare const XP_IF_UPDATED_AT_HEADER = "x-xp-if-updated-at";

package/dist/constants.js

@@ -1,3 +1,4 @@
+export const DEFAULT_SEQUENTIAL_TUNING_PARAMETER = 5000;
 export const MAX_EVENTS_PER_BODY = 20;
 export const DEFAULT_MAX_BODY_BYTES = 8192;
 export const XP_COOKIE = 'xp_id';
@@ -5,3 +6,4 @@ export const XP_HEADER = 'x-xp-assignments';
 export const XP_PREVIEW_PARAM = 'xp_preview';
 export const XP_MANIFEST_KEY_HEADER = 'x-xp-manifest-key';
 export const XP_REQUEST_HEADER = 'x-xp-request';
+export const XP_IF_UPDATED_AT_HEADER = 'x-xp-if-updated-at';

package/dist/db/staleEdit.d.ts

@@ -0,0 +1,6 @@
+import type { Executor } from './executor.js';
+import type { DocId } from '../types/contracts.js';
+/** Request transaction only: hold the row lock through the experiment write. */
+export declare function lockExperimentUpdatedAt(exec: Executor & {
+    schemaName?: string;
+}, id: DocId): Promise<Date | string | null>;

package/dist/db/staleEdit.js

@@ -0,0 +1,10 @@
+import { COLUMNS, TABLES } from './names.js';
+const quote = (name)=>`"${name.replaceAll('"', '""')}"`;
+/** Request transaction only: hold the row lock through the experiment write. */ export async function lockExperimentUpdatedAt(exec, id) {
+    const table = `${exec.schemaName ? `${quote(exec.schemaName)}.` : ''}${quote(TABLES.experiments)}`;
+    const columns = COLUMNS.experiments;
+    const result = await exec.query(`SELECT ${quote(columns.updatedAt)} AS "updatedAt" FROM ${table} WHERE ${quote(columns.id)} = $1 FOR NO KEY UPDATE`, [
+        id
+    ]);
+    return result.rows[0]?.updatedAt ?? null;
+}

package/dist/endpoints/events.js

@@ -1,3 +1,4 @@
+import { safeError } from '../log.js';
 import { NextRequest } from 'next/server.js';
 import { DEFAULT_MAX_BODY_BYTES } from '../constants.js';
 import { pooledExecutor } from '../db/executor.js';
@@ -89,9 +90,8 @@ export async function handleEvents(req, { options }) {
     } catch (error) {
         try {
             req.payload.logger.error({
-                err: error,
-                msg: 'Experiments: events endpoint failed'
-            });
+                err: safeError(error)
+            }, 'Experiments: events endpoint failed');
         } catch  {}
     }
     return accepted();

package/dist/endpoints/recompute.js

@@ -1,3 +1,4 @@
+import { safeError } from '../log.js';
 import { runResults } from '../server/runResults.js';
 import { readSnapshots, resultsError } from './results.js';
 import { routeId } from './routeId.js';
@@ -22,6 +23,7 @@ export async function handleRecompute(req, _ctx) {
             experimentId: docs[0].id,
             sweep: false
         });
+        if (result.failed) return resultsError(500, 'analysis-failed', 'Results could not be computed; this has been logged.');
         if (result.skipped || result.budgetExhausted) return resultsError(503, 'recompute-failed', 'Results could not be recomputed. Try again.');
         const latest = (await readSnapshots(req, [
             docs[0].id
@@ -36,7 +38,11 @@ export async function handleRecompute(req, _ctx) {
                 'Cache-Control': 'no-store'
             }
         });
-    } catch  {
+    } catch (error) {
+        req.payload.logger.error({
+            err: safeError(error),
+            experimentId: docs[0].id
+        }, 'Experiment recompute failed');
         return resultsError(503, 'recompute-failed', 'Results could not be recomputed. Try again.');
     }
 }

package/dist/exports/adminClient.d.ts

@@ -1,3 +1,4 @@
+export { XP_IF_UPDATED_AT_HEADER } from '../constants.js';
 export { LayerUsage } from '../admin/LayerUsage.js';
 export { MetricSourceSelect } from '../admin/MetricSourceSelect.js';
 export { ArmSelectField } from '../admin/armSelect/ArmSelectField.js';

package/dist/exports/adminClient.js

@@ -1,4 +1,5 @@
 'use client';
+export { XP_IF_UPDATED_AT_HEADER } from '../constants.js';
 export { LayerUsage } from '../admin/LayerUsage.js';
 export { MetricSourceSelect } from '../admin/MetricSourceSelect.js';
 export { ArmSelectField } from '../admin/armSelect/ArmSelectField.js';

package/dist/hooks/hostHook.js

@@ -1,9 +1,10 @@
+import { safeError } from '../log.js';
 /** Host saves must survive synchronous and asynchronous plugin hook failures. */ export function neverThrow(name, hook) {
     return async (args)=>{
         try {
             return await hook(args);
         } catch (error) {
-            console.error(`[payload-experiments] ${name} failed; the document was saved without it`, error);
+            console.error(`[payload-experiments] ${name} failed; the document was saved without it`, safeError(error));
             return args.doc;
         }
     };
@@ -13,7 +14,7 @@
         try {
             return await hook(args);
         } catch (error) {
-            console.error(`[payload-experiments] ${name} failed; the document was saved without it`, error);
+            console.error(`[payload-experiments] ${name} failed; the document was saved without it`, safeError(error));
             return args.data;
         }
     };

package/dist/labels/arms.d.ts

@@ -0,0 +1,7 @@
+export declare const ARM_LABELS: {
+    readonly control: "Original";
+    readonly variantA: "Variant A";
+    readonly variantB: "Variant B";
+    readonly variantC: "Variant C";
+    readonly holdout: "Holdout";
+};

package/dist/labels/arms.js

@@ -0,0 +1,7 @@
+export const ARM_LABELS = {
+    control: 'Original',
+    variantA: 'Variant A',
+    variantB: 'Variant B',
+    variantC: 'Variant C',
+    holdout: 'Holdout'
+};

package/dist/log.d.ts

@@ -0,0 +1,7 @@
+/** Deliberately construct a plain object: host serializers must never see the error. */
+export declare function safeError(err: unknown): {
+    name: string;
+    code?: string;
+    stack?: string;
+    message?: string;
+};

package/dist/log.js

@@ -0,0 +1,35 @@
+import { XpNoTransactionError, XpNotImplemented, XpRefusal } from './errors.js';
+import { ResultsBudgetError } from './db/pgExecutor.js';
+/** Deliberately construct a plain object: host serializers must never see the error. */ export function safeError(err) {
+    try {
+        if (!(err instanceof Error)) return {
+            name: typeof err
+        };
+        const name = err.name;
+        const result = {
+            name: typeof name === 'string' ? name : 'Error'
+        };
+        const code = 'code' in err ? err.code : undefined;
+        if (typeof code === 'string' && (/^[0-9A-Z]{5}$/.test(code) || err instanceof XpRefusal)) result.code = code;
+        const message = err.message;
+        const stack = err.stack;
+        // Remove the entire V8 header first: message lines can impersonate frames.
+        // Unknown stack formats fail closed. Never traverse cause or database fields.
+        if (typeof name === 'string' && typeof message === 'string' && typeof stack === 'string') {
+            const header = message ? `${name}: ${message}` : name;
+            const frames = stack.startsWith(`${header}\n`) ? stack.slice(header.length + 1).split('\n').filter((line)=>/^\s+at /.test(line)) : [];
+            if (frames.length) result.stack = frames.join('\n');
+        }
+        // XpRefusal includes stored slugs; XpLockedFieldError includes request keys
+        // and stored status. Neither class's message is safe to send to host logs.
+        if (err instanceof XpNoTransactionError || err instanceof XpNotImplemented || err instanceof ResultsBudgetError) {
+            if (typeof message === 'string') result.message = message;
+        }
+        return result;
+    } catch  {
+        // Even instanceof, property existence checks and getters can throw on hosts' errors.
+        return {
+            name: 'Error'
+        };
+    }
+}

package/dist/puck/copy.d.ts

@@ -1,3 +1,9 @@
+export declare const slotLabels: {
+    readonly control: "Original";
+    readonly variantA: "Variant A";
+    readonly variantB: "Variant B";
+    readonly variantC: "Variant C";
+};
 export declare const pickerCopy: {
     readonly label: "Experiment";
     readonly none: "No experiment";

package/dist/puck/copy.js

@@ -1,3 +1,10 @@
+import { ARM_LABELS } from '../labels/arms.js';
+export const slotLabels = {
+    control: ARM_LABELS.control,
+    variantA: ARM_LABELS.variantA,
+    variantB: ARM_LABELS.variantB,
+    variantC: ARM_LABELS.variantC
+};
 export const pickerCopy = {
     label: 'Experiment',
     none: 'No experiment',

package/dist/puck/editor/ExperimentSlotEditor.js

@@ -156,6 +156,8 @@ function EditorRender(props) {
                                     experiment ? /*#__PURE__*/ _jsx("a", {
                                         className: "xp-slot-button xp-slot-button-primary",
                                         href: `/admin/experiments/${encodeURIComponent(String(experimentId))}${experiment.status === 'draft' ? '' : '/results'}`,
+                                        target: "_blank",
+                                        rel: "noopener noreferrer",
                                         children: experiment.status === 'draft' ? editorCopy.setup : editorCopy.viewResults
                                     }) : null
                                 ]

package/dist/puck/slotConfig.js

@@ -1,19 +1,24 @@
 import { createExperimentSlotField } from './experimentSlotField.js';
-import { pickerCopy } from './copy.js';
+import { pickerCopy, slotLabels } from './copy.js';
 export const experimentSlotLabel = pickerCopy.label;
 export const experimentSlotFields = {
     experiment: createExperimentSlotField(),
-    control: {
-        type: 'slot'
-    },
-    variantA: {
-        type: 'slot'
+    // Puck 0.24's defaultSlots prepends each slot, reversing declaration order in the outline.
+    variantC: {
+        type: 'slot',
+        label: slotLabels.variantC
     },
     variantB: {
-        type: 'slot'
+        type: 'slot',
+        label: slotLabels.variantB
     },
-    variantC: {
-        type: 'slot'
+    variantA: {
+        type: 'slot',
+        label: slotLabels.variantA
+    },
+    control: {
+        type: 'slot',
+        label: slotLabels.control
     }
 };
 export const experimentSlotDefaultProps = {

package/dist/results/analyse.d.ts

@@ -33,7 +33,7 @@ export interface AnalysisPhase {
     analysis: {
         method: 'sequential' | 'bayesian';
         alpha?: number;
-        sequentialTuningParameter: number;
+        sequentialTuningParameter?: number | null;
         cuped: 'auto' | 'off';
         cupedLookbackDays?: number;
         minExposuresPerArm: number;

package/dist/results/analyse.js

@@ -1,4 +1,5 @@
 import { DEFAULT_GAUSSIAN_PRIOR, bonferroniAlpha, capValues, createThetaAdjustedStatistics, effectBayesianABTest, sequentialOneSidedTreatmentGreaterTTest, sequentialOneSidedTreatmentLesserTTest, sequentialTwoSidedTTest, statisticMean, statisticVariance } from '@delmaredigital/experiments-stats';
+import { DEFAULT_SEQUENTIAL_TUNING_PARAMETER } from '../constants.js';
 import { timestampMs } from './aggregate.js';
 import { outcomeStatistic } from './cuped.js';
 import { guardrailStatus } from './guardrails.js';
@@ -17,6 +18,9 @@ const severity = {
  */ export function analysePhase(input) {
     const { phase, units } = input;
     const { analysis } = phase;
+    // Start freezes this optional collection field as-is. Match the stats engine's
+    // default and record the effective value in every snapshot, including n = 0.
+    const sequentialTuningParameter = analysis.sequentialTuningParameter ?? DEFAULT_SEQUENTIAL_TUNING_PARAMETER;
     const alpha = analysis.alpha ?? 0.05;
     const prior = analysis.prior ?? DEFAULT_GAUSSIAN_PRIOR;
     const bayesian = analysis.bayesian ?? {
@@ -73,7 +77,7 @@ const severity = {
         capped: {}
     };
     const params = {
-        sequentialTuningParameter: analysis.sequentialTuningParameter,
+        sequentialTuningParameter,
         prior: {
             ...prior
         },
@@ -158,7 +162,7 @@ const severity = {
                 metric.cupedApplied ||= a.type === 'regressionAdjusted' && b.type === 'regressionAdjusted';
                 const config = {
                     alpha,
-                    sequentialTuningParameter: analysis.sequentialTuningParameter
+                    sequentialTuningParameter
                 };
                 const inverse = definition.direction === 'decrease';
                 let comparison;
@@ -342,7 +346,7 @@ const severity = {
             alpha: alphaAdjusted,
             method: analysis.method,
             prior,
-            sequentialTuningParameter: analysis.sequentialTuningParameter
+            sequentialTuningParameter
         });
         verdict = computeVerdict({
             ...verdictInput,

package/dist/results/verdict.d.ts

@@ -78,6 +78,8 @@ interface VerdictInputFields {
     originalLabel: string;
     controlArm: string;
 }
+/** Resolve a stored group label without exposing an internal key in verdict copy. */
+export declare function verdictGroupLabel(key: string, label?: string): string;
 /** Apply spec §8.5 in order to already-computed results; no inference is performed here. */
 export declare function computeVerdict(input: VerdictInput): Snapshot['verdict'];
 export {};

package/dist/results/verdict.js

@@ -1,3 +1,4 @@
+import { ARM_LABELS } from '../labels/arms.js';
 function percent(value) {
     if (value === null) return '…';
     const rounded = Math.round(value * 100);
@@ -19,6 +20,9 @@ function chance(value) {
     if (value === undefined) return '';
     return value >= 0.995 ? ' (more than 99%)' : ` (${Math.floor(value * 100)}%)`;
 }
+/** Resolve a stored group label without exposing an internal key in verdict copy. */ export function verdictGroupLabel(key, label = '') {
+    return label.trim() || (Object.hasOwn(ARM_LABELS, key) ? ARM_LABELS[key] : 'This group');
+}
 /** Apply spec §8.5 in order to already-computed results; no inference is performed here. */ export function computeVerdict(input) {
     const rollout = input.phaseKind === 'rollout';
     const make = (row, code, finding, action, detail, recommendedArm, line, worstArm)=>({
@@ -60,7 +64,20 @@ function chance(value) {
     }
     const failing = input.guardrails.find((item)=>item.status === 'failing');
     if (failing) return make(3, 'guardrail-failing', `Stop: ${failing.worstArmLabel} harms ${failing.name}.`, null, 'An outcome that must stay safe has become worse.', input.controlArm, undefined, failing.worstArm);
-    if (collecting) return make(4, 'collecting', input.status === 'stopped' ? 'Stopped before enough data was collected.' : `Collecting data: ${minimum} of ${input.exposures.minExposuresPerArm} people, ${minimumConverters} of ${input.primary.minSampleSize} conversions.`, null, 'More people or conversions are needed before drawing a conclusion.', null);
+    if (collecting) {
+        const smallest = compared.find((item)=>item.n === minimum);
+        const fewest = converters.find((item)=>item.converters === minimumConverters);
+        const groupLabel = (group)=>{
+            if (!group || group.kind === 'control') return 'Original';
+            const label = input.exposures.perArm.find((item)=>item.arm === group.arm)?.label ?? input.primary.comparisons.find((item)=>item.arm === group.arm)?.label;
+            return verdictGroupLabel(group.arm, label);
+        };
+        const detail = [
+            minimum < input.exposures.minExposuresPerArm ? `Smallest group so far: ${groupLabel(smallest)}, ${minimum} of the ${input.exposures.minExposuresPerArm} people it needs.` : '',
+            minimumConverters < input.primary.minSampleSize ? `Fewest conversions so far: ${groupLabel(fewest)}, ${minimumConverters} of the ${input.primary.minSampleSize} needed.` : ''
+        ].filter(Boolean).join(' ') || 'More people or conversions are needed before drawing a conclusion.';
+        return make(4, 'collecting', input.status === 'stopped' ? 'Stopped before enough data was collected.' : 'Collecting data.', null, input.status === 'stopped' ? 'More people or conversions are needed before drawing a conclusion.' : detail, null);
+    }
     const variantKeys = new Set(compared.filter((item)=>item.kind === 'variant').map((item)=>item.arm));
     const variants = input.primary.comparisons.filter((item)=>variantKeys.has(item.arm));
     const better = variants.filter((item)=>item.significant === 'better');

package/dist/server/linkIdentity.js

@@ -1,3 +1,4 @@
+import { safeError } from '../log.js';
 import { NextRequest } from 'next/server.js';
 import { insertIdentityOnOwnConnection } from '../db/identities.js';
 import { readUnitCookie } from '../runtime/cookie.js';
@@ -26,9 +27,8 @@ export async function linkIdentity(serverRuntime, opts) {
     } catch (error) {
         try {
             payload?.logger.error({
-                err: error,
-                msg: 'Experiments: linkIdentity failed'
-            });
+                err: safeError(error)
+            }, 'Experiments: linkIdentity failed');
         } catch  {}
     }
 }

package/dist/server/recordContentChange.js

@@ -1,3 +1,4 @@
+import { safeError } from '../log.js';
 import { isDeepStrictEqual } from 'node:util';
 import { appendContentChange, contentChangeSavepoint, previousPublishedContent, runningContentExperiment } from '../db/appends.js';
 import { txExecutor } from '../db/executor.js';
@@ -75,7 +76,7 @@ const baselineKey = (collection, id)=>`${collection}:${id}`;
     try {
         await auditContentChange(args);
     } catch (error) {
-        console.error('[payload-experiments] contentChanges failed; the document was saved without it', error);
+        console.error('[payload-experiments] contentChanges failed; the document was saved without it', safeError(error));
     }
 }
 async function auditContentChange({ doc, previousDoc, req, collection }) {

package/dist/server/recordExposures.js

@@ -1,3 +1,4 @@
+import { safeError } from '../log.js';
 import { pooledExecutor } from '../db/executor.js';
 import { insertEvents } from '../db/events.js';
 import { exposureDimensions } from '../events/dimensions.js';
@@ -48,9 +49,8 @@ export async function recordExposures(serverRuntime, rendered, ctx) {
     } catch (error) {
         try {
             payload?.logger.error({
-                err: error,
-                msg: 'Experiments: recordExposures failed'
-            });
+                err: safeError(error)
+            }, 'Experiments: recordExposures failed');
         } catch  {}
     }
 }

package/dist/server/runResults.d.ts

@@ -13,6 +13,7 @@ export declare function runResults(payload: Payload, { budgetMs, experimentId, s
 }): Promise<{
     ran: number;
     skipped: number;
+    failed: number;
     swept: number;
     processedIds: DocId[];
     budgetExhausted: boolean;

package/dist/server/runResults.js

@@ -1,3 +1,4 @@
+import { safeError } from '../log.js';
 import { resultsCandidates, resultsExecutor, writeSnapshots } from '../db/snapshots.js';
 import { sweepEvents } from '../db/sweep.js';
 import { armMismatchCount, identityRows, metricEventRows, phaseExposureRows, rolloutExposureRows } from '../db/results.js';
@@ -219,6 +220,7 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
     const summary = {
         ran: 0,
         skipped: 0,
+        failed: 0,
         swept: 0,
         processedIds: [],
         budgetExhausted: false,
@@ -243,9 +245,10 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
         });
     } catch (error) {
         summary.skipped++;
+        if (!(error instanceof ResultsBudgetError)) summary.failed++;
         summary.budgetExhausted = error instanceof ResultsBudgetError;
         payload.logger.error({
-            err: error,
+            err: safeError(error),
             experimentId
         }, 'Experiment scheduling failed');
     }
@@ -277,9 +280,10 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
             if (summary.processedIds.length < 100) summary.processedIds.push(id);
         } catch (error) {
             summary.skipped++;
+            if (!(error instanceof ResultsBudgetError)) summary.failed++;
             summary.budgetExhausted ||= error instanceof ResultsBudgetError;
             payload.logger.error({
-                err: error,
+                err: safeError(error),
                 experimentId: id
             }, 'Experiment results failed');
         }
@@ -296,9 +300,10 @@ export async function runResults(payload, { budgetMs = 20_000, experimentId, swe
                 logger: payload.logger
             });
         } catch (error) {
+            if (!(error instanceof ResultsBudgetError)) summary.failed++;
             summary.budgetExhausted ||= error instanceof ResultsBudgetError;
             payload.logger.error({
-                err: error
+                err: safeError(error)
             }, 'Experiment retention sweep failed');
         }
     }

package/dist/server/trackConversion.js

@@ -1,3 +1,4 @@
+import { safeError } from '../log.js';
 import { NextRequest } from 'next/server.js';
 import { pooledExecutor } from '../db/executor.js';
 import { insertEvents } from '../db/events.js';
@@ -39,9 +40,8 @@ export async function trackConversion(serverRuntime, event) {
             } catch (error) {
                 try {
                     payload.logger.error({
-                        err: error,
-                        msg: 'Experiments: trackConversion getUser failed'
-                    });
+                        err: safeError(error)
+                    }, 'Experiments: trackConversion getUser failed');
                 } catch  {}
             }
         }
@@ -61,9 +61,8 @@ export async function trackConversion(serverRuntime, event) {
     } catch (error) {
         try {
             payload?.logger.error({
-                err: error,
-                msg: 'Experiments: trackConversion failed'
-            });
+                err: safeError(error)
+            }, 'Experiments: trackConversion failed');
         } catch  {}
     }
 }

package/dist/transitions/deleteExperiment.js

@@ -1,3 +1,4 @@
+import { safeError } from '../log.js';
 import { txExecutor } from '../db/executor.js';
 import { deleteExperimentSnapshots, serializeDelete } from '../db/delete.js';
 import { deleteExperimentEvents } from '../db/events.js';
@@ -45,7 +46,7 @@ import { readExperiment, refuse } from './start.js';
         } catch (error) {
             req.payload.logger.error({
                 experimentId,
-                err: error
+                err: safeError(error)
             }, 'Experiment cascade failed; aborting delete');
             throw error;
         }

package/dist/types/endpoints.d.ts

@@ -4,7 +4,7 @@ import type { ReadinessCode } from '../transitions/checkStart.js';
 export type { ReadinessCode } from '../transitions/checkStart.js';
 import type { Snapshot, VerdictCode } from './snapshot.js';
 export type ArmIssueCode = 'weights-total' | 'control-count' | 'control-first' | 'holdout-last' | 'holdout-count' | 'variant-count' | 'duplicate-key' | 'duplicate-slot' | 'slot-required' | 'invalid-key';
-export type RefusalCode = ArmIssueCode | 'not-found' | 'no-planned-duration' | 'no-primary-metric' | 'no-placements' | 'empty-slot' | 'page-no-targets' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'layer-full' | 'layer-unit-mismatch' | 'unknown-metric-source' | 'unit-source-mismatch' | 'no-reach-per-day' | 'invalid-status' | 'stale-draft' | 'commit-unverified' | 'allocation-lower' | 'confirmation-required' | 'invalid-winner' | 'slices-taken' | 'locked-placement' | 'not-implemented' | 'forbidden' | 'unauthenticated' | 'body-too-large' | 'invalid-body' | 'too-many-ids' | 'invalid-phase' | 'invalid-ids' | 'recompute-failed' | 'undeclared-targeting-key' | 'invalid-targeting-rule' | 'duplicate-metric';
+export type RefusalCode = ArmIssueCode | 'not-found' | 'no-planned-duration' | 'no-primary-metric' | 'no-placements' | 'empty-slot' | 'page-no-targets' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'layer-full' | 'layer-unit-mismatch' | 'unknown-metric-source' | 'unit-source-mismatch' | 'no-reach-per-day' | 'invalid-status' | 'stale-draft' | 'stale-edit' | 'commit-unverified' | 'allocation-lower' | 'confirmation-required' | 'invalid-winner' | 'slices-taken' | 'locked-placement' | 'not-implemented' | 'forbidden' | 'unauthenticated' | 'body-too-large' | 'invalid-body' | 'too-many-ids' | 'invalid-phase' | 'invalid-ids' | 'recompute-failed' | 'analysis-failed' | 'undeclared-targeting-key' | 'invalid-targeting-rule' | 'duplicate-metric';
 export type ErrorEnvelope = {
     errors: Array<{
         code: RefusalCode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delmaredigital/payload-experiments",
-  "version": "0.2.0-rc.5",
+  "version": "0.2.0-rc.7",
   "description": "No-code A/B testing for Payload CMS and Next.js: block, page and flag experiments with holdouts, layers, exposure logging and honest statistics inside the admin — no vendor",
   "type": "module",
   "license": "MIT",