@delmaredigital/payload-experiments 0.0.0-stage → 0.1.0-rc.6

package/dist/transitions/addMetric.js

@@ -0,0 +1,126 @@
+import { readState } from '../db/state.js';
+import { XpRefusal } from '../errors.js';
+import { relationshipId } from './checkStart.js';
+import { withTransition } from './kernel.js';
+import { readExperiment, refuse, updateExperiment } from './start.js';
+import { resolveCaps } from './resolveCaps.js';
+export async function addMetric(req, { experimentId, metric, role, options }) {
+    if (role !== 'secondary' && role !== 'guardrail') refuse('invalid-body');
+    const before = await readExperiment(req, experimentId);
+    if (before.status !== 'running') refuse('invalid-status');
+    const found = await req.payload.find({
+        collection: 'xp-metrics',
+        req,
+        overrideAccess: false,
+        depth: 0,
+        limit: 1,
+        where: {
+            id: {
+                equals: metric
+            }
+        }
+    });
+    if (!found.docs[0]) throw new XpRefusal('not-found', 'Metric not found', undefined, 404);
+    const metricId = found.docs[0].id;
+    const at = new Date();
+    // §5.4: cap history ends at the phase start, never inside the running phase.
+    const started = before.startedAt;
+    const startedAt = typeof started === 'string' ? new Date(started) : at;
+    const caps = await resolveCaps([
+        found.docs[0]
+    ], options.metricSources ?? [], startedAt);
+    // Metrics are analysis-only; the assignment manifest is unchanged, so no bump.
+    const { result } = await withTransition(req, {
+        experimentId,
+        bump: false
+    }, async ({ req, exec })=>{
+        const current = await readExperiment(req, experimentId);
+        if (current.status !== 'running') refuse('invalid-status');
+        const ids = [
+            current.metrics?.primary,
+            ...current.metrics?.secondary ?? [],
+            ...current.metrics?.guardrails ?? []
+        ].map(relationshipId);
+        if (ids.some((id)=>id !== undefined && String(id) === String(metric))) refuse('duplicate-metric', {
+            message: 'This metric is already part of the experiment.'
+        });
+        const definition = caps.definitions[0];
+        if (current.unitType === 'user' && definition.keyedBy === 'visitor' && !definition.source.startsWith('events:')) refuse('unit-source-mismatch');
+        // §7.8: phase lookup serves the access-authorised transition write.
+        const phases = await req.payload.find({
+            collection: 'xp-phases',
+            req,
+            overrideAccess: true,
+            depth: 0,
+            limit: 1,
+            where: {
+                and: [
+                    {
+                        experiment: {
+                            equals: experimentId
+                        }
+                    },
+                    {
+                        phase: {
+                            equals: current.phase
+                        }
+                    }
+                ]
+            }
+        });
+        const phase = phases.docs[0];
+        if (!phase) throw new XpRefusal('not-found', 'The phase record was not found.', undefined, 404);
+        // §7.8: append one frozen metric definition under the experiment lock.
+        const analysis = phase.analysis;
+        await req.payload.update({
+            collection: 'xp-phases',
+            req,
+            overrideAccess: true,
+            id: phase.id,
+            data: {
+                analysis: {
+                    ...analysis,
+                    minSampleSizes: {
+                        ...analysis?.minSampleSizes,
+                        [metricId]: definition.minSampleSize ?? 150
+                    },
+                    ...role === 'guardrail' ? {
+                        guardrailThresholds: {
+                            ...analysis?.guardrailThresholds,
+                            [metricId]: definition.guardrailThreshold ?? 0.05
+                        }
+                    } : {}
+                },
+                metricDefinitions: [
+                    ...phase.metricDefinitions ?? [],
+                    {
+                        ...definition,
+                        metricId,
+                        role,
+                        addedAt: at.toISOString()
+                    }
+                ]
+            }
+        });
+        const field = role === 'guardrail' ? 'guardrails' : 'secondary';
+        const doc = await updateExperiment(req, experimentId, {
+            metrics: {
+                ...current.metrics,
+                [field]: [
+                    ...current.metrics?.[field] ?? [],
+                    metricId
+                ]
+            }
+        });
+        return {
+            doc,
+            revision: (await readState(exec))?.revision ?? 0
+        };
+    });
+    return {
+        ...result,
+        ...caps.detail.length ? {
+            detail: caps.detail
+        } : {}
+    };
+}

package/dist/transitions/allocate.d.ts

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

package/dist/transitions/allocate.js

