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

package/dist/transitions/checkStart.d.ts

@@ -1,7 +1,7 @@
 import type { Arm, DocId, ExperimentKind, ExposurePolicy, FlagPoint, MetricSource, ResolvedOptions, Status, TargetingRule, UnitType } from '../types/contracts.js';
 import type { ArmIssueCode, PreflightResult } from '../types/endpoints.js';
 import type { BlockPlacement, FlagPlacement } from './placements.js';
-export type ReadinessCode = ArmIssueCode | 'invalid-status' | 'no-planned-duration' | 'no-primary-metric' | 'no-reach-per-day' | 'page-no-targets' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'no-placements' | 'empty-slot' | 'layer-unit-mismatch' | 'layer-full' | 'unknown-metric-source' | 'unit-source-mismatch' | 'undeclared-targeting-key' | 'invalid-targeting-rule';
+export type ReadinessCode = ArmIssueCode | 'invalid-status' | 'no-planned-duration' | 'no-primary-metric' | 'no-reach-per-day' | 'page-no-targets' | 'page-in-use' | 'page-target-unpublished' | 'page-targets-unchecked' | 'version-page-unavailable' | 'version-page-unchecked' | 'page-user-unit' | 'flag-no-point' | 'flag-params-invalid' | 'flag-point-busy' | 'flag-placement-missing' | 'no-placements' | 'empty-slot' | 'make-content-unsupported' | 'layer-unit-mismatch' | 'layer-full' | 'unknown-metric-source' | 'unit-source-mismatch' | 'block-path-rule' | 'undeclared-targeting-key' | 'invalid-targeting-rule';
 export interface StartExperiment {
     id: DocId;
     slug: string;
@@ -38,6 +38,7 @@ export interface StartMetric {
     id: DocId;
     source: string;
 }
+export type PlacementFailure = 'placements-failed' | 'forbidden' | 'not-found';
 export interface CheckStartInput {
     experiment: StartExperiment;
     metrics: StartMetric[];
@@ -45,9 +46,12 @@ export interface CheckStartInput {
     flagPoints?: FlagPoint[];
     placements?: BlockPlacement[];
     flagPlacements?: FlagPlacement[];
-    placementError?: string;
-    flagPlacementError?: string;
+    placementError?: PlacementFailure;
+    flagPlacementError?: PlacementFailure;
     flagPointBusy?: boolean;
+    unpublishedPageTargets?: string[];
+    pageTargetsUnchecked?: boolean;
+    pageTestsInUse?: Pick<StartExperiment, 'id' | 'arms'>[];
     layer?: {
         unitType: UnitType;
         usedSlices: number[];
@@ -58,5 +62,8 @@ export declare const ARM_CHECK_ORDER: readonly ArmIssueCode[];
 export declare const relationshipId: (value: DocId | {
     id: DocId;
 } | null | undefined) => DocId | undefined;
+/** Every path the runtime would match for these arms (pageRewrite, experimentMetadata): any string
+ * pageTarget, holdout included, normalised the same way ('' is '/'). Occupancy and lock keys use this. */
+export declare const pageTargetPaths: (arms: readonly Arm[]) => string[];
 /** Pure Review/Start predicates in refusal order. Inapplicable checks pass. */
 export declare function checkStart(input: CheckStartInput): PreflightResult['checks'];

package/dist/transitions/checkStart.js

@@ -1,4 +1,5 @@
 import { checkArms } from '../collections/experiments/armInvariants.js';
+import { normalisePath } from '../runtime/normalisePath.js';
 import { isOpValid } from '../targeting/ops.js';
 export const ARM_CHECK_ORDER = [
     'weights-total',
@@ -13,6 +14,10 @@ export const ARM_CHECK_ORDER = [
     'duplicate-slot'
 ];
 export const relationshipId = (value)=>value == null ? undefined : typeof value === 'object' ? value.id : value;
+/** Every path the runtime would match for these arms (pageRewrite, experimentMetadata): any string
+ * pageTarget, holdout included, normalised the same way ('' is '/'). Occupancy and lock keys use this. */ export const pageTargetPaths = (arms)=>[
+        ...new Set(arms.filter((arm)=>typeof arm.pageTarget === 'string').map((arm)=>normalisePath(arm.pageTarget)))
+    ].sort();
 const positive = (value)=>typeof value === 'number' && Number.isFinite(value) && value > 0;
 function invalidParams(arms, point) {
     return arms.flatMap((arm)=>{
@@ -56,6 +61,14 @@ function invalidParams(arms, point) {
         'viewport'
     ].includes(e.exposurePolicy) || positive(e.analysis?.reachPerDay));
     add('page-no-targets', e.kind !== 'page' || e.arms.filter((arm)=>arm.kind !== 'holdout').every((arm)=>typeof arm.pageTarget === 'string' && arm.pageTarget.trim().length > 0));
+    const occupiedPaths = new Set((input.pageTestsInUse ?? []).filter((other)=>String(other.id) !== String(e.id)).flatMap((other)=>pageTargetPaths(other.arms)));
+    const sharedPaths = e.kind === 'page' ? pageTargetPaths(e.arms).filter((path)=>occupiedPaths.has(path)) : [];
+    add('page-in-use', sharedPaths.length === 0, {
+        paths: sharedPaths
+    });
+    add('page-target-unpublished', !input.unpublishedPageTargets?.length, input.unpublishedPageTargets?.[0]);
+    add('page-targets-unchecked', true);
+    if (input.pageTargetsUnchecked) checks[checks.length - 1].warning = true;
     add('page-user-unit', e.kind !== 'page' || e.unitType === 'visitor');
     const point = input.flagPoints?.find((point)=>point.id === e.flagPoint);
     add('flag-no-point', e.kind !== 'flag' || !!point);
@@ -72,6 +85,12 @@ function invalidParams(arms, point) {
     add('no-placements', e.kind !== 'block' || !input.placementError && placements.length > 0, input.placementError);
     const empty = placements.filter((placement)=>e.arms.some((arm)=>arm.kind !== 'holdout' && (!arm.slot || !(placement.slots[arm.slot] > 0))));
     add('empty-slot', e.kind !== 'block' || empty.length === 0, empty);
+    add('make-content-unsupported', true);
+    const localized = placements.find((placement)=>placement.localized);
+    if (localized) Object.assign(checks[checks.length - 1], {
+        warning: true,
+        detail: localized.title
+    });
     add('layer-unit-mismatch', e.layer == null || input.layer?.unitType === e.unitType);
     const free = 100 - new Set(input.layer?.usedSlices).size;
     add('layer-full', e.layer == null || !!input.layer && free >= e.allocation, {
@@ -82,6 +101,12 @@ function invalidParams(arms, point) {
     add('unknown-metric-source', unknown.length === 0, unknown);
     const mismatches = input.metrics.filter((metric)=>!metric.source.startsWith('events:') && e.unitType === 'user' && input.metricSources?.some((source)=>source.id === metric.source && source.keyedBy === 'visitor'));
     add('unit-source-mismatch', mismatches.length === 0, mismatches);
+    const pathRules = (e.targeting ?? []).flatMap((rule, index)=>rule.attribute === 'path' ? [
+            index
+        ] : []);
+    add('block-path-rule', e.kind !== 'block' || pathRules.length === 0, {
+        rules: pathRules
+    });
     const undeclared = (e.targeting ?? []).filter((rule)=>!Object.hasOwn(input.attributeKeys ?? {}, rule.attribute));
     add('undeclared-targeting-key', undeclared.length === 0, {
         message: 'Targeting uses an undeclared attribute.',

package/dist/transitions/contentFields.d.ts

@@ -0,0 +1,7 @@
+import type { Block, Field, SanitizedConfig } from 'payload';
+/** Payload keeps both inline definitions and slug references in blockReferences. */
+export declare function contentBlocks(field: Extract<Field, {
+    type: 'blocks';
+}>, blocks?: Block[]): Block[];
+/** Any localized data makes a full-document publish unsafe in Payload 3.90. */
+export declare function hasLocalizedFields(fields: Field[], config: Pick<SanitizedConfig, 'localization' | 'blocks'>, seen?: Set<Field>): boolean;

package/dist/transitions/contentFields.js

@@ -0,0 +1,20 @@
+/** Payload keeps both inline definitions and slug references in blockReferences. */ export function contentBlocks(field, blocks = []) {
+    return [
+        ...field.blocks,
+        ...(field.blockReferences ?? []).flatMap((reference)=>typeof reference === 'string' ? blocks.filter((block)=>block.slug === reference) : [
+                reference
+            ])
+    ];
+}
+/** Any localized data makes a full-document publish unsafe in Payload 3.90. */ export function hasLocalizedFields(fields, config, seen = new Set()) {
+    if (!config.localization) return false;
+    const blocks = config.blocks ?? [];
+    return fields.some((field)=>{
+        if (seen.has(field)) return false;
+        const branch = new Set(seen).add(field);
+        if ('localized' in field && field.localized) return true;
+        if ('tabs' in field && field.tabs.some((tab)=>tab.localized || hasLocalizedFields(tab.fields, config, branch))) return true;
+        if ('fields' in field && hasLocalizedFields(field.fields, config, branch)) return true;
+        return field.type === 'blocks' && contentBlocks(field, blocks).some((block)=>hasLocalizedFields(block.fields, config, branch));
+    });
+}

package/dist/transitions/decide.js

@@ -1,6 +1,9 @@
+import { DEFAULT_SEQUENTIAL_TUNING_PARAMETER } from '../constants.js';
 import { reclaimSlices } from '../db/slices.js';
 import { decideGuard } from '../results/decideGuard.js';
-import { relationshipId } from './checkStart.js';
+import { lockPagePaths } from '../db/locks.js';
+import { routedPageTests } from '../db/pageOccupancy.js';
+import { pageTargetPaths, relationshipId } from './checkStart.js';
 import { expectedConfirm, matchesConfirm, storedWinnerLabel } from './confirmPhrases.js';
 import { withTransition } from './kernel.js';
 import { readPhaseRecord, setPhaseEndedAt, writePhaseRecord } from './phaseRecord.js';
@@ -44,6 +47,19 @@ export async function decide(req, { experimentId, winnerArm, note, confirmation
         }
         const test = await readPhaseRecord(req, experimentId, current.phase);
         if (test.phaseKind !== 'test') refuse('invalid-status');
+        if (current.kind === 'page' && current.status === 'stopped') {
+            // Deciding a stopped page test restores its routing: recheck page occupancy under the
+            // sorted path locks Start takes, so another test that started on these pages meanwhile wins.
+            // The frozen test-round arms are what decide restores; the stopped document's arms may have been edited.
+            const mine = pageTargetPaths(test.arms);
+            await lockPagePaths(exec, mine);
+            // Other tests' routed (frozen-round) arms, as the runtime matches them.
+            const occupied = new Set((await routedPageTests(exec)).filter((other)=>String(other.id) !== String(experimentId)).flatMap((other)=>pageTargetPaths(other.arms)));
+            const shared = mine.filter((path)=>occupied.has(path));
+            if (shared.length) refuse('page-in-use', {
+                paths: shared
+            });
+        }
         const winner = test.arms.find((arm)=>arm.key === winnerArm && arm.kind !== 'holdout');
         if (!winner) refuse('invalid-winner');
         // §7.8: decision snapshot lookup serves the authorised transition.
@@ -112,7 +128,11 @@ export async function decide(req, { experimentId, winnerArm, note, confirmation
                 allocationChanges: [],
                 targeting: test.targeting,
                 metricDefinitions: test.metricDefinitions,
-                analysis: test.analysis,
+                analysis: {
+                    ...test.analysis,
+                    // Older test phases may predate freezing the effective tuning value.
+                    sequentialTuningParameter: test.analysis?.sequentialTuningParameter ?? DEFAULT_SEQUENTIAL_TUNING_PARAMETER
+                },
                 contentChanges: []
             });
         }

package/dist/transitions/dismissContentEntry.d.ts

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

package/dist/transitions/dismissContentEntry.js

@@ -0,0 +1,45 @@
+import { relationshipId } from './checkStart.js';
+import { withTransition } from './kernel.js';
+import { readExperiment, refuse, updateExperiment } from './start.js';
+export async function dismissContentEntry(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.ok !== false) refuse('entry-ok');
+        if (entry.dismissedAt) refuse('entry-dismissed');
+        const docs = report.docs.map((entry, i)=>i === index ? {
+                ...entry,
+                dismissedAt: new Date().toISOString(),
+                dismissedBy: req.user?.id == null ? null : String(req.user.id)
+            } : entry);
+        return updateExperiment(req, experimentId, {
+            decision: {
+                ...decision,
+                contentReport: {
+                    ...report,
+                    docs
+                }
+            }
+        });
+    });
+    req.payload.logger.info({
+        experimentId,
+        collection,
+        id
+    }, 'Experiment content entry dismissed');
+    return {
+        doc
+    };
+}

package/dist/transitions/makeContent.d.ts

@@ -1,11 +1,14 @@
 import { type PayloadRequest } from 'payload';
+import type { ContentReportReason } from '../types/reasons.js';
 import type { DocId, ResolvedOptions } from '../types/contracts.js';
 type ContentDoc = {
     collection: string;
     id: DocId;
     ok: boolean;
-    detail?: string;
-    error?: string;
+    detail?: ContentReportReason;
+    error?: ContentReportReason;
+    dismissedAt?: string;
+    dismissedBy?: string | null;
 };
 export declare function makeContent<TUser extends {
     id: DocId;