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

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/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/sweep.js

@@ -11,6 +11,13 @@ import { ResultsBudgetError } from './pgExecutor.js';
     const events = qualifiedTable(exec, TABLES.events), phases = qualifiedTable(exec, TABLES.phases);
     const revision = `(SELECT ${q(s.revision)} FROM ${qualifiedTable(exec, TABLES.state)} LIMIT 1)`;
     let swept = 0;
+    const warnNoProgress = ()=>logger?.warn('Experiment retention sweep made no progress before its budget expired; eligible rows may remain.');
+    // Every budget-limited exit with nothing swept is reported, whether the budget ran out mid-statement (the catch
+    // below) or before the next batch could start (here).
+    const finish = ()=>{
+        if (swept === 0 && !shouldContinue()) warnNoProgress();
+        return swept;
+    };
     // Each statement still uses the caller's budget/race-aware executor.
     async function batches(predicate, order, params = []) {
         while(shouldContinue()){
@@ -38,7 +45,7 @@ import { ResultsBudgetError } from './pgExecutor.js';
                 type
             ]);
         }
-        if (!shouldContinue()) return swept;
+        if (!shouldContinue()) return finish();
         // Final-endedAt retention protects every phase while any phase is open.
         const ended = await exec.query(`SELECT ${q(p.experimentId)} AS "experimentId" FROM ${phases}
       WHERE ${q(p.experimentId)} IS NOT NULL GROUP BY ${q(p.experimentId)}
@@ -54,7 +61,7 @@ import { ResultsBudgetError } from './pgExecutor.js';
                 cutoff
             ]);
         }
-        if (!shouldContinue()) return swept;
+        if (!shouldContinue()) return finish();
         // Every protected window ends at/after cutoff (or is open). For old
         // conversions their union therefore starts at the earliest lookback start;
         // everything before that single bound is safe. Compute it once, in the same
@@ -80,11 +87,9 @@ import { ResultsBudgetError } from './pgExecutor.js';
             before,
             frozen.revision
         ]);
-        return swept;
+        return finish();
     } catch (error) {
-        if (swept === 0 && error instanceof ResultsBudgetError) {
-            logger?.warn('Experiment retention sweep made no progress before its budget expired; eligible rows may remain.');
-        }
+        if (swept === 0 && error instanceof ResultsBudgetError) warnNoProgress();
         throw error;
     }
 }

package/dist/endpoints/index.js

@@ -4,7 +4,7 @@ import { XpNotImplemented, XpRefusal } from '../errors.js';
 import { readUnitCookie } from '../runtime/cookie.js';
 import { handleManifest } from './manifest.js';
 import { handleEvents } from './events.js';
-import { handleStart, handleAllocate, handleAddMetric, handleStop, handleDecide, handleReleaseHoldout, handleMakeContent, handleArchive } from './transitions.js';
+import { handleStart, handleAllocate, handleAddMetric, handleStop, handleDecide, handleReleaseHoldout, handleReleasePages, handleMakeContent, handleDismissContentEntry, handleRestoreContentEntry, handleArchive } from './transitions.js';
 import { handlePreflight } from './preflight.js';
 import { handlePreviewToken } from './previewToken.js';
 import { handleResults } from './results.js';
@@ -59,12 +59,30 @@ export const ROUTES = [
         access: 'manage',
         handler: handleReleaseHoldout
     },
+    {
+        method: 'post',
+        path: '/xp/experiments/:id/release-pages',
+        access: 'manage',
+        handler: handleReleasePages
+    },
     {
         method: 'post',
         path: '/xp/experiments/:id/make-content',
         access: 'manage',
         handler: handleMakeContent
     },
+    {
+        method: 'post',
+        path: '/xp/experiments/:id/content-report/dismiss',
+        access: 'manage',
+        handler: handleDismissContentEntry
+    },
+    {
+        method: 'post',
+        path: '/xp/experiments/:id/content-report/restore',
+        access: 'manage',
+        handler: handleRestoreContentEntry
+    },
     {
         method: 'post',
         path: '/xp/experiments/:id/archive',

package/dist/endpoints/results.js

@@ -111,6 +111,11 @@ export async function handleResults(req, _ctx) {
     if (selected !== null && !records.some((record)=>record.phase === phase)) return resultsError(404, 'not-found', 'Round not found');
     const snapshot = snapshots.find((snapshot)=>snapshot.phase === phase)?.snapshot ?? null;
     const response = {
+        experiment: {
+            name: metadata.name ?? '',
+            kind: metadata.kind,
+            status: metadata.status
+        },
         phases,
         snapshot,
         ...decision ? {

package/dist/endpoints/sanitizeReadinessDetail.d.ts

@@ -0,0 +1 @@
+export { sanitizeReadinessDetail } from '../sanitizeReadinessDetail.js';

package/dist/endpoints/sanitizeReadinessDetail.js

@@ -0,0 +1,2 @@
+// Shared with the admin home; keep this server import path stable.
+export { sanitizeReadinessDetail } from '../sanitizeReadinessDetail.js';

package/dist/endpoints/summary.js

@@ -2,6 +2,7 @@ import { checkStart } from '../transitions/checkStart.js';
 import { loadStartInputsBatch } from '../transitions/preflightData.js';
 import { readSnapshots, resultsError } from './results.js';
 import { experimentId } from './routeId.js';
+import { sanitizeReadinessDetail } from './sanitizeReadinessDetail.js';
 export async function handleSummary(req, { options }) {
     let ids;
     try {
@@ -40,7 +41,13 @@ export async function handleSummary(req, { options }) {
             verdict: {
                 code: snapshot.verdict.code,
                 headline: snapshot.verdict.headline
-            }
+            },
+            ...snapshot.health ? {
+                health: snapshot.health.slice(0, 100).map(({ code, path })=>({
+                        code,
+                        path: path.slice(0, 128)
+                    }))
+            } : {}
         } : {
             exposures: 0,
             days: 0,
@@ -72,7 +79,18 @@ export async function handleSummary(req, { options }) {
                 if (!experiment) continue;
                 const input = inputs.get(String(experiment.id));
                 try {
-                    response[key].ready = !!input && checkStart(input).every((check)=>check.ok);
+                    const checks = input ? checkStart(input) : [];
+                    response[key].ready = !!input && checks.every((check)=>check.ok);
+                    const next = checks.find((check)=>!check.ok && !check.warning);
+                    if (next) {
+                        const detail = sanitizeReadinessDetail(next.code, next.detail);
+                        response[key].next = {
+                            code: next.code,
+                            ...detail === undefined ? {} : {
+                                detail
+                            }
+                        };
+                    }
                 } catch  {
                     response[key].ready = false;
                 }