@@ -0,0 +1,84 @@
+import { XpRefusal } from '../errors.js';
+import { appendAllocationChange } from '../db/appends.js';
+import { claimSlices } from '../db/slices.js';
+import { relationshipId } from './checkStart.js';
+import { withTransition } from './kernel.js';
+import { readExperiment, refuse, updateExperiment } from './start.js';
+export async function allocate(req, { experimentId, allocation }) {
+    if (!Number.isInteger(allocation) || allocation < 1 || allocation > 100) refuse('invalid-body');
+    const before = await readExperiment(req, experimentId);
+    const { result: doc, revision } = await withTransition(req, {
+        experimentId,
+        layerId: relationshipId(before.layer)
+    }, async ({ req, exec })=>{
+        const current = await readExperiment(req, experimentId);
+        if (current.status !== 'running') refuse('invalid-status');
+        if (allocation <= current.allocation) refuse('allocation-lower');
+        const layerId = relationshipId(current.layer);
+        const layerSlices = layerId === undefined ? [] : [
+            ...current.layerSlices ?? [],
+            ...await claimSlices(exec, {
+                layerId,
+                experimentId,
+                count: allocation - current.allocation
+            })
+        ].sort((a, b)=>a - b);
+        await appendAllocationChange(exec, {
+            experimentId,
+            phase: current.phase,
+            entry: {
+                at: new Date().toISOString(),
+                from: current.allocation,
+                to: allocation
+            }
+        });
+        // The compiler reads coverage from the phase, so keep its current allocation
+        // in sync while allocationChanges retains the full audit trail.
+        // §7.8: phase lookup for the transition write.
+        const phases = await req.payload.find({
+            collection: 'xp-phases',
+            req,
+            overrideAccess: true,
+            depth: 0,
+            limit: 1,
+            where: {
+                and: [
+                    {
+                        experiment: {
+                            equals: experimentId
+                        }
+                    },
+                    {
+                        phase: {
+                            equals: current.phase
+                        }
+                    }
+                ]
+            }
+        });
+        if (!phases.docs[0]) throw new XpRefusal('not-found', 'The phase record was not found.', undefined, 404);
+        // §7.8: transition writes the phase's widened coverage.
+        await req.payload.update({
+            collection: 'xp-phases',
+            req,
+            overrideAccess: true,
+            id: phases.docs[0].id,
+            data: {
+                allocation,
+                analysis: {
+                    ...phases.docs[0].analysis,
+                    layerSlices
+                }
+            }
+        });
+        // Preserve seed, arms and existing slices: only coverage widens.
+        return updateExperiment(req, experimentId, {
+            allocation,
+            layerSlices
+        });
+    });
+    return {
+        doc,
+        revision: revision
+    };
+}

package/dist/transitions/archive.d.ts

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

package/dist/transitions/archive.js

@@ -0,0 +1,46 @@
+import { relationshipId } from './checkStart.js';
+import { expectedConfirm, matchesConfirm, storedWinnerLabel } from './confirmPhrases.js';
+import { withTransition } from './kernel.js';
+import { setPhaseEndedAt } from './phaseRecord.js';
+import { readExperiment, refuse, updateExperiment } from './start.js';
+export async function archive(req, { experimentId, mode, confirmation }) {
+    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 (mode === 'stopped' ? current.status !== 'stopped' : current.status !== 'decided') refuse('invalid-status');
+        if (mode === 'hard-coded' && current.kind !== 'code') refuse('invalid-status');
+        if (mode === 'after-content') {
+            const report = decision?.contentReport;
+            const docs = Array.isArray(report) ? report : report?.docs;
+            if (!Array.isArray(docs) || !docs.every((doc)=>doc?.ok === true)) refuse('invalid-status');
+        }
+        if (mode === 'discard' && !matchesConfirm(expectedConfirm('discard', ''), confirmation)) refuse('confirmation-required');
+        if (mode === 'hard-coded') {
+            const winner = current.arms.find((arm)=>arm.key === decision?.winnerArm && arm.kind !== 'holdout');
+            if (!winner) refuse('invalid-winner');
+            if (!matchesConfirm(expectedConfirm('hard-coded', storedWinnerLabel(winner)), confirmation)) refuse('confirmation-required');
+        }
+        const at = new Date().toISOString();
+        await setPhaseEndedAt(req, experimentId, current.phase, at);
+        return updateExperiment(req, experimentId, {
+            status: 'archived',
+            archivedAt: at,
+            layerSlices: [],
+            ...mode === 'discard' ? {
+                decision: {
+                    ...decision,
+                    winnerArm: null,
+                    discardedAt: at
+                }
+            } : {}
+        });
+    });
+    return {
+        doc,
+        revision: revision
+    };
+}

