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

package/dist/transitions/deleteExperiment.js

@@ -0,0 +1,66 @@
+import { txExecutor } from '../db/executor.js';
+import { deleteExperimentSnapshots, serializeDelete } from '../db/delete.js';
+import { deleteExperimentEvents } from '../db/events.js';
+import { lockTransitionScope } from '../db/locks.js';
+import { buildAndStoreManifest } from '../manifest/compile.js';
+import { readExperiment, refuse } from './start.js';
+/** Payload deleteByID owns the request transaction; never commit inside hooks. */ export async function deleteExperiment(req, experimentId) {
+    await serializeDelete(req, async (state)=>{
+        const exec = txExecutor(req);
+        await lockTransitionScope(exec, {
+            experimentId
+        });
+        const current = await readExperiment(req, experimentId);
+        if (current.status !== 'draft' && current.status !== 'archived') refuse('invalid-status');
+        try {
+            const collection = 'xp-phases';
+            // §7.8 transition exception: cascade while FK references still exist.
+            const { docs } = await req.payload.find({
+                collection,
+                req,
+                overrideAccess: true,
+                depth: 0,
+                limit: 0,
+                where: {
+                    experiment: {
+                        equals: experimentId
+                    }
+                }
+            });
+            // deleteByID throws on a hook failure; bulk delete swallows per-doc errors.
+            for (const doc of docs){
+                // §7.8: privileged plugin cascade shares the access-checked delete's req.
+                await req.payload.delete({
+                    collection,
+                    id: doc.id,
+                    req,
+                    overrideAccess: true
+                });
+            }
+            await deleteExperimentSnapshots(exec, experimentId);
+            await deleteExperimentEvents(exec, experimentId);
+            state.excludedIds.set(String(experimentId), experimentId);
+            const decision = current.decision;
+            if (current.status !== 'archived' || decision?.discardedAt) state.pruneFlagDefaultIds.set(String(experimentId), experimentId);
+        } catch (error) {
+            req.payload.logger.error({
+                experimentId,
+                err: error
+            }, 'Experiment cascade failed; aborting delete');
+            throw error;
+        }
+    });
+}
+export async function deleteExperimentAfter(req, experimentId) {
+    await serializeDelete(req, async (state)=>{
+        await buildAndStoreManifest(req, {
+            excludeIds: [
+                ...state.excludedIds.values(),
+                experimentId
+            ],
+            pruneFlagDefaultIds: [
+                ...state.pruneFlagDefaultIds.values()
+            ]
+        });
+    });
+}

package/dist/transitions/kernel.d.ts

@@ -0,0 +1,31 @@
+import { type PayloadRequest } from 'payload';
+import { type Executor } from '../db/executor.js';
+import type { DocId } from '../types/contracts.js';
+export interface TransitionScope {
+    experimentId: DocId;
+    layerId?: DocId | null;
+    flagPointId?: string | null;
+    /** Defaults to true; content-change audit appends opt out. */
+    bump?: boolean;
+    /** Best-effort content audit only; a borrowed transaction must never be killed here. */
+    audit?: boolean;
+    excludeIds?: DocId[];
+}
+/** Runs transition writes on the request's transaction under ordered locks.
+ * Returns the callback result and, unless bump is false, the stored manifest's
+ * revision. Only the transaction owner commits and verifies that transaction's
+ * status on the pool (even without a bump); a caller-owned transaction still
+ * needs its caller to commit. The explicit borrowed audit path takes only lock E
+ * inside a savepoint. ROLLBACK TO SAVEPOINT releases that transaction advisory
+ * lock (Postgres §13.3); after RELEASE it remains held until the host commits.
+ * Audit failures never kill the host transaction, even if savepoint recovery
+ * itself fails: the host must observe its own failed commit. Other failures kill
+ * even a borrowed transaction. Owned audits follow the ordinary owned path.
+ */
+export declare function withTransition<T>(req: PayloadRequest, scope: TransitionScope, fn: (ctx: {
+    exec: Executor;
+    req: PayloadRequest;
+}) => Promise<T>): Promise<{
+    result: T;
+    revision?: number;
+}>;

package/dist/transitions/kernel.js

