@delmaredigital/payload-experiments 0.2.0-rc.6 → 0.3.0-rc.1

package/dist/collections/experiments/config.js

@@ -2,12 +2,14 @@ import * as paths from '../../admin/paths.js';
 import { managedAccess } from '../access.js';
 import { serializeAttributeKeys, serializeFlagPoints } from '../serialize.js';
 import { TARGETING_OPS, isOpValid } from '../../targeting/ops.js';
+import { readListValue } from '../../targeting/values.js';
 import { createDefaults } from './createDefaults.js';
 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 targetingValue = (rule)=>rule.op === 'in' || rule.op === 'nin' ? readListValue(rule.value) : rule.value;
 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 +93,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: [
@@ -206,6 +226,21 @@ export function experimentsCollection(options) {
                             {
                                 name: 'targeting',
                                 type: 'array',
+                                validate: (value, { data, previousValue })=>{
+                                    // Payload 3.90.2 beforeChange/promise.js passes merged document data
+                                    // and this document's stored array as previousValue, including in bulk updates.
+                                    const status = data?.status ?? 'draft';
+                                    if (data?.kind === 'block' && (status === 'draft' || status === 'stopped')) {
+                                        for (const rule of value ?? []){
+                                            if (rule.attribute !== 'path') continue;
+                                            const previous = rule.id == null ? undefined : previousValue?.find((stored)=>stored.id != null && String(stored.id) === String(rule.id));
+                                            if (!previous || previous.attribute !== rule.attribute || previous.op !== rule.op || JSON.stringify(targetingValue(previous)) !== JSON.stringify(targetingValue(rule))) {
+                                                return 'Page block tests run on their page; remove the page-path rule.';
+                                            }
+                                        }
+                                    }
+                                    return true;
+                                },
                                 fields: [
                                     {
                                         name: 'attribute',
@@ -459,6 +494,14 @@ export function experimentsCollection(options) {
                     {
                         name: 'holdoutReleasedAt',
                         type: 'date'
+                    },
+                    {
+                        name: 'pagesReleasedAt',
+                        type: 'date'
+                    },
+                    {
+                        name: 'pagesReleasedBy',
+                        type: 'text'
                     }
                 ]
             }

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';
@@ -9,6 +12,7 @@ const relationships = new Set([
     'metrics.secondary',
     'metrics.guardrails',
     'decision.decidedBy',
+    'decision.pagesReleasedBy',
     'decision.snapshotId'
 ]);
 const dates = new Set([
@@ -17,7 +21,8 @@ const dates = new Set([
     'decidedAt',
     'archivedAt',
     'decision.discardedAt',
-    'decision.holdoutReleasedAt'
+    'decision.holdoutReleasedAt',
+    'decision.pagesReleasedAt'
 ]);
 /** Schema-aware: JSON retains its own ids and date-like strings. */ function normalize(value, path, json = false) {
     json ||= [
@@ -60,6 +65,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/collections/identities.js

@@ -19,12 +19,17 @@ export function identitiesCollection(options) {
             {
                 name: 'userId',
                 type: 'text',
-                required: true
+                required: true,
+                index: true
             },
             {
                 name: 'linkedAt',
                 type: 'date',
                 required: true
+            },
+            {
+                name: 'verifiedAt',
+                type: 'date'
             }
         ]
     };

package/dist/collections/metrics.js

@@ -2,6 +2,7 @@ import { XP_METRIC_SOURCE_SELECT } from '../admin/paths.js';
 import { managedAccess } from './access.js';
 import { serializeMetricSources } from './serialize.js';
 import { validateCappingType, validateCappingValue } from './metricValidation.js';
+import { metricChangeGuard, metricDeleteGuard } from './metricsGuards.js';
 export function metricsCollection(options) {
     const sources = serializeMetricSources(options);
     return {
@@ -20,6 +21,12 @@ export function metricsCollection(options) {
         },
         access: managedAccess(options),
         hooks: {
+            beforeDelete: [
+                metricDeleteGuard
+            ],
+            beforeChange: [
+                metricChangeGuard
+            ],
             beforeValidate: [
                 ({ data, originalDoc })=>{
                     if (!data) return data;

package/dist/collections/metricsGuards.d.ts

@@ -0,0 +1,9 @@
+import type { CollectionBeforeChangeHook, CollectionBeforeDeleteHook } from 'payload';
+/** Payload's REST formatter preserves public plugin errors and their 4xx status. */
+export declare class XpGoalInUseError extends Error {
+    name: string;
+    readonly status = 400;
+    readonly isPublic = true;
+}
+export declare const metricDeleteGuard: CollectionBeforeDeleteHook;
+export declare const metricChangeGuard: CollectionBeforeChangeHook;

package/dist/collections/metricsGuards.js

@@ -0,0 +1,33 @@
+import { pooledExecutor, txExecutor } from '../db/executor.js';
+import { findMetricUsage, lockMetricRow } from '../db/metricUsage.js';
+/** Payload's REST formatter preserves public plugin errors and their 4xx status. */ export class XpGoalInUseError extends Error {
+    name = 'XpGoalInUseError';
+    status = 400;
+    isPublic = true;
+}
+async function executor(req, id, mode) {
+    const transactionID = await req.transactionID;
+    if (transactionID != null) {
+        const exec = txExecutor(req);
+        await lockMetricRow(exec, id, mode);
+        return exec;
+    }
+    // With no transaction a pooled row lock would expire before the usage read;
+    // retain the existing best-effort usage check without taking a lock.
+    return pooledExecutor(req.payload);
+}
+export const metricDeleteGuard = async ({ req, id })=>{
+    const usage = await findMetricUsage(await executor(req, id, 'delete'), id);
+    if (usage) throw new XpGoalInUseError(`This goal is used by the test "${usage.name}". Remove it from the test first.`);
+};
+export const metricChangeGuard = async ({ req, data, originalDoc, operation })=>{
+    if (operation !== 'update') return data;
+    const changed = [
+        'slug',
+        'source'
+    ].some((field)=>field in data && data[field] !== originalDoc[field]);
+    if (changed && await findMetricUsage(await executor(req, originalDoc.id, 'change'), originalDoc.id)) {
+        throw new XpGoalInUseError("This goal is used by a test, so its short name and what it measures can't change. Create a new goal instead.");
+    }
+    return data;
+};

package/dist/constants.d.ts

@@ -6,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

@@ -6,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/contentDone.d.ts

@@ -0,0 +1,4 @@
+import type { ContentReport } from './types/endpoints.js';
+/** Every recorded content entry is updated or handled by the manager. A present but empty report is done:
+ * page tests and flag tests without a host callback record no entries. An absent report is not done. */
+export declare function contentDone(report: ContentReport | null | undefined): boolean;

package/dist/contentDone.js

@@ -0,0 +1,5 @@
+/** Every recorded content entry is updated or handled by the manager. A present but empty report is done:
+ * page tests and flag tests without a host callback record no entries. An absent report is not done. */ export function contentDone(report) {
+    const docs = Array.isArray(report) ? report : report?.docs;
+    return Array.isArray(docs) && docs.every((doc)=>doc?.ok === true || Boolean(doc?.dismissedAt));
+}

package/dist/db/identities.d.ts

@@ -1,11 +1,12 @@
 import type { Payload } from 'payload';
 import { type Executor } from './executor.js';
-export declare function insertIdentity(exec: Executor, { anonymousId, userId }: {
+export type IdentityWriteOutcome = 'linked' | 'verified' | 'skipped';
+type IdentityInput = {
     anonymousId: string;
     userId: string;
-}): Promise<void>;
-/** §5.6 / §7.8: privileged insert, isolated from the caller's sign-in transaction. */
-export declare function insertIdentityOnOwnConnection(payload: Payload, identity: {
-    anonymousId: string;
-    userId: string;
-}): Promise<void>;
+    verified: boolean;
+};
+export declare function insertIdentity(exec: Executor, { anonymousId, userId, verified }: IdentityInput): Promise<IdentityWriteOutcome>;
+/** §5.6 / §7.8: privileged insert/upgrade, isolated from the caller's sign-in transaction. */
+export declare function insertIdentityOnOwnConnection(payload: Payload, identity: IdentityInput): Promise<IdentityWriteOutcome>;
+export {};

package/dist/db/identities.js

@@ -1,26 +1,29 @@
 import { ownConnection } from './executor.js';
 import { COLUMNS, TABLES } from './names.js';
 const quote = (name)=>`"${name.replaceAll('"', '""')}"`;
-export async function insertIdentity(exec, { anonymousId, userId }) {
+export async function insertIdentity(exec, { anonymousId, userId, verified }) {
     const schema = exec.schemaName;
     const table = `${schema ? `${quote(schema)}.` : ''}${quote(TABLES.identities)}`;
     const c = COLUMNS.identities;
-    await exec.query(`INSERT INTO ${table} (${[
+    const { rows } = await exec.query(`INSERT INTO ${table} AS identity (${[
         c.anonymousId,
         c.userId,
         c.linkedAt,
+        c.verifiedAt,
         c.createdAt,
         c.updatedAt
-    ].map(quote).join(', ')}) VALUES ($1, $2, now(), now(), now()) ON CONFLICT (${quote(c.anonymousId)}) DO NOTHING`, [
+    ].map(quote).join(', ')}) VALUES ($1, $2, now(), CASE WHEN $3 THEN now() END, now(), now()) ON CONFLICT (${quote(c.anonymousId)}) DO UPDATE SET ${quote(c.verifiedAt)} = now(), ${quote(c.updatedAt)} = now() WHERE identity.${quote(c.userId)} = EXCLUDED.${quote(c.userId)} AND identity.${quote(c.verifiedAt)} IS NULL AND $3 RETURNING (xmax = 0) AS inserted`, [
         anonymousId,
-        userId
+        userId,
+        verified
     ]);
+    return rows.length === 0 ? 'skipped' : rows[0].inserted ? 'linked' : 'verified';
 }
-/** §5.6 / §7.8: privileged insert, isolated from the caller's sign-in transaction. */ export async function insertIdentityOnOwnConnection(payload, identity) {
+/** §5.6 / §7.8: privileged insert/upgrade, isolated from the caller's sign-in transaction. */ export async function insertIdentityOnOwnConnection(payload, identity) {
     const db = payload.db;
     const exec = await ownConnection(db.pool);
     try {
-        await insertIdentity(Object.assign(exec, {
+        return await insertIdentity(Object.assign(exec, {
             schemaName: db.schemaName
         }), identity);
     } finally{

package/dist/db/metricUsage.d.ts

@@ -0,0 +1,19 @@
+import type { Executor } from './executor.js';
+import type { DocId } from '../types/contracts.js';
+/** Request transaction only: serialize the guard with FK checks and freezes. */
+export declare function lockMetricRow(exec: Executor, id: DocId, mode: 'delete' | 'change'): Promise<void>;
+/** Transition transaction only, after advisory locks. SQL orders by the native
+ * id type so overlapping freezes always acquire row locks in the same order.
+ * Return the locked identities so callers can reject a change that committed
+ * after preflight. Missing rows mean a goal was deleted; never freeze that copy.
+ * txExecutor throws if the request no longer has a transaction session.
+ */
+export declare function lockMetricsForFreeze(exec: Executor, ids: DocId[]): Promise<Array<{
+    id: DocId;
+    slug: string;
+    source: string;
+}> | null>;
+/** Live selections cover drafts; frozen definitions keep historical goals in use. */
+export declare function findMetricUsage(exec: Executor, id: DocId): Promise<{
+    name: string;
+} | null>;

package/dist/db/metricUsage.js

@@ -0,0 +1,54 @@
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+/** Request transaction only: serialize the guard with FK checks and freezes. */ export async function lockMetricRow(exec, id, mode) {
+    const lock = mode === 'delete' ? 'FOR UPDATE' : 'FOR NO KEY UPDATE';
+    await exec.query(`SELECT 1 FROM ${qualifiedTable(exec, TABLES.metrics)} WHERE ${q(COLUMNS.metrics.id)} = $1 ${lock}`, [
+        id
+    ]);
+}
+/** Transition transaction only, after advisory locks. SQL orders by the native
+ * id type so overlapping freezes always acquire row locks in the same order.
+ * Return the locked identities so callers can reject a change that committed
+ * after preflight. Missing rows mean a goal was deleted; never freeze that copy.
+ * txExecutor throws if the request no longer has a transaction session.
+ */ export async function lockMetricsForFreeze(exec, ids) {
+    // Deduplicate for the row-count check; SQL ORDER BY sets the lock order.
+    const sorted = [
+        ...new Map(ids.map((id)=>[
+                String(id),
+                id
+            ])).values()
+    ].sort((a, b)=>typeof a === 'number' && typeof b === 'number' ? a - b : String(a).localeCompare(String(b)));
+    const m = COLUMNS.metrics, id = q(m.id);
+    const result = await exec.query(`SELECT ${id}, ${q(m.slug)}, ${q(m.source)} FROM ${qualifiedTable(exec, TABLES.metrics)} WHERE ${id} = ANY($1) ORDER BY ${id} FOR SHARE`, [
+        sorted
+    ]);
+    return result.rows.length === sorted.length ? result.rows : null;
+}
+/** Live selections cover drafts; frozen definitions keep historical goals in use. */ export async function findMetricUsage(exec, id) {
+    const e = COLUMNS.experiments, p = COLUMNS.phases, r = COLUMNS.experimentsRels;
+    const result = await exec.query(`
+    SELECT COALESCE(usage.name, 'Deleted test') AS name FROM (
+      SELECT e.${q(e.name)} AS name, e.${q(e.status)} AS status
+      FROM ${qualifiedTable(exec, TABLES.phases)} p
+      LEFT JOIN ${qualifiedTable(exec, TABLES.experiments)} e ON e.${q(e.id)} = p.${q(p.experimentId)}
+      WHERE jsonb_typeof(p.${q(p.metricDefinitions)}) = 'array' AND EXISTS (
+        SELECT 1 FROM jsonb_array_elements(p.${q(p.metricDefinitions)}) definition
+        WHERE definition->>'metricId' = $1::text
+      )
+      UNION ALL
+      SELECT e.${q(e.name)} AS name, e.${q(e.status)} AS status
+      FROM ${qualifiedTable(exec, TABLES.experiments)} e
+      WHERE e.${q(e.metricsPrimaryId)}::text = $1::text OR EXISTS (
+        SELECT 1 FROM ${qualifiedTable(exec, TABLES.experimentsRels)} r
+        WHERE r.${q(r.parentId)} = e.${q(e.id)}
+          AND r.${q(r.path)} IN ('metrics.secondary', 'metrics.guardrails')
+          AND r.${q(r.xpMetricsId)}::text = $1::text
+      )
+    ) usage
+    ORDER BY CASE WHEN usage.status IN ('running', 'decided') THEN 0 ELSE 1 END, usage.name
+    LIMIT 1`, [
+        String(id)
+    ]);
+    return result.rows[0] ?? null;
+}

package/dist/db/names.d.ts

@@ -83,6 +83,8 @@ export declare const COLUMNS: {
         readonly decisionDiscardedAt: "decision_discarded_at";
         readonly decisionContentReport: "decision_content_report";
         readonly decisionHoldoutReleasedAt: "decision_holdout_released_at";
+        readonly decisionPagesReleasedAt: "decision_pages_released_at";
+        readonly decisionPagesReleasedBy: "decision_pages_released_by";
         readonly updatedAt: "updated_at";
         readonly createdAt: "created_at";
     };
@@ -151,6 +153,8 @@ export declare const COLUMNS: {
         readonly versionDecisionDiscardedAt: "version_decision_discarded_at";
         readonly versionDecisionContentReport: "version_decision_content_report";
         readonly versionDecisionHoldoutReleasedAt: "version_decision_holdout_released_at";
+        readonly versionDecisionPagesReleasedAt: "version_decision_pages_released_at";
+        readonly versionDecisionPagesReleasedBy: "version_decision_pages_released_by";
         readonly versionUpdatedAt: "version_updated_at";
         readonly versionCreatedAt: "version_created_at";
         readonly createdAt: "created_at";
@@ -227,6 +231,7 @@ export declare const COLUMNS: {
         readonly anonymousId: "anonymous_id";
         readonly userId: "user_id";
         readonly linkedAt: "linked_at";
+        readonly verifiedAt: "verified_at";
         readonly updatedAt: "updated_at";
         readonly createdAt: "created_at";
     };

package/dist/db/names.js

@@ -82,6 +82,8 @@ export const COLUMNS = {
         decisionDiscardedAt: 'decision_discarded_at',
         decisionContentReport: 'decision_content_report',
         decisionHoldoutReleasedAt: 'decision_holdout_released_at',
+        decisionPagesReleasedAt: 'decision_pages_released_at',
+        decisionPagesReleasedBy: 'decision_pages_released_by',
         updatedAt: 'updated_at',
         createdAt: 'created_at'
     },
@@ -150,6 +152,8 @@ export const COLUMNS = {
         versionDecisionDiscardedAt: 'version_decision_discarded_at',
         versionDecisionContentReport: 'version_decision_content_report',
         versionDecisionHoldoutReleasedAt: 'version_decision_holdout_released_at',
+        versionDecisionPagesReleasedAt: 'version_decision_pages_released_at',
+        versionDecisionPagesReleasedBy: 'version_decision_pages_released_by',
         versionUpdatedAt: 'version_updated_at',
         versionCreatedAt: 'version_created_at',
         createdAt: 'created_at',
@@ -226,6 +230,7 @@ export const COLUMNS = {
         anonymousId: 'anonymous_id',
         userId: 'user_id',
         linkedAt: 'linked_at',
+        verifiedAt: 'verified_at',
         updatedAt: 'updated_at',
         createdAt: 'created_at'
     },

package/dist/db/publishedContent.d.ts

@@ -0,0 +1,10 @@
+import type { PayloadRequest } from 'payload';
+import type { DocId } from '../types/contracts.js';
+/** §7.8 make-content: the published main row, so Payload's draft baseline never fills a field (KI-1). */
+export declare function publishedContent(req: PayloadRequest, collection: string, id: DocId): Promise<(Record<string, unknown> & {
+    id: DocId;
+}) | null>;
+/** §7.8 make-content: the latest draft version, so restoring the draft never drops fields the manager cannot read (KI-1). */
+export declare function latestDraftContent(req: PayloadRequest, collection: string, id: DocId): Promise<(Record<string, unknown> & {
+    id: DocId;
+}) | undefined>;

package/dist/db/publishedContent.js

@@ -0,0 +1,43 @@
+// Keep this module adapter-only: the §7.8 exception does not permit Local API calls.
+/** §7.8 make-content: the published main row, so Payload's draft baseline never fills a field (KI-1). */ export async function publishedContent(req, collection, id) {
+    return req.payload.db.findOne({
+        collection,
+        req,
+        where: {
+            id: {
+                equals: id
+            }
+        },
+        // Static allow-list marker only; adapter reads have no access layer.
+        overrideAccess: true
+    });
+}
+/** §7.8 make-content: the latest draft version, so restoring the draft never drops fields the manager cannot read (KI-1). */ export async function latestDraftContent(req, collection, id) {
+    const { docs } = await req.payload.db.findVersions({
+        collection,
+        req,
+        limit: 1,
+        pagination: false,
+        sort: '-updatedAt',
+        where: {
+            and: [
+                {
+                    parent: {
+                        equals: id
+                    }
+                },
+                {
+                    latest: {
+                        equals: true
+                    }
+                }
+            ]
+        },
+        // Static allow-list marker only; adapter reads have no access layer.
+        overrideAccess: true
+    });
+    return docs[0] ? {
+        ...docs[0].version,
+        id
+    } : undefined;
+}

package/dist/db/results.d.ts

@@ -20,6 +20,8 @@ export interface MetricEventRow {
 export interface IdentityRow {
     anonymousId: string;
     userId: string;
+    verifiedAt: number | null;
+    ownedAt: number | null;
 }
 type PhaseQuery = {
     experimentId: DocId;

package/dist/db/results.js

@@ -91,12 +91,16 @@ function phaseFilter({ experimentId, phase, endedAt }, type) {
     const i = COLUMNS.identities;
     const rows = [];
     for(let offset = 0; offset < ids.length; offset += batchSize){
-        const result = await exec.query(`SELECT ${q(i.anonymousId)} AS "anonymousId", ${q(i.userId)} AS "userId" FROM ${qualifiedTable(exec, TABLES.identities)} WHERE ${q(i.anonymousId)} = ANY($1::text[]) ORDER BY ${q(i.anonymousId)}`, [
+        // Ownership is global to the user, including browsers outside these exposure batches.
+        const table = qualifiedTable(exec, TABLES.identities);
+        const result = await exec.query(`SELECT link.${q(i.anonymousId)} AS "anonymousId", link.${q(i.userId)} AS "userId", round(extract(epoch from link.${q(i.verifiedAt)}) * 1000)::bigint AS "verifiedAt", (SELECT round(extract(epoch from min(owner.${q(i.verifiedAt)})) * 1000)::bigint FROM ${table} owner WHERE owner.${q(i.userId)} = link.${q(i.userId)}) AS "ownedAt" FROM ${table} link WHERE link.${q(i.anonymousId)} = ANY($1::text[]) ORDER BY link.${q(i.anonymousId)}`, [
             ids.slice(offset, offset + batchSize)
         ]);
         rows.push(...result.rows.map((row)=>({
                 anonymousId: row.anonymousId,
-                userId: String(row.userId)
+                userId: String(row.userId),
+                verifiedAt: row.verifiedAt == null ? null : Number(row.verifiedAt),
+                ownedAt: row.ownedAt == null ? null : Number(row.ownedAt)
             })));
     }
     return rows;

package/dist/db/snapshots.d.ts

@@ -1,9 +1,10 @@
 import type { Payload } from 'payload';
-import type { DocId, UnitType } from '../types/contracts.js';
+import type { Arm, DocId, ExperimentKind, Status, UnitType } from '../types/contracts.js';
 import type { Snapshot } from '../types/snapshot.js';
 import type { AnalysisPhase, FrozenMetric } from '../results/analyse.js';
 import { type Executor } from './executor.js';
 export interface ResultsPhase extends AnalysisPhase {
+    arms: Array<AnalysisPhase['arms'][number] & Pick<Arm, 'pageTarget'>>;
     seed: string;
     allocation: number;
     metricDefinitions: Array<FrozenMetric & {
@@ -14,11 +15,18 @@ export interface ResultsPhase extends AnalysisPhase {
 }
 export interface ResultsCandidate {
     phase: ResultsPhase;
+    frozenSnapshot?: Snapshot | null;
+    kind?: ExperimentKind;
+    currentPhase?: number;
+    winnerArm?: string | null;
     unitType: UnitType;
     status: 'running' | 'stopped' | 'decided' | 'archived';
     latestComputedAt: string | null;
     testArms: Array<{
+        key: string;
         weight: number;
+        kind?: string;
+        pageTarget?: string;
     }>;
     layerSlug: string | null;
     layerSlices: number[] | null;
@@ -39,10 +47,14 @@ export declare function writeSnapshots(exec: Executor, snapshots: Snapshot[]): P
 /** Fetch pointers only, then the endpoint reads the bounded set through Payload
  * with req/overrideAccess:false. Called behind the readResults/manage gate. */
 export declare function newestSnapshotIds(exec: Executor, ids: DocId[], per: 'phase' | 'experiment'): Promise<DocId[]>;
-/** Called only behind the endpoint's readResults gate. Experiment collection
- * reads require manage, so read only the decision metadata needed by results. */
-export declare function resultsMetadata(exec: Executor, id: DocId): Promise<{
-    status: string;
+type ResultsMetadata = {
+    name: string | null;
+    kind: ExperimentKind;
+    status: Status;
     snapshotId: DocId | null;
     winnerArm: string | null;
-} | null>;
+};
+/** Called only behind the endpoint's readResults gate. Experiment collection
+ * reads require manage, so read only the identity and decision metadata needed by results. */
+export declare function resultsMetadata(exec: Executor, id: DocId): Promise<ResultsMetadata | null>;
+export {};

package/dist/db/snapshots.js

@@ -31,16 +31,32 @@ const LATE_BEACON_GRACE_MS = 24 * 60 * 60 * 1000;
       'startedAt', p.${q(p.startedAt)}, 'endedAt', p.${q(p.endedAt)}, 'seed', p.${q(p.seed)},
       'arms', p.${q(p.arms)}, 'allocation', p.${q(p.allocation)}, 'metricDefinitions', p.${q(p.metricDefinitions)},
       'analysis', p.${q(p.analysis)}, 'contentChanges', p.${q(p.contentChanges)}) AS "phase",
-    e.${q(e.unitType)} AS "unitType", e.${q(e.status)} AS "status",
+    e.${q(e.kind)} AS "kind", e.${q(e.phase)} AS "currentPhase", e.${q(e.unitType)} AS "unitType", e.${q(e.status)} AS "status", e.${q(e.decisionWinnerArm)} AS "winnerArm",
     (SELECT max(s.${q(s.computedAt)}) FROM ${snapshots} s WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}) AS "latestComputedAt",
     (SELECT t.${q(p.arms)} FROM ${phases} t WHERE t.${q(p.experimentId)} = p.${q(p.experimentId)} AND t.${q(p.phaseKind)} = 'test' AND t.${q(p.phase)} <= p.${q(p.phase)} ORDER BY t.${q(p.phase)} DESC LIMIT 1) AS "testArms",
+    frozen."snapshot" AS "frozenSnapshot",
     l.${q(l.slug)} AS "layerSlug", e.${q(e.layerSlices)} AS "layerSlices"
     FROM ${phases} p JOIN ${qualifiedTable(exec, TABLES.experiments)} e ON e.${q(e.id)} = p.${q(p.experimentId)}
     LEFT JOIN ${qualifiedTable(exec, TABLES.layers)} l ON l.${q(l.id)} = e.${q(e.layerId)}
-    WHERE (p.${q(p.endedAt)} IS NULL OR p.${q(p.endedAt)} >= $1)
-    AND NOT EXISTS (SELECT 1 FROM ${snapshots} frozen WHERE frozen.${q(s.experimentId)} = p.${q(p.experimentId)} AND frozen.${q(s.phase)} = p.${q(p.phase)}
-      AND frozen.${q(s.computedAt)} > p.${q(p.endedAt)} + $2 * interval '1 millisecond')${experimentId === undefined ? '' : ` AND p.${q(p.experimentId)} = $3`}
-    ORDER BY "latestComputedAt" NULLS FIRST, p.${q(p.experimentId)}, p.${q(p.phase)}`, params);
+    LEFT JOIN LATERAL (SELECT s.${q(s.snapshot)} AS "snapshot" FROM ${snapshots} s
+      WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}
+        AND p.${q(p.endedAt)} IS NOT NULL
+        AND (s.${q(s.computedAt)} > p.${q(p.endedAt)} + $2 * interval '1 millisecond' OR p.${q(p.endedAt)} < $1)
+      ORDER BY s.${q(s.computedAt)} DESC, s.${q(s.id)} DESC LIMIT 1) frozen ON true
+    WHERE ((e.${q(e.kind)} = 'page'
+        AND (p.${q(p.endedAt)} IS NULL OR p.${q(p.endedAt)} >= $1 OR EXISTS
+          (SELECT 1 FROM ${snapshots} existing WHERE existing.${q(s.experimentId)} = p.${q(p.experimentId)} AND existing.${q(s.phase)} = p.${q(p.phase)}))
+        AND e.${q(e.status)} IN ('running', 'decided') AND (p.${q(p.phase)} = e.${q(e.phase)}
+        OR p.${q(p.phase)} = (SELECT max(active.${q(p.phase)}) FROM ${phases} active WHERE active.${q(p.experimentId)} = e.${q(e.id)} AND active.${q(p.phaseKind)} = 'test')))
+      OR ((p.${q(p.endedAt)} IS NULL OR p.${q(p.endedAt)} >= $1)
+        AND NOT EXISTS (SELECT 1 FROM ${snapshots} done WHERE done.${q(s.experimentId)} = p.${q(p.experimentId)} AND done.${q(s.phase)} = p.${q(p.phase)}
+          AND done.${q(s.computedAt)} > p.${q(p.endedAt)} + $2 * interval '1 millisecond')))
+      ${experimentId === undefined ? '' : ` AND p.${q(p.experimentId)} = $3`}
+    ORDER BY (frozen."snapshot" IS NOT NULL),
+      CASE WHEN frozen."snapshot" IS NULL THEN
+        (SELECT max(s.${q(s.computedAt)}) FROM ${snapshots} s WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}) END NULLS FIRST,
+      CASE WHEN frozen."snapshot" IS NOT NULL THEN random() END,
+      p.${q(p.experimentId)}, p.${q(p.phase)}`, params);
     return rows;
 }
 export async function writeSnapshot(exec, snapshot) {
@@ -80,9 +96,9 @@ export async function writeSnapshot(exec, snapshot) {
     return rows.map((row)=>row.id);
 }
 /** Called only behind the endpoint's readResults gate. Experiment collection
- * reads require manage, so read only the decision metadata needed by results. */ export async function resultsMetadata(exec, id) {
+ * reads require manage, so read only the identity and decision metadata needed by results. */ export async function resultsMetadata(exec, id) {
     const c = COLUMNS.experiments;
-    const { rows } = await exec.query(`SELECT ${q(c.status)} AS "status", ${q(c.decisionSnapshotId)} AS "snapshotId", ${q(c.decisionWinnerArm)} AS "winnerArm" FROM ${qualifiedTable(exec, TABLES.experiments)} WHERE ${q(c.id)} = $1`, [
+    const { rows } = await exec.query(`SELECT ${q(c.name)} AS "name", ${q(c.kind)} AS "kind", ${q(c.status)} AS "status", ${q(c.decisionSnapshotId)} AS "snapshotId", ${q(c.decisionWinnerArm)} AS "winnerArm" FROM ${qualifiedTable(exec, TABLES.experiments)} WHERE ${q(c.id)} = $1`, [
         id
     ]);
     return rows[0] ?? null;

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;
+}