package/dist/transitions/checkStart.d.ts

@@ -0,0 +1,61 @@
+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 interface StartExperiment {
+    id: DocId;
+    slug: string;
+    status: Status;
+    kind: ExperimentKind;
+    unitType: UnitType;
+    arms: Arm[];
+    allocation: number;
+    exposurePolicy: ExposurePolicy;
+    flagPoint?: string | null;
+    layer?: DocId | {
+        id: DocId;
+    } | null;
+    targeting?: TargetingRule[] | null;
+    metrics?: {
+        primary?: DocId | {
+            id: DocId;
+        } | null;
+        secondary?: Array<DocId | {
+            id: DocId;
+        }> | null;
+        guardrails?: Array<DocId | {
+            id: DocId;
+        }> | null;
+    } | null;
+    analysis?: {
+        plannedDurationDays?: number | null;
+        reachPerDay?: number | null;
+        sequentialTuningParameter?: number | null;
+        method?: string | null;
+    } | null;
+}
+export interface StartMetric {
+    id: DocId;
+    source: string;
+}
+export interface CheckStartInput {
+    experiment: StartExperiment;
+    metrics: StartMetric[];
+    metricSources?: Pick<MetricSource, 'id' | 'keyedBy'>[];
+    flagPoints?: FlagPoint[];
+    placements?: BlockPlacement[];
+    flagPlacements?: FlagPlacement[];
+    placementError?: string;
+    flagPlacementError?: string;
+    flagPointBusy?: boolean;
+    layer?: {
+        unitType: UnitType;
+        usedSlices: number[];
+    } | null;
+    attributeKeys?: ResolvedOptions['attributeKeys'];
+}
+export declare const ARM_CHECK_ORDER: readonly ArmIssueCode[];
+export declare const relationshipId: (value: DocId | {
+    id: DocId;
+} | null | undefined) => DocId | undefined;
+/** Pure Review/Start predicates in refusal order. Inapplicable checks pass. */
+export declare function checkStart(input: CheckStartInput): PreflightResult['checks'];

package/dist/transitions/checkStart.js

@@ -0,0 +1,104 @@
+import { checkArms } from '../collections/experiments/armInvariants.js';
+import { isOpValid } from '../targeting/ops.js';
+export const ARM_CHECK_ORDER = [
+    'weights-total',
+    'control-count',
+    'control-first',
+    'holdout-count',
+    'holdout-last',
+    'variant-count',
+    'invalid-key',
+    'duplicate-key',
+    'slot-required',
+    'duplicate-slot'
+];
+export const relationshipId = (value)=>value == null ? undefined : typeof value === 'object' ? value.id : value;
+const positive = (value)=>typeof value === 'number' && Number.isFinite(value) && value > 0;
+function invalidParams(arms, point) {
+    return arms.flatMap((arm)=>{
+        // Holdouts render the control's effective defaults and have no params of their own.
+        if (arm.kind === 'holdout') return [];
+        const params = arm.params ?? {};
+        return Object.entries(point.params).flatMap(([key, field])=>{
+            const value = params[key];
+            const missing = value == null || value === '';
+            const invalid = missing ? field.required === true : field.type === 'number' ? typeof value !== 'number' || !Number.isFinite(value) || field.min !== undefined && value < field.min || field.max !== undefined && value > field.max : field.type === 'checkbox' ? typeof value !== 'boolean' : field.type === 'select' ? !field.options?.some((option)=>option.value === value) : typeof value !== 'string' || field.required === true && !value.trim();
+            return invalid ? [
+                {
+                    arm: arm.key,
+                    field: key
+                }
+            ] : [];
+        });
+    });
+}
+/** Pure Review/Start predicates in refusal order. Inapplicable checks pass. */ export function checkStart(input) {
+    const { experiment: e } = input;
+    const checks = [];
+    const add = (code, ok, detail)=>checks.push({
+            code,
+            ok,
+            ...!ok && detail !== undefined ? {
+                detail
+            } : {}
+        });
+    add('invalid-status', e.status === 'draft' || e.status === 'stopped');
+    const issues = checkArms(e.arms, e.kind);
+    for (const code of ARM_CHECK_ORDER){
+        const matches = issues.filter((issue)=>issue.code === code);
+        add(code, matches.length === 0, matches);
+    }
+    add('no-planned-duration', positive(e.analysis?.plannedDurationDays));
+    const primary = relationshipId(e.metrics?.primary);
+    add('no-primary-metric', primary !== undefined && input.metrics.some((metric)=>String(metric.id) === String(primary)));
+    add('no-reach-per-day', ![
+        'manual',
+        '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));
+    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);
+    const params = e.kind === 'flag' && point ? invalidParams(e.arms, point) : [];
+    add('flag-params-invalid', params.length === 0, params);
+    add('flag-point-busy', e.kind !== 'flag' || !input.flagPointBusy);
+    const missing = input.flagPlacements === undefined ? [] : e.arms.filter((arm)=>arm.kind !== 'holdout' && !input.flagPlacements.some((placement)=>placement.arm === arm.key && placement.ok));
+    const failed = input.flagPlacements?.filter((placement)=>!placement.ok) ?? [];
+    add('flag-placement-missing', e.kind !== 'flag' || !input.flagPlacementError && missing.length === 0 && failed.length === 0, input.flagPlacementError ?? {
+        missing: missing.map((arm)=>arm.key),
+        placements: failed
+    });
+    const placements = input.placements ?? [];
+    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('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, {
+        available: free,
+        requested: e.allocation
+    });
+    const unknown = input.metrics.filter((metric)=>!metric.source.startsWith('events:') && !input.metricSources?.some((source)=>source.id === metric.source));
+    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 undeclared = (e.targeting ?? []).filter((rule)=>!Object.hasOwn(input.attributeKeys ?? {}, rule.attribute));
+    add('undeclared-targeting-key', undeclared.length === 0, {
+        message: 'Targeting uses an undeclared attribute.',
+        attributes: undeclared.map((rule)=>rule.attribute)
+    });
+    const invalidRules = (e.targeting ?? []).filter((rule)=>{
+        const type = Object.hasOwn(input.attributeKeys ?? {}, rule.attribute) ? input.attributeKeys[rule.attribute].type : undefined;
+        if (!type) return false // Report undeclared keys through their own refusal.
+        ;
+        const validValue = type === 'string' && [
+            'in',
+            'nin'
+        ].includes(rule.op) ? Array.isArray(rule.value) && rule.value.length > 0 && rule.value.every((value)=>typeof value === 'string') : typeof rule.value === type && (type !== 'number' || Number.isFinite(rule.value));
+        return !isOpValid(type, rule.op) || !validValue;
+    });
+    add('invalid-targeting-rule', invalidRules.length === 0, {
+        attributes: invalidRules.map((rule)=>rule.attribute)
+    });
+    return checks;
+}