@@ -0,0 +1,69 @@
+import { commitTransaction, initTransaction, killTransaction } from 'payload';
+import { pooledExecutor, txExecutor } from '../db/executor.js';
+import { lockTransitionScope } from '../db/locks.js';
+import { currentTxid, txidStatus } from '../db/txid.js';
+import { contentChangeSavepoint } from '../db/appends.js';
+import { XpRefusal } from '../errors.js';
+import { buildAndStoreManifest } from '../manifest/compile.js';
+/** Runs transition writes on the request's transaction under ordered locks.
+ * Returns the callback result and, unless bump is false, the stored manifest's
+ * revision. Only the transaction owner commits and verifies that transaction's
+ * status on the pool (even without a bump); a caller-owned transaction still
+ * needs its caller to commit. The explicit borrowed audit path takes only lock E
+ * inside a savepoint. ROLLBACK TO SAVEPOINT releases that transaction advisory
+ * lock (Postgres §13.3); after RELEASE it remains held until the host commits.
+ * Audit failures never kill the host transaction, even if savepoint recovery
+ * itself fails: the host must observe its own failed commit. Other failures kill
+ * even a borrowed transaction. Owned audits follow the ordinary owned path.
+ */ export async function withTransition(req, scope, fn) {
+    const hadTransition = Object.prototype.hasOwnProperty.call(req.context, 'xpTransition');
+    const previousTransition = req.context.xpTransition;
+    let borrowedAudit = scope.audit === true && req.transactionID != null;
+    try {
+        const owns = await initTransaction(req);
+        borrowedAudit = scope.audit === true && !owns;
+        const exec = txExecutor(req);
+        req.context.xpTransition = true;
+        const work = async ()=>{
+            await lockTransitionScope(exec, scope);
+            return fn({
+                exec,
+                req
+            });
+        };
+        let result;
+        if (borrowedAudit) {
+            const audit = await contentChangeSavepoint(exec, work);
+            if (!audit.ok) {
+                throw audit.error;
+            }
+            result = audit.result;
+        } else result = await work();
+        const revision = scope.bump === false ? undefined : (await buildAndStoreManifest(req, {
+            excludeIds: scope.excludeIds
+        })).revision;
+        if (owns) {
+            const xid = await currentTxid(exec);
+            await commitTransaction(req);
+            const status = await txidStatus(pooledExecutor(req.payload), xid);
+            if (status !== 'committed') {
+                throw new XpRefusal('commit-unverified', 'The transition commit could not be verified.', {
+                    xid,
+                    status
+                }, 500);
+            }
+        }
+        return revision === undefined ? {
+            result
+        } : {
+            result,
+            revision
+        };
+    } catch (error) {
+        if (!borrowedAudit) await killTransaction(req);
+        throw error;
+    } finally{
+        if (hadTransition) req.context.xpTransition = previousTransition;
+        else delete req.context.xpTransition;
+    }
+}

package/dist/transitions/makeContent.d.ts

@@ -0,0 +1,20 @@
+import { type PayloadRequest } from 'payload';
+import type { DocId, ResolvedOptions } from '../types/contracts.js';
+type ContentDoc = {
+    collection: string;
+    id: DocId;
+    ok: boolean;
+    detail?: string;
+    error?: string;
+};
+export declare function makeContent<TUser extends {
+    id: DocId;
+}>(req: PayloadRequest, { experimentId, options }: {
+    experimentId: DocId;
+    options: ResolvedOptions<TUser>;
+}): Promise<{
+    docs: ContentDoc[];
+    doc: import("payload").JsonObject & import("payload").TypeWithID;
+    revision: number;
+}>;
+export {};

package/dist/transitions/makeContent.js

