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

package/dist/transitions/preflightData.js

@@ -1,7 +1,14 @@
+import { Forbidden, NotFound } from 'payload';
+import { safeError } from '../log.js';
 import { powerMetricWeeks } from '@delmaredigital/experiments-stats';
 import { checkStart, relationshipId } from './checkStart.js';
 import { flagPlacements, scanBlockPlacements } from './placements.js';
-const failureDetail = (cause)=>cause instanceof Error ? cause.message : 'Placement lookup failed.';
+import { routedPageTests } from '../db/pageOccupancy.js';
+import { pooledExecutor, txExecutor } from '../db/executor.js';
+const failureDetail = (cause)=>{
+    const name = cause instanceof Error ? cause.name : undefined;
+    return cause instanceof Forbidden || name === 'Forbidden' ? 'forbidden' : cause instanceof NotFound || name === 'NotFound' ? 'not-found' : 'placements-failed';
+};
 /** Read-only inputs shared with Start's pre-transaction checks. Start must re-read
  * the document and lock-sensitive facts inside its transition (CORE-10b).
  */ export async function loadStartInputs(req, options, experimentId) {
@@ -23,6 +30,30 @@ const failureDetail = (cause)=>cause instanceof Error ? cause.message : 'Placeme
         experiment
     ])).get(String(experiment.id)) ?? null;
 }
+/** Occupancy from the arms the runtime routes on (frozen rounds), shared by preflight and
+ * Start's locked recheck. Raw SQL on the request's transaction when there is one. */ export async function loadPageTestsInUse(req) {
+    return routedPageTests(await req.transactionID != null ? txExecutor(req) : pooledExecutor(req.payload));
+}
+/** Page targets no registered collection reports as published. A lookup that throws counts as
+ * unpublished (logged). Start calls it again under its page-path locks on a detached request. */ export async function unpublishedPageTargets(req, options, experiment) {
+    const targets = await Promise.all(experiment.arms.filter((arm)=>arm.kind !== 'holdout' && arm.pageTarget?.trim()).map(async (arm)=>{
+        for (const collection of options.pages?.collections ?? []){
+            try {
+                const page = await collection.findByPath(arm.pageTarget, req);
+                if (page?.published === true) return null;
+            } catch (cause) {
+                req.payload.logger.error({
+                    err: safeError(cause),
+                    experimentId: experiment.id,
+                    collection: collection.slug,
+                    id: arm.pageTarget
+                }, 'Experiment page lookup failed');
+            }
+        }
+        return arm.pageTarget;
+    }));
+    return targets.filter((target)=>target !== null);
+}
 const metricIds = (experiment)=>[
         experiment.metrics?.primary,
         ...experiment.metrics?.secondary ?? [],
@@ -53,6 +84,7 @@ const metricIds = (experiment)=>[
     })();
     const blockSlugs = new Set(experiments.filter((e)=>e.kind === 'block').map((e)=>e.slug));
     // Lazy promises prevent unhandled rejections and share failed reads as well as successful ones.
+    let pageTestsInUse;
     let blocks;
     let state;
     const busyPoints = new Map();
@@ -68,6 +100,22 @@ const metricIds = (experiment)=>[
                 flagPoints: options.flagPoints,
                 attributeKeys: options.attributeKeys
             };
+            const placementFailure = (cause)=>{
+                const collection = experiment.flagPoint ?? 'xp-experiments';
+                req.payload.logger.error({
+                    err: safeError(cause),
+                    experimentId: experiment.id,
+                    collection,
+                    id: experiment.id
+                }, 'Experiment placement lookup failed');
+                return failureDetail(cause);
+            };
+            if (experiment.kind === 'page') {
+                pageTestsInUse ??= loadPageTestsInUse(req);
+                input.pageTestsInUse = await pageTestsInUse;
+                input.pageTargetsUnchecked = options.pages === undefined;
+                if (options.pages) input.unpublishedPageTargets = await unpublishedPageTargets(req, options, experiment);
+            }
             if (experiment.kind === 'block') {
                 try {
                     blocks ??= scanBlockPlacements(req, {
@@ -76,7 +124,7 @@ const metricIds = (experiment)=>[
                     });
                     input.placements = (await blocks).get(experiment.slug) ?? [];
                 } catch (cause) {
-                    input.placementError = failureDetail(cause);
+                    input.placementError = placementFailure(cause);
                 }
             }
             if (experiment.kind === 'flag') {
@@ -108,9 +156,9 @@ const metricIds = (experiment)=>[
                     try {
                         const placements = await flagPlacements(options, experiment, req);
                         if (Array.isArray(placements) && placements.every((p)=>p && typeof p === 'object' && typeof p.arm === 'string')) input.flagPlacements = placements;
-                        else input.flagPlacementError = 'Placement lookup returned an invalid result.';
+                        else input.flagPlacementError = placementFailure(new Error('Invalid placement result'));
                     } catch (cause) {
-                        input.flagPlacementError = failureDetail(cause);
+                        input.flagPlacementError = placementFailure(cause);
                     }
                 }
                 if (experiment.flagPoint) {
@@ -210,16 +258,23 @@ const metricIds = (experiment)=>[
     }
     return inputs;
 }
-function placementUrls(options, placement) {
+// Bound each optional host preview lookup so it cannot indefinitely hold preflight open.
+const PREVIEW_URL_TIMEOUT_MS = 2000;
+// Resolve host preview lookups in a bounded pool instead of launching one per slot.
+const PREVIEW_URL_CONCURRENCY = 8;
+async function placementUrls(options, placement, pendingPreviews, onFailure, previews) {
     const result = {};
     const { collection, id, published } = placement;
-    try {
-        const url = options.admin?.previewUrl?.({
-            collection,
-            id
-        });
-        if (typeof url === 'string') result.url = url;
-    } catch  {}
+    // One host lookup per page version: several slots on a page share it.
+    const key = JSON.stringify([
+        collection,
+        String(id),
+        published
+    ]);
+    let preview = previews.get(key);
+    if (!preview) previews.set(key, preview = previewLookup(options, placement, pendingPreviews, onFailure));
+    const url = await preview;
+    if (url !== undefined) result.url = url;
     try {
         const url = options.admin?.editorUrl?.({
             collection,
@@ -230,6 +285,43 @@ function placementUrls(options, placement) {
     } catch  {}
     return result;
 }
+async function previewLookup(options, placement, pendingPreviews, onFailure) {
+    const { collection, id, title, published, slug } = placement;
+    const previewUrl = options.admin?.previewUrl;
+    let found;
+    if (previewUrl) {
+        let timer;
+        try {
+            if (pendingPreviews.count >= PREVIEW_URL_CONCURRENCY) throw new Error('Preview URL lookups at capacity');
+            pendingPreviews.count++;
+            // A timeout cannot cancel host work: retain its permit until that work settles.
+            const lookup = Promise.resolve().then(()=>previewUrl({
+                    collection,
+                    id,
+                    title,
+                    published,
+                    ...slug !== undefined ? {
+                        slug
+                    } : {}
+                })).finally(()=>{
+                pendingPreviews.count--;
+            });
+            const url = await Promise.race([
+                lookup,
+                new Promise((_, reject)=>{
+                    timer = setTimeout(()=>reject(new Error('Preview URL lookup timed out')), PREVIEW_URL_TIMEOUT_MS);
+                })
+            ]);
+            if (typeof url === 'string') found = url;
+            else if (url !== null && url !== undefined) throw new TypeError('Invalid preview URL result');
+        } catch (cause) {
+            onFailure(cause, placement);
+        } finally{
+            clearTimeout(timer);
+        }
+    }
+    return found;
+}
 async function primaryHistory(source, now) {
     if (!source) return null;
     const from = new Date(now.getTime() - 28 * 86400000);
@@ -340,15 +432,41 @@ export async function preflightData(req, { experimentId, options }, { now = new
         }
     }
     const requiredSlots = e.arms.filter((arm)=>arm.kind !== 'holdout').map((arm)=>arm.slot);
-    const placements = (input.placements ?? []).map((placement)=>({
+    const blocks = input.placements ?? [];
+    const placements = new Array(blocks.length);
+    let nextPlacement = 0;
+    const pendingPreviews = {
+        count: 0
+    };
+    const previews = new Map();
+    let loggedPreviewFailure = false;
+    const onPreviewFailure = (cause, placement)=>{
+        if (loggedPreviewFailure) return;
+        loggedPreviewFailure = true;
+        req.payload.logger.warn({
+            err: safeError(cause),
+            experimentId: e.id,
             collection: placement.collection,
-            id: placement.id,
-            title: placement.title,
-            slots: placement.slots,
-            ...placementUrls(options, placement),
-            ok: requiredSlots.every((slot)=>slot && placement.slots[slot] > 0),
-            detail: placement.published ? 'Published' : 'Draft'
-        }));
+            id: placement.id
+        }, 'Experiment preview URL lookup failed');
+    };
+    await Promise.all(Array.from({
+        length: Math.min(PREVIEW_URL_CONCURRENCY, blocks.length)
+    }, async ()=>{
+        while(nextPlacement < blocks.length){
+            const index = nextPlacement++;
+            const placement = blocks[index];
+            placements[index] = {
+                collection: placement.collection,
+                id: placement.id,
+                title: placement.title,
+                slots: placement.slots,
+                ...await placementUrls(options, placement, pendingPreviews, onPreviewFailure, previews),
+                ok: requiredSlots.every((slot)=>slot && placement.slots[slot] > 0),
+                detail: placement.published ? 'Published' : 'Draft'
+            };
+        }
+    }));
     for (const placement of input.flagPlacements ?? [])placements.push({
         collection: e.flagPoint ?? '',
         id: placement.arm,

package/dist/transitions/releasePages.d.ts

@@ -0,0 +1,8 @@
+import type { PayloadRequest } from 'payload';
+import type { DocId } from '../types/contracts.js';
+export declare function releasePages(req: PayloadRequest, { experimentId }: {
+    experimentId: DocId;
+}): Promise<{
+    doc: import("payload").JsonObject & import("payload").TypeWithID;
+    revision: number;
+}>;

package/dist/transitions/releasePages.js

@@ -0,0 +1,26 @@
+import { relationshipId } from './checkStart.js';
+import { withTransition } from './kernel.js';
+import { readExperiment, refuse, updateExperiment } from './start.js';
+export async function releasePages(req, { experimentId }) {
+    const before = await readExperiment(req, experimentId);
+    const { result: doc, revision } = await withTransition(req, {
+        experimentId,
+        layerId: relationshipId(before.layer)
+    }, async ({ req })=>{
+        const current = await readExperiment(req, experimentId);
+        const decision = current.decision;
+        if (current.kind !== 'page' || current.status !== 'archived' || !decision?.winnerArm || decision.discardedAt || decision.pagesReleasedAt) refuse('invalid-status');
+        const at = new Date().toISOString();
+        return updateExperiment(req, experimentId, {
+            decision: {
+                ...decision,
+                pagesReleasedAt: at,
+                pagesReleasedBy: req.user ? String(req.user.id) : null
+            }
+        });
+    });
+    return {
+        doc,
+        revision: revision
+    };
+}

package/dist/transitions/restoreContentEntry.d.ts

@@ -0,0 +1,8 @@
+import type { PayloadRequest } from 'payload';
+import type { DocId } from '../types/contracts.js';
+import type { RestoreContentEntryBody } from '../types/endpoints.js';
+export declare function restoreContentEntry(req: PayloadRequest, { experimentId, collection, id }: RestoreContentEntryBody & {
+    experimentId: DocId;
+}): Promise<{
+    doc: import("payload").JsonObject & import("payload").TypeWithID;
+}>;

package/dist/transitions/restoreContentEntry.js

@@ -0,0 +1,47 @@
+import { relationshipId } from './checkStart.js';
+import { withTransition } from './kernel.js';
+import { readExperiment, refuse, updateExperiment } from './start.js';
+export async function restoreContentEntry(req, { experimentId, collection, id }) {
+    const before = await readExperiment(req, experimentId);
+    // Only the audit report changes; assignment and the manifest stay the same.
+    const { result: doc } = await withTransition(req, {
+        experimentId,
+        layerId: relationshipId(before.layer),
+        flagPointId: before.kind === 'flag' ? before.flagPoint : undefined,
+        bump: false
+    }, async ({ req })=>{
+        const current = await readExperiment(req, experimentId);
+        const decision = current.decision;
+        const report = decision?.contentReport;
+        const index = Array.isArray(report?.docs) ? report.docs.findIndex((entry)=>entry.collection === collection && String(entry.id) === String(id)) : -1;
+        const entry = report?.docs?.[index];
+        if (current.status !== 'decided' || !decision?.winnerArm || decision.discardedAt) refuse('not-decided');
+        if (!entry) refuse('entry-not-found');
+        if (!entry.dismissedAt) refuse('entry-not-dismissed');
+        const docs = report.docs.map((entry, i)=>{
+            if (i !== index) return entry;
+            const { dismissedAt: _at, dismissedBy: _by, ...restored } = entry;
+            return {
+                ...restored,
+                ok: false
+            };
+        });
+        return updateExperiment(req, experimentId, {
+            decision: {
+                ...decision,
+                contentReport: {
+                    ...report,
+                    docs
+                }
+            }
+        });
+    });
+    req.payload.logger.info({
+        experimentId,
+        collection,
+        id
+    }, 'Experiment content entry restored');
+    return {
+        doc
+    };
+}

package/dist/transitions/start.js

@@ -1,11 +1,15 @@
+import { lockPagePaths } from '../db/locks.js';
+import { lockMetricsForFreeze } from '../db/metricUsage.js';
+import { DEFAULT_SEQUENTIAL_TUNING_PARAMETER } from '../constants.js';
 import { claimSlices } from '../db/slices.js';
+import { pageInUseCopy, unpublishedPageCopy } from '../admin/copy/readiness.js';
 import { XpRefusal } from '../errors.js';
 import { isOpValid } from '../targeting/ops.js';
 import { newSeed } from '../runtime/seed.js';
-import { checkStart, relationshipId } from './checkStart.js';
+import { checkStart, pageTargetPaths, relationshipId } from './checkStart.js';
 import { withTransition } from './kernel.js';
 import { writePhaseRecord } from './phaseRecord.js';
-import { loadStartInputs } from './preflightData.js';
+import { loadPageTestsInUse, loadStartInputs, unpublishedPageTargets } from './preflightData.js';
 import { resolveCaps } from './resolveCaps.js';
 export async function readExperiment(req, id) {
     // §7.8: internal lookup serves the authorised transition write. Preserve
@@ -27,21 +31,33 @@ export async function readExperiment(req, id) {
 }
 export function refuse(code, detail) {
     const messages = {
+        'page-in-use': pageInUseCopy(detail?.paths?.[0] ?? 'this page'),
+        'page-target-unpublished': unpublishedPageCopy(typeof detail === 'string' ? detail : 'This page'),
         'invalid-status': 'This action is not available in the current status.',
         'stale-draft': 'The experiment changed. Review it again before starting.',
         'flag-point-busy': 'Another experiment is running or decided on this flag point.',
         'layer-full': 'There is not enough room in this layer.',
         'allocation-lower': 'Allocation can only increase while running. Stop and start a new round to lower it.',
-        'invalid-body': 'Check the experiment settings and try again.'
+        'invalid-body': 'Check the experiment settings and try again.',
+        'not-decided': 'This test has no standing winner.',
+        'entry-not-found': 'That page is not in the report.',
+        'entry-ok': 'That page was already updated.',
+        'entry-dismissed': 'That page was already dismissed.',
+        'entry-not-dismissed': 'That page is not dismissed.'
     };
     const conflict = [
         'invalid-status',
         'stale-draft',
+        'page-in-use',
         'flag-point-busy',
         'layer-full',
-        'allocation-lower'
+        'allocation-lower',
+        'not-decided',
+        'entry-ok',
+        'entry-dismissed',
+        'entry-not-dismissed'
     ].includes(code);
-    throw new XpRefusal(code, messages[code] ?? 'The experiment is not ready to start.', detail, conflict ? 409 : 422);
+    throw new XpRefusal(code, messages[code] ?? 'The experiment is not ready to start.', detail, code === 'entry-not-found' ? 404 : conflict ? 409 : 422);
 }
 export async function updateExperiment(req, id, data) {
     // §7.8: access-authorised transition writes locked plugin fields.
@@ -78,8 +94,10 @@ export async function start(req, { experimentId, options }) {
         kind: full.kind,
         analysis: full.analysis
     };
+    // Warning-only codes always have ok: true. These exclusions narrow
+    // ReadinessCode to RefusalCode, which intentionally excludes warnings.
     const failed = checkStart(input).find((check)=>!check.ok);
-    if (failed) refuse(failed.code, failed.detail);
+    if (failed && failed.code !== 'page-targets-unchecked' && failed.code !== 'make-content-unsupported') refuse(failed.code, failed.detail);
     const before = input.experiment;
     const updatedAt = before.updatedAt;
     const at = new Date();
@@ -92,6 +110,33 @@ export async function start(req, { experimentId, options }) {
         const current = await readExperiment(req, experimentId);
         if (current.updatedAt !== updatedAt) refuse('stale-draft');
         if (current.status !== 'draft' && current.status !== 'stopped') refuse('invalid-status');
+        if (current.kind === 'page') {
+            // Independent experiment/layer locks do not serialize overlapping pages.
+            // Re-read occupancy after acquiring sorted path locks; hold through commit.
+            // A waiting Start then sees the first Start's live test on this transaction.
+            await lockPagePaths(exec, pageTargetPaths(current.arms));
+            const recheck = checkStart({
+                ...input,
+                experiment: current,
+                pageTestsInUse: await loadPageTestsInUse(req)
+            }).find((check)=>check.code === 'page-in-use' && !check.ok);
+            if (recheck) refuse('page-in-use', recheck.detail);
+            if (options.pages) {
+                // The page guard takes the same path locks, so a delete, unpublish or rename that committed
+                // while Start waited is visible now. Read it on a detached request (committed state, outside
+                // this transaction): a refused host read must not kill the transition (CORE-21).
+                // (the make-content pattern: drop the transaction id for the reads, restore it after).
+                const transactionID = req.transactionID;
+                delete req.transactionID;
+                let unpublished;
+                try {
+                    unpublished = await unpublishedPageTargets(req, options, current);
+                } finally{
+                    req.transactionID = transactionID;
+                }
+                if (unpublished.length) refuse('page-target-unpublished', unpublished[0]);
+            }
+        }
         if (current.kind === 'flag' && current.flagPoint) {
             const busy = await req.payload.find({
                 collection: 'xp-experiments',
@@ -134,8 +179,17 @@ export async function start(req, { experimentId, options }) {
                 ...input,
                 experiment: current
             }).find((check)=>!check.ok);
-            if (recheck) refuse(recheck.code, recheck.detail);
+            if (recheck && recheck.code !== 'page-targets-unchecked' && recheck.code !== 'make-content-unsupported') refuse(recheck.code, recheck.detail);
+        }
+        const lockedMetrics = await lockMetricsForFreeze(exec, caps.definitions.map((metric)=>metric.id));
+        if (!lockedMetrics) {
+            throw new XpRefusal('stale-draft', 'A goal in this test was deleted. Review the goals before starting.', undefined, 409);
         }
+        // Reachable: a slug/source change takes FOR NO KEY UPDATE, which a draft's FK check does not wait on.
+        if (caps.definitions.some((metric)=>{
+            const locked = lockedMetrics.find((row)=>String(row.id) === String(metric.id));
+            return locked.slug !== metric.slug || locked.source !== metric.source;
+        })) throw new XpRefusal('stale-draft', 'A goal changed. Review it again before starting.', undefined, 409);
         const targeting = (current.targeting ?? []).map((rule)=>{
             const type = Object.hasOwn(options.attributeKeys ?? {}, rule.attribute) ? options.attributeKeys[rule.attribute].type : undefined;
             const validValue = type === 'string' && [
@@ -183,6 +237,7 @@ export async function start(req, { experimentId, options }) {
                 ...current.analysis,
                 method: current.analysis?.method ?? 'sequential',
                 alpha: 0.05,
+                sequentialTuningParameter: current.analysis?.sequentialTuningParameter ?? DEFAULT_SEQUENTIAL_TUNING_PARAMETER,
                 cupedLookbackDays: 14,
                 layerSlices,
                 minSampleSizes: Object.fromEntries(definitions.map((metric)=>[

package/dist/types/contracts.d.ts

@@ -3,6 +3,14 @@ import type { ExperimentsServerRuntime } from './runtime.js';
 import type { ArmSlot } from './puck.js';
 import type { TargetingOp } from '../targeting/ops.js';
 export type DocId = string | number;
+export interface PreviewPlacement {
+    collection: string;
+    id: DocId;
+    title: string;
+    published: boolean;
+    /** The published main row's string slug, including on draft placements; absent for unpublished documents, never a draft/version row's slug. */
+    slug?: string;
+}
 export type Attributes = Record<string, string | number | boolean>;
 export type ExposurePolicy = 'render' | 'viewport' | 'pageview' | 'manual';
 export type ExperimentKind = 'block' | 'page' | 'flag' | 'code';
@@ -93,6 +101,15 @@ export type RateLimiter = (args: {
 export type ExperimentsAccess = (args: {
     req: PayloadRequest;
 }) => boolean | Promise<boolean>;
+export interface ExperimentsPageCollection {
+    slug: string;
+    pathOf: (doc: Record<string, unknown>) => string | null;
+    /** Lookup with the supplied req and overrideAccess: false. Under an anonymous req (results checks) only published pages are visible, so a hit is { published: true } or null. Under a req that can read drafts (Start), a draft-only page may be reported as { published: false }. */
+    findByPath: (path: string, req: PayloadRequest) => Promise<{
+        id: string | number;
+        published: boolean;
+    } | null>;
+}
 export interface ExperimentsPluginOptions<TUser extends {
     id: string | number;
 } = {
@@ -105,16 +122,16 @@ export interface ExperimentsPluginOptions<TUser extends {
         readResults?: ExperimentsAccess;
         readIdentities?: ExperimentsAccess;
     };
+    theme?: {
+        accent?: string;
+    };
     admin?: {
         editorUrl?: (args: {
             collection: string;
             id: DocId;
             draft?: boolean;
         }) => string;
-        previewUrl?: (args: {
-            collection: string;
-            id: DocId;
-        }) => string;
+        previewUrl?: (placement: PreviewPlacement) => string | null | undefined | Promise<string | null | undefined>;
         descriptions?: {
             block?: string;
             document?: string;
@@ -131,6 +148,9 @@ export interface ExperimentsPluginOptions<TUser extends {
         type: 'string' | 'number' | 'boolean';
         values?: string[];
     }>;
+    pages?: {
+        collections: ExperimentsPageCollection[];
+    };
     puck?: {
         enabled: boolean;
         collections: Array<string | {

package/dist/types/endpoints.d.ts

@@ -1,10 +1,13 @@
-import type { ArmKind, DocId, ExposurePolicy, MetricSource, ResolvedOptions } from './contracts.js';
+import type { ArmKind, DocId, ExperimentKind, ExposurePolicy, MetricSource, ResolvedOptions, Status } from './contracts.js';
+import type { ContentReportReason } from './reasons.js';
 import type { ArmSlot } from './puck.js';
 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' | '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';
+/** Content-report dismiss/restore refusals (CORE-44). */
+export type ContentEntryRefusal = 'not-decided' | 'entry-not-found' | 'entry-ok' | 'entry-dismissed' | 'entry-not-dismissed';
+export type RefusalCode = ArmIssueCode | 'not-found' | ContentEntryRefusal | 'no-planned-duration' | 'no-primary-metric' | 'no-placements' | 'empty-slot' | 'page-in-use' | 'page-no-targets' | 'page-target-unpublished' | 'page-user-unit' | 'version-page-unavailable' | 'version-page-unchecked' | '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' | 'block-path-rule' | 'duplicate-metric';
 export type ErrorEnvelope = {
     errors: Array<{
         code: RefusalCode;
@@ -32,12 +35,25 @@ export type ArchiveBody = {
     mode: 'stopped' | 'after-content' | 'discard' | 'hard-coded';
     confirmation?: string;
 };
+export type DismissContentEntryBody = {
+    collection: string;
+    id: DocId;
+};
+export type DismissContentEntryResult = Pick<TransitionSuccess, 'doc'>;
+export type RestoreContentEntryBody = DismissContentEntryBody;
+export type RestoreContentEntryResult = Pick<TransitionSuccess, 'doc'>;
+export type ContentReport = {
+    docs: MakeContentResult['docs'];
+} | MakeContentResult['docs'];
 export type MakeContentResult = TransitionSuccess & {
     docs: Array<{
         collection: string;
         id: DocId;
         ok: boolean;
-        error?: string;
+        detail?: ContentReportReason | string;
+        error?: ContentReportReason | string;
+        dismissedAt?: string;
+        dismissedBy?: string | null;
     }>;
 };
 export type PreflightResult = {
@@ -45,6 +61,7 @@ export type PreflightResult = {
         code: ReadinessCode;
         ok: boolean;
         detail?: unknown;
+        warning?: boolean;
     }>;
     placements: Array<{
         collection: string;
@@ -93,6 +110,12 @@ export interface PhaseSummary {
     }>;
 }
 export type ResultsResponse = {
+    /** Filled by the results endpoint from CORE-48: what a results reader may see about the test. */
+    experiment?: {
+        name: string;
+        kind: ExperimentKind;
+        status: Status;
+    };
     phases: PhaseSummary[];
     snapshot: Snapshot | null;
     decisionSnapshot?: Snapshot;
@@ -110,6 +133,14 @@ export type ResultsResponse = {
 };
 export type SummaryResponse = Record<DocId, {
     ready?: boolean;
+    next?: {
+        code: ReadinessCode;
+        detail?: unknown;
+    };
+    health?: Array<{
+        code: 'version-page-unavailable' | 'version-page-unchecked';
+        path: string;
+    }>;
     exposures: number;
     days: number;
     verdict: {

package/dist/types/index.d.ts

@@ -6,3 +6,4 @@ export * from './puck.js';
 export * from './admin.js';
 export * from './endpoints.js';
 export * from './snapshot.js';
+export * from './reasons.js';

package/dist/types/index.js

@@ -6,3 +6,4 @@ export * from './puck.js';
 export * from './admin.js';
 export * from './endpoints.js';
 export * from './snapshot.js';
+export * from './reasons.js';

package/dist/types/reasons.d.ts

@@ -0,0 +1,3 @@
+/** Closed codes written by new results runs; stored snapshots may predate them. */
+export type MetricUnavailableReason = 'source-failed' | 'source-unavailable' | 'unit-type-unavailable' | 'non-finite-values' | 'non-finite-covariates' | 'budget' | 'not-supplied' | 'analysis-failed';
+export type ContentReportReason = 'localized' | 'locked' | 'forbidden' | 'not-found' | 'validation' | 'update-failed';

package/dist/types/reasons.js

@@ -0,0 +1 @@
+/** Closed codes written by new results runs; stored snapshots may predate them. */ export { };

package/dist/types/snapshot.d.ts

@@ -1,5 +1,6 @@
 import type { GaussianPrior } from '@delmaredigital/experiments-stats';
 import type { DocId, MetricSource } from './contracts.js';
+import type { MetricUnavailableReason } from './reasons.js';
 export type VerdictCode = 'unavailable' | 'data-problem' | 'guardrail-failing' | 'collecting' | 'original-better' | 'worse-none-better' | 'winner' | 'mixed' | 'keep-running' | 'no-difference' | 'rollout-collecting' | 'rollout-readout';
 export interface Snapshot {
     experiment: DocId;
@@ -54,7 +55,7 @@ export interface Snapshot {
         kind: MetricSource['kind'];
         role: 'primary' | 'secondary' | 'guardrail';
         cupedApplied: boolean;
-        unavailable?: string;
+        unavailable?: MetricUnavailableReason | string;
         perArm: Array<{
             arm: string;
             n: number;
@@ -107,6 +108,10 @@ export interface Snapshot {
         guardrailLine?: string;
         worstArm?: string;
     };
+    health?: Array<{
+        code: 'version-page-unavailable' | 'version-page-unchecked';
+        path: string;
+    }>;
     contentChanges: Array<{
         at: string;
         doc: {

package/dist/ui/Banner.d.ts

@@ -0,0 +1,2 @@
+import './ui.css';
+export { Banner } from './Feedback.js';

package/dist/ui/Banner.js

@@ -0,0 +1,2 @@
+import './ui.css';
+export { Banner } from './Feedback.js';

package/dist/ui/Breadcrumb.d.ts

@@ -0,0 +1,7 @@
+import './ui.css';
+export declare function Breadcrumb({ items }: {
+    items: Array<{
+        label: string;
+        href?: string;
+    }>;
+}): import("react").JSX.Element;