package/dist/transitions/confirmPhrases.d.ts

@@ -0,0 +1,5 @@
+export declare function expectedConfirm(action: 'decide' | 'discard' | 'hard-coded', winnerLabel: string): string;
+export declare function matchesConfirm(expected: string, typed: string | undefined | null): boolean;
+import type { Arm } from '../types/contracts.js';
+/** Confirmation uses the stored editor label, with fixed vocabulary as fallback. */
+export declare function storedWinnerLabel(arm: Arm): string;

package/dist/transitions/confirmPhrases.js

@@ -0,0 +1,18 @@
+export function expectedConfirm(action, winnerLabel) {
+    if (action === 'decide') return winnerLabel;
+    if (action === 'discard') return 'discard winner';
+    return `the developer has hard-coded ${winnerLabel}`;
+}
+export function matchesConfirm(expected, typed) {
+    const phrase = expected.trim();
+    return phrase !== '' && typed != null && typed.trim() === phrase;
+}
+/** Confirmation uses the stored editor label, with fixed vocabulary as fallback. */ export function storedWinnerLabel(arm) {
+    return arm.label?.trim() || ({
+        control: 'Original',
+        variantA: 'Variant A',
+        variantB: 'Variant B',
+        variantC: 'Variant C',
+        holdout: 'Holdout'
+    })[arm.key];
+}

package/dist/transitions/decide.d.ts

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

package/dist/transitions/decide.js

@@ -0,0 +1,138 @@
+import { reclaimSlices } from '../db/slices.js';
+import { decideGuard } from '../results/decideGuard.js';
+import { relationshipId } from './checkStart.js';
+import { expectedConfirm, matchesConfirm, storedWinnerLabel } from './confirmPhrases.js';
+import { withTransition } from './kernel.js';
+import { readPhaseRecord, setPhaseEndedAt, writePhaseRecord } from './phaseRecord.js';
+import { readExperiment, refuse, updateExperiment } from './start.js';
+export async function decide(req, { experimentId, winnerArm, note, confirmation }) {
+    const before = await readExperiment(req, experimentId);
+    const { result: doc, revision } = await withTransition(req, {
+        experimentId,
+        layerId: relationshipId(before.layer),
+        flagPointId: before.kind === 'flag' ? before.flagPoint : undefined
+    }, async ({ req, exec })=>{
+        const current = await readExperiment(req, experimentId);
+        if (current.status !== 'running' && current.status !== 'stopped') refuse('invalid-status');
+        if (current.kind === 'flag' && current.flagPoint) {
+            // §7.8: recheck point occupancy under its lock before restoring live routing.
+            const busy = await req.payload.find({
+                collection: 'xp-experiments',
+                req,
+                overrideAccess: true,
+                depth: 0,
+                limit: 0,
+                where: {
+                    and: [
+                        {
+                            flagPoint: {
+                                equals: current.flagPoint
+                            }
+                        },
+                        {
+                            status: {
+                                in: [
+                                    'running',
+                                    'decided'
+                                ]
+                            }
+                        }
+                    ]
+                }
+            });
+            if (busy.docs.some((doc)=>String(doc.id) !== String(experimentId))) refuse('flag-point-busy');
+        }
+        const test = await readPhaseRecord(req, experimentId, current.phase);
+        if (test.phaseKind !== 'test') refuse('invalid-status');
+        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.
+        const snapshots = await req.payload.find({
+            collection: 'xp-results-snapshots',
+            req,
+            overrideAccess: true,
+            depth: 0,
+            limit: 1,
+            where: {
+                and: [
+                    {
+                        experiment: {
+                            equals: experimentId
+                        }
+                    },
+                    {
+                        phase: {
+                            equals: test.phase
+                        }
+                    }
+                ]
+            },
+            sort: [
+                '-computedAt',
+                '-id'
+            ]
+        });
+        const snapshotDoc = snapshots.docs[0];
+        const snapshot = snapshotDoc?.snapshot;
+        if (decideGuard(snapshot ?? null, winnerArm) && (!note?.trim() || !matchesConfirm(expectedConfirm('decide', storedWinnerLabel(winner)), confirmation))) refuse('confirmation-required');
+        const at = new Date().toISOString();
+        const holdout = test.arms.find((arm)=>arm.kind === 'holdout');
+        const rollout = holdout !== undefined && winner.kind !== 'control';
+        let slices = current.layerSlices ?? [];
+        if (rollout && current.status === 'stopped' && relationshipId(current.layer) !== undefined) {
+            const original = test.analysis?.layerSlices;
+            if (!Array.isArray(original) || original.length !== test.allocation || !original.every((slice)=>Number.isInteger(slice) && slice >= 0 && slice < 100) || new Set(original).size !== original.length) refuse('slices-taken');
+            slices = await reclaimSlices(exec, {
+                layerId: relationshipId(current.layer),
+                experimentId,
+                slices: original
+            });
+        }
+        await setPhaseEndedAt(req, experimentId, test.phase, at);
+        const phase = rollout ? test.phase + 1 : test.phase;
+        if (rollout) {
+            const arms = [
+                {
+                    ...winner,
+                    weight: 100 - holdout.weight
+                },
+                {
+                    ...holdout,
+                    weight: holdout.weight
+                }
+            ];
+            await writePhaseRecord(req, {
+                experiment: experimentId,
+                phase,
+                phaseKind: 'rollout',
+                startedAt: at,
+                seed: test.seed,
+                arms,
+                allocation: test.allocation,
+                allocationChanges: [],
+                targeting: test.targeting,
+                metricDefinitions: test.metricDefinitions,
+                analysis: test.analysis,
+                contentChanges: []
+            });
+        }
+        return updateExperiment(req, experimentId, {
+            status: 'decided',
+            phase,
+            seed: test.seed,
+            decidedAt: at,
+            layerSlices: rollout ? slices : [],
+            decision: {
+                winnerArm,
+                verdictCode: snapshot?.verdict.code ?? 'unavailable',
+                note: note?.trim() ?? null,
+                decidedBy: req.user?.id == null ? null : String(req.user.id),
+                snapshotId: snapshotDoc ? String(snapshotDoc.id) : null
+            }
+        });
+    });
+    return {
+        doc,
+        revision: revision
+    };
+}

package/dist/transitions/deleteExperiment.d.ts

@@ -0,0 +1,5 @@
+import type { PayloadRequest } from 'payload';
+import type { DocId } from '../types/contracts.js';
+/** Payload deleteByID owns the request transaction; never commit inside hooks. */
+export declare function deleteExperiment(req: PayloadRequest, experimentId: DocId): Promise<void>;
+export declare function deleteExperimentAfter(req: PayloadRequest, experimentId: DocId): Promise<void>;