@@ -0,0 +1,411 @@
+import { commitTransaction, initTransaction, killTransaction } from 'payload';
+import { lockContentDefaults } from '../db/appends.js';
+import { pooledExecutor, txExecutor } from '../db/executor.js';
+import { currentTxid, txidStatus } from '../db/txid.js';
+import { buildAndStoreManifest } from '../manifest/compile.js';
+import { puckCollections } from '../options.js';
+import { archive } from './archive.js';
+import { relationshipId } from './checkStart.js';
+import { withTransition } from './kernel.js';
+import { scanBlockPlacements } from './placements.js';
+import { readExperiment, refuse, updateExperiment } from './start.js';
+const object = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Flatten selected slots in every content array, including nested selected slots. */ function unwrap(value, slug, slot) {
+    if (Array.isArray(value)) return value.flatMap((node)=>{
+        if (object(node) && node.type === 'ExperimentSlot' && object(node.props)) {
+            const ref = node.props.experiment;
+            if ((typeof ref === 'string' ? ref : object(ref) ? ref.slug : undefined) === slug) {
+                const content = node.props[slot];
+                if (!Array.isArray(content)) throw new Error('The winning content slot is missing.');
+                return unwrap(content, slug, slot);
+            }
+        }
+        return [
+            unwrap(node, slug, slot)
+        ];
+    });
+    if (object(value)) return Object.fromEntries(Object.entries(value).map(([key, child])=>[
+            key,
+            unwrap(child, slug, slot)
+        ]));
+    return value;
+}
+/** Payload update merges omissions from the latest version even on publish.
+ * Restore each captured document's fields, omitting API/adapter metadata.
+ */ function contentData(doc, field, content) {
+    const metadata = new Set([
+        'id',
+        'createdAt',
+        'updatedAt',
+        '_isLocked',
+        '_userEditing'
+    ]);
+    return {
+        ...Object.fromEntries(Object.entries(doc).filter(([key])=>!metadata.has(key))),
+        [field]: content
+    };
+}
+/** Refuse unsafe collection shapes before rebuilding complete host documents. */ async function fieldRefusal(fields, req, doc, operation = 'read', data = doc, siblingData = data, blockData, seen = new Set()) {
+    for (const field of fields){
+        if (seen.has(field)) continue;
+        const branch = new Set(seen).add(field);
+        if ('localized' in field && field.localized) return 'This page is localized; update it by hand.';
+        if ('hidden' in field && field.hidden === true) return 'This page has hidden fields; update it by hand.';
+        if ('access' in field && field.access?.[operation] && !await field.access[operation]({
+            id: doc.id,
+            req,
+            doc,
+            data,
+            siblingData,
+            blockData
+        })) {
+            return operation === 'read' ? 'This page has fields you cannot read; update it by hand.' : 'This page has fields you cannot update; update it by hand.';
+        }
+        const value = 'name' in field ? siblingData[field.name] : siblingData;
+        if ('tabs' in field) for (const tab of field.tabs){
+            if ('localized' in tab && tab.localized) return 'This page is localized; update it by hand.';
+            if ('hidden' in tab && tab.hidden === true) return 'This page has hidden fields; update it by hand.';
+            if ('access' in tab && tab.access?.[operation] && !await tab.access[operation]({
+                id: doc.id,
+                req,
+                doc,
+                data,
+                siblingData,
+                blockData
+            })) {
+                return operation === 'read' ? 'This page has fields you cannot read; update it by hand.' : 'This page has fields you cannot update; update it by hand.';
+            }
+            const tabData = 'name' in tab && tab.name ? siblingData[tab.name] : siblingData;
+            const refusal = await fieldRefusal(tab.fields, req, doc, operation, data, object(tabData) ? tabData : {}, blockData, branch);
+            if (refusal) return refusal;
+        }
+        if ('fields' in field) for (const row of Array.isArray(value) && value.length ? value : [
+            value
+        ]){
+            const refusal = await fieldRefusal(field.fields, req, doc, operation, data, object(row) ? row : {}, blockData, branch);
+            if (refusal) return refusal;
+        }
+        if (field.type === 'blocks') {
+            const blocks = [
+                ...field.blocks,
+                ...(field.blockReferences ?? []).map((slug)=>req.payload.config.blocks?.find((block)=>block.slug === slug)).filter((block)=>block !== undefined)
+            ];
+            for (const block of blocks){
+                const rows = Array.isArray(value) ? value.filter((row)=>object(row) && row.blockType === block.slug) : [];
+                for (const row of rows.length ? rows : [
+                    {}
+                ]){
+                    const refusal = await fieldRefusal(block.fields, req, doc, operation, data, row, row, branch);
+                    if (refusal) return refusal;
+                }
+            }
+        }
+    }
+}
+/** Each placement commits independently while the outer transition retains its
+ * experiment locks. Keep the manager's exact req/user, temporarily lending it a
+ * fresh transaction; a denied host write must not kill the outer transaction.
+ */ async function hostTransaction(req, fn) {
+    const transactionID = req.transactionID;
+    const transition = req.context.xpTransition;
+    delete req.transactionID;
+    delete req.context.xpTransition;
+    try {
+        if (!await initTransaction(req)) throw new Error('A content transaction could not be started.');
+        await fn();
+        const xid = await currentTxid(txExecutor(req));
+        await commitTransaction(req);
+        if (await txidStatus(pooledExecutor(req.payload), xid) !== 'committed') throw new Error('The content commit could not be verified. Retry to check the saved content.');
+    } catch (error) {
+        await killTransaction(req);
+        throw error;
+    } finally{
+        req.transactionID = transactionID;
+        if (transition === undefined) delete req.context.xpTransition;
+        else req.context.xpTransition = transition;
+    }
+}
+export async function makeContent(req, { experimentId, options }) {
+    const before = await readExperiment(req, experimentId);
+    const { result } = await withTransition(req, {
+        experimentId,
+        layerId: relationshipId(before.layer),
+        flagPointId: before.kind === 'flag' ? before.flagPoint : undefined,
+        bump: false
+    }, async ({ exec })=>{
+        const current = await readExperiment(req, experimentId);
+        if (current.status !== 'decided' || ![
+            'block',
+            'flag',
+            'page'
+        ].includes(current.kind)) refuse('invalid-status');
+        const decision = current.decision;
+        const winner = current.arms.find((arm)=>arm.key === decision?.winnerArm && arm.kind !== 'holdout');
+        if (!winner) refuse('invalid-winner');
+        const docs = [];
+        const attempt = async (collection, id, fn)=>{
+            try {
+                await hostTransaction(req, fn);
+                docs.push({
+                    collection,
+                    id,
+                    ok: true
+                });
+            } catch (error) {
+                const detail = error instanceof Error ? error.message : 'The content could not be updated.';
+                docs.push({
+                    collection,
+                    id,
+                    ok: false,
+                    detail,
+                    error: detail
+                });
+            }
+        };
+        if (current.kind === 'block') {
+            if (!winner.slot) refuse('invalid-winner');
+            const report = decision?.contentReport;
+            const registrations = puckCollections(options);
+            const scanned = [];
+            for (const registration of registrations){
+                const transactionID = req.transactionID;
+                delete req.transactionID;
+                try {
+                    scanned.push(...await scanBlockPlacements(req, {
+                        slug: current.slug,
+                        puckCollections: [
+                            registration
+                        ]
+                    }));
+                } catch (error) {
+                    // A collection made unreadable since the last attempt still has
+                    // retained placements to report below. Never sacrifice the outer tx.
+                    const denied = error && typeof error === 'object' && 'status' in error && error.status === 403;
+                    if (!denied || !report?.docs?.some((doc)=>doc.collection === registration.slug)) throw error;
+                } finally{
+                    req.transactionID = transactionID;
+                }
+            }
+            if (scanned.some((doc)=>doc.locked)) refuse('locked-placement');
+            const placements = new Map();
+            for (const doc of [
+                ...report?.docs ?? [],
+                ...scanned
+            ])placements.set(doc.collection + ':' + doc.id, doc);
+            const skipped = new Set();
+            // Probe with no borrowed transaction: disableErrors handles expected
+            // NotFound/Forbidden, and even a host read hook cannot kill the outer tx.
+            for (const [key, { collection, id }] of placements){
+                const transactionID = req.transactionID;
+                delete req.transactionID;
+                try {
+                    const config = req.payload.config.collections.find((config)=>config.slug === collection);
+                    const access = config?.access?.read ? await config.access.read({
+                        id,
+                        req
+                    }) : true;
+                    const doc = await req.payload.findByID({
+                        collection,
+                        id,
+                        req,
+                        overrideAccess: false,
+                        depth: 0,
+                        draft: true,
+                        includeLockStatus: true,
+                        disableErrors: true
+                    });
+                    if (!doc) {
+                        // Fail closed (exp-orch 16:20): only an unfiltered read proves the page is gone;
+                        // a Where-filtered miss may be a page this manager cannot see.
+                        const ok = access === true || typeof access === 'object' && access !== null && Object.keys(access).length === 0;
+                        const detail = ok ? 'This page no longer exists; nothing to change.' : access === false ? 'You can no longer read this page.' : 'You can no longer read this page. If it was deleted, archive this experiment with discard or hard-coded instead.';
+                        docs.push({
+                            collection,
+                            id,
+                            ok,
+                            detail,
+                            ...!ok ? {
+                                error: detail
+                            } : {}
+                        });
+                        skipped.add(key);
+                    } else if (doc._isLocked === true || doc.locked === true) refuse('locked-placement', {
+                        collection,
+                        id
+                    });
+                } catch (error) {
+                    if (error && typeof error === 'object' && 'code' in error && error.code === 'locked-placement') throw error;
+                    const missing = error && typeof error === 'object' && 'status' in error && error.status === 404;
+                    const detail = missing ? 'This page no longer exists; nothing to change.' : 'You can no longer read this page.';
+                    docs.push({
+                        collection,
+                        id,
+                        ok: Boolean(missing),
+                        detail,
+                        ...!missing ? {
+                            error: detail
+                        } : {}
+                    });
+                    skipped.add(key);
+                } finally{
+                    req.transactionID = transactionID;
+                }
+            }
+            for (const [key, { collection, id }] of placements){
+                if (skipped.has(key)) continue;
+                await attempt(collection, id, async ()=>{
+                    const field = registrations.find((entry)=>entry.slug === collection)?.field;
+                    if (!field) throw new Error('This content collection is no longer configured.');
+                    const draft = await req.payload.findByID({
+                        collection,
+                        id,
+                        req,
+                        overrideAccess: false,
+                        depth: 0,
+                        draft: true
+                    });
+                    const config = req.payload.config.collections.find((config)=>config.slug === collection);
+                    const drafts = Boolean(config?.versions && config.versions.drafts);
+                    const published = drafts ? await req.payload.findByID({
+                        collection,
+                        id,
+                        req,
+                        overrideAccess: false,
+                        depth: 0,
+                        draft: false
+                    }) : draft;
+                    const draftContent = unwrap(draft[field], current.slug, winner.slot);
+                    const publishedContent = unwrap(published[field], current.slug, winner.slot);
+                    const changedDraft = JSON.stringify(draftContent) !== JSON.stringify(draft[field]);
+                    const changedPublished = JSON.stringify(publishedContent) !== JSON.stringify(published[field]);
+                    // Nothing left to rewrite (e.g. an editor already did it by hand): done, before any refusal —
+                    // but only when the content field was really read (not stripped as hidden/unreadable, not localized).
+                    const contentField = topLevelField(config?.fields ?? [], field);
+                    // Payload strips hidden and read-denied fields from a read, so presence in both proves readability;
+                    // a localized content field compares only one locale, so it never takes the shortcut.
+                    const contentReadable = Object.hasOwn(draft, field) && Object.hasOwn(published, field) && !contentField?.localized;
+                    if (contentReadable && !changedDraft && !changedPublished) return;
+                    for (const doc of [
+                        draft,
+                        published
+                    ]){
+                        const refusal = await fieldRefusal(config?.fields ?? [], req, doc);
+                        if (refusal) throw new Error(refusal);
+                    }
+                    const publishedData = contentData(published, field, publishedContent);
+                    const draftData = {
+                        ...contentData(draft, field, draftContent),
+                        _status: 'draft'
+                    };
+                    // Payload beforeValidate receives the latest version as doc, and the
+                    // proposed write as data/siblingData (blockData is the proposed row).
+                    const publicationRefusal = await fieldRefusal(config?.fields ?? [], req, draft, 'update', publishedData);
+                    if (publicationRefusal) throw new Error(publicationRefusal);
+                    if (drafts) {
+                        const draftOriginal = changedPublished ? {
+                            ...published,
+                            ...publishedData
+                        } : draft;
+                        const draftRefusal = await fieldRefusal(config?.fields ?? [], req, draftOriginal, 'update', draftData);
+                        if (draftRefusal) throw new Error(draftRefusal);
+                    }
+                    // Host writes are access checked with the manager's req (§7.8).
+                    if (changedPublished) await req.payload.update({
+                        collection,
+                        id,
+                        req,
+                        overrideAccess: false,
+                        overrideLock: false,
+                        draft: false,
+                        data: publishedData
+                    });
+                    if (drafts) await req.payload.update({
+                        collection,
+                        id,
+                        req,
+                        overrideAccess: false,
+                        overrideLock: false,
+                        draft: true,
+                        data: draftData
+                    });
+                });
+            }
+        } else if (current.kind === 'flag') {
+            const point = options.flagPoints?.find((point)=>point.id === current.flagPoint);
+            if (!point) refuse('flag-no-point');
+            if (point.makeContent) await attempt('xp-experiments', experimentId, ()=>point.makeContent({
+                    experimentId,
+                    winner: {
+                        arm: winner.key,
+                        params: winner.params ?? {}
+                    },
+                    req
+                }));
+            // Lock the shared state before its read/modify/write, after L/F/E.
+            await lockContentDefaults(exec);
+            // §7.8 transition exception: durable made-content defaults in plugin state.
+            const state = await req.payload.findGlobal({
+                slug: 'xp-state',
+                req,
+                overrideAccess: true,
+                depth: 0
+            });
+            // §7.8 transition exception: host documents above always use false.
+            await req.payload.updateGlobal({
+                slug: 'xp-state',
+                req,
+                overrideAccess: true,
+                data: {
+                    flagDefaults: {
+                        ...state.flagDefaults ?? {},
+                        [point.id]: {
+                            winnerArm: winner.key,
+                            params: winner.params ?? {},
+                            experiment: experimentId,
+                            decidedAt: current.decidedAt
+                        }
+                    }
+                }
+            });
+        }
+        const doc = await updateExperiment(req, experimentId, {
+            decision: {
+                ...decision,
+                contentReport: {
+                    docs
+                }
+            }
+        });
+        if (docs.every((doc)=>doc.ok)) return {
+            ...await archive(req, {
+                experimentId,
+                mode: 'after-content'
+            }),
+            docs
+        };
+        const manifest = await buildAndStoreManifest(req);
+        return {
+            doc,
+            revision: manifest.revision,
+            docs
+        };
+    });
+    return result;
+}
+/** The top-level data field with this name, looking through unnamed rows, collapsibles and tabs. */ function topLevelField(fields, name) {
+    for (const raw of fields){
+        const field = raw;
+        if (field.name === name) return field;
+        if (!field.name && (field.type === 'row' || field.type === 'collapsible') && field.fields) {
+            const found = topLevelField(field.fields, name);
+            if (found) return found;
+        }
+        if (field.type === 'tabs') {
+            for (const tab of field.tabs ?? [])if (!tab.name && tab.fields) {
+                const found = topLevelField(tab.fields, name);
+                if (found) return found;
+            }
+        }
+    }
+    return undefined;
+}

package/dist/transitions/phaseRecord.d.ts

@@ -0,0 +1,27 @@
+import type { PayloadRequest } from 'payload';
+import type { Arm, DocId, TargetingRule } from '../types/contracts.js';
+import type { AllocationChange, ContentChange } from '../db/appends.js';
+export interface PhaseRecord {
+    experiment: DocId;
+    phase: number;
+    phaseKind: 'test' | 'rollout';
+    startedAt: string;
+    endedAt?: string | null;
+    seed: string;
+    arms: Arm[];
+    allocation: number;
+    allocationChanges?: AllocationChange[];
+    targeting: TargetingRule[];
+    metricDefinitions?: Array<Record<string, unknown>>;
+    analysis?: Record<string, unknown>;
+    contentChanges?: ContentChange[];
+}
+export declare function readPhaseRecord(req: PayloadRequest, experimentId: DocId, phase: number): Promise<PhaseRecord & {
+    id: DocId;
+}>;
+/** Caller holds the experiment lock and passes the kernel's transaction req. */
+export declare function writePhaseRecord(req: PayloadRequest, record: PhaseRecord): Promise<import("payload").JsonObject & import("payload").TypeWithID>;
+/** End only an open phase, preserving the original stop time on a later decide.
+ * Caller holds the experiment lock and passes the kernel's transaction req.
+ */
+export declare function setPhaseEndedAt(req: PayloadRequest, experimentId: DocId, phase: number, at: string): Promise<import("payload").JsonObject & import("payload").TypeWithID>;