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

package/dist/manifest/compile.js

@@ -0,0 +1,237 @@
+import { txExecutor } from '../db/executor.js';
+import { bumpRevision, writeManifest } from '../db/state.js';
+import { XpRefusal } from '../errors.js';
+import { xpOptionsFromReq } from '../options/fromReq.js';
+export async function loadManifestInputs(req, { excludeIds = [], pruneFlagDefaultIds = [] } = {}) {
+    // §7.8 manifest reads: transitions compile all live/archived routing state.
+    const result = await req.payload.find({
+        collection: 'xp-experiments',
+        req,
+        overrideAccess: true,
+        depth: 1,
+        limit: 0,
+        where: {
+            status: {
+                in: [
+                    'running',
+                    'decided',
+                    'archived'
+                ]
+            }
+        }
+    });
+    const excluded = new Set(excludeIds.map(String));
+    const experiments = [];
+    for (const doc of result.docs){
+        if (excluded.has(String(doc.id))) continue;
+        // §7.8 manifest reads: archived routing needs all arms from the last test,
+        // while active assignment uses the current immutable phase.
+        const phases = await req.payload.find({
+            collection: 'xp-phases',
+            req,
+            overrideAccess: true,
+            depth: 0,
+            limit: 1,
+            where: {
+                experiment: {
+                    equals: doc.id
+                },
+                ...doc.status === 'archived' ? {
+                    phaseKind: {
+                        equals: 'test'
+                    }
+                } : {}
+            },
+            sort: '-phase'
+        });
+        const rollout = phases.docs[0]?.phaseKind === 'rollout';
+        // §7.8 manifest reads: runtime rollout ranges use the test's full weights (including their exact
+        // floating-point sum) and its control content. The rollout record has only
+        // winner + holdout; never reconstruct the holdout boundary from those weights.
+        const test = rollout ? await req.payload.find({
+            collection: 'xp-phases',
+            req,
+            overrideAccess: true,
+            depth: 0,
+            limit: 1,
+            where: {
+                experiment: {
+                    equals: doc.id
+                },
+                phaseKind: {
+                    equals: 'test'
+                }
+            },
+            sort: '-phase'
+        }) : null;
+        if (rollout && !test?.docs[0]) throw new Error('Missing test phase for rollout ' + doc.id);
+        experiments.push({
+            ...doc,
+            currentPhase: doc.status === 'archived' ? null : phases.docs[0] ?? null,
+            ...doc.status === 'archived' ? {
+                lastTestPhase: phases.docs[0] ?? null
+            } : {},
+            ...rollout ? {
+                lastTestPhase: test.docs[0]
+            } : {}
+        });
+    }
+    // §7.8 manifest reads: defaults are part of the private compiled manifest.
+    const state = await req.payload.findGlobal({
+        slug: 'xp-state',
+        req,
+        overrideAccess: true,
+        depth: 0
+    });
+    return {
+        experiments,
+        flagDefaults: state.flagDefaults ?? {},
+        excludeIds,
+        pruneFlagDefaultIds
+    };
+}
+/** The builder has already acquired the state lock with bumpRevision. */ async function pruneDeletedDefaults(req, inputs) {
+    if (!inputs.pruneFlagDefaultIds?.length) return;
+    const excluded = new Set(inputs.pruneFlagDefaultIds.map(String));
+    const defaults = Object.fromEntries(Object.entries(inputs.flagDefaults).filter(([, value])=>!excluded.has(String(value.experiment))));
+    if (Object.keys(defaults).length === Object.keys(inputs.flagDefaults).length) return;
+    // §7.8 transition write: keep delete exclusions durable under the state
+    // lock, so a later unrelated compilation cannot restore deleted defaults.
+    await req.payload.updateGlobal({
+        slug: 'xp-state',
+        req,
+        overrideAccess: true,
+        data: {
+            flagDefaults: defaults
+        }
+    });
+    inputs.flagDefaults = defaults;
+}
+/** Pure compiler. Assignment config comes exclusively from the frozen phase. */ export function compileManifest(inputs, revision, { attributeKeys, onInvalid } = {}) {
+    const excluded = new Set(inputs.excludeIds?.map(String));
+    const prunedDefaults = new Set(inputs.pruneFlagDefaultIds?.map(String));
+    const manifest = {
+        v: 1,
+        revision,
+        experiments: [],
+        flagDefaults: {},
+        archivedWinners: {},
+        archivedPages: {}
+    };
+    for (const [point, value] of Object.entries(inputs.flagDefaults)){
+        if (!prunedDefaults.has(String(value.experiment))) manifest.flagDefaults[point] = structuredClone(value);
+    }
+    for (const experiment of inputs.experiments){
+        if (excluded.has(String(experiment.id))) continue;
+        const { decision, currentPhase: phase } = experiment;
+        if (experiment.status === 'archived') {
+            if (!decision?.winnerArm || decision.discardedAt) continue;
+            const testPhase = experiment.lastTestPhase ?? (phase?.phaseKind === 'test' ? phase : null);
+            if (!testPhase) throw new XpRefusal('invalid-status', `Missing last test phase for experiment ${experiment.slug}`, undefined, 409);
+            const winner = testPhase.arms.find((arm)=>arm.key === decision.winnerArm);
+            if (experiment.kind === 'block' && winner?.slot) manifest.archivedWinners[experiment.slug] = winner.slot;
+            if (experiment.kind === 'page' && winner?.pageTarget) {
+                for (const arm of testPhase.arms){
+                    if (arm.pageTarget && arm.pageTarget !== winner.pageTarget) {
+                        manifest.archivedPages[arm.pageTarget] = {
+                            slug: experiment.slug,
+                            winnerPath: winner.pageTarget
+                        };
+                    }
+                }
+            }
+            continue;
+        }
+        if (experiment.status !== 'running' && experiment.status !== 'decided') continue;
+        if (!phase) throw new Error(`Missing current phase for experiment ${experiment.slug}`);
+        const targeting = [];
+        for (const rule of phase.targeting ?? []){
+            // Legacy phases have no stored type. Only those consult today's registry.
+            const type = rule.type ?? (attributeKeys && Object.hasOwn(attributeKeys, rule.attribute) ? attributeKeys[rule.attribute]?.type : undefined);
+            if (type !== 'string' && type !== 'number' && type !== 'boolean') break;
+            targeting.push({
+                attribute: rule.attribute,
+                op: rule.op,
+                value: rule.value,
+                type
+            });
+        }
+        if (targeting.length !== (phase.targeting ?? []).length) {
+            onInvalid?.(experiment.slug, 'untyped-targeting-rule');
+            continue;
+        }
+        const rollout = experiment.status === 'decided' && phase.phaseKind === 'rollout' && !phase.endedAt && !decision?.holdoutReleasedAt;
+        let layer;
+        if ((experiment.status === 'running' || rollout) && experiment.layer != null) {
+            if (typeof experiment.layer !== 'object' || typeof experiment.layer.slug !== 'string' || !experiment.layer.slug || !Array.isArray(experiment.layerSlices)) {
+                throw new XpRefusal('invalid-status', `Incomplete layer configuration for experiment ${experiment.slug}`, undefined, 409);
+            }
+            layer = {
+                slug: experiment.layer.slug,
+                slices: experiment.layerSlices
+            };
+        }
+        const compiled = {
+            id: experiment.id,
+            slug: experiment.slug,
+            kind: experiment.kind,
+            unitType: experiment.unitType,
+            status: experiment.status,
+            phase: phase.phase,
+            phaseKind: rollout ? 'rollout' : 'test',
+            seed: phase.seed,
+            coverage: layer || experiment.status === 'decided' && !rollout ? 1 : phase.allocation / 100,
+            arms: (phase.phaseKind === 'rollout' ? experiment.lastTestPhase?.arms ?? phase.arms : phase.arms).map(({ key, kind, weight, slot, pageTarget, params })=>({
+                    key,
+                    kind,
+                    weight,
+                    ...slot != null ? {
+                        slot
+                    } : {},
+                    ...pageTarget != null ? {
+                        pageTarget
+                    } : {},
+                    ...params != null ? {
+                        params
+                    } : {}
+                })),
+            targeting,
+            exposurePolicy: experiment.exposurePolicy,
+            deferrable: targeting.some((rule)=>rule.attribute === 'loggedIn' || rule.attribute === 'staff'),
+            ...experiment.flagPoint ? {
+                flagPoint: experiment.flagPoint
+            } : {},
+            ...layer ? {
+                layer
+            } : {},
+            ...decision?.winnerArm ? {
+                winnerArm: decision.winnerArm
+            } : {}
+        };
+        if (rollout) {
+            const holdout = phase.arms.find((arm)=>arm.kind === 'holdout');
+            if (holdout) compiled.holdoutKey = holdout.key;
+        }
+        manifest.experiments.push(structuredClone(compiled));
+    }
+    return manifest;
+}
+/** Take the state lock before reading inputs. Under READ COMMITTED, a builder
+ * waiting for another transition then sees that transition's committed changes,
+ * so a later revision cannot overwrite the manifest with pre-lock input state.
+ * All reads and writes join the request's transaction.
+ */ export async function buildAndStoreManifest(req, options = {}) {
+    const exec = txExecutor(req);
+    const revision = await bumpRevision(exec);
+    const inputs = await loadManifestInputs(req, options);
+    await pruneDeletedDefaults(req, inputs);
+    const manifest = compileManifest(inputs, revision, {
+        attributeKeys: xpOptionsFromReq(req).attributeKeys,
+        onInvalid: (slug, reason)=>req.payload.logger.warn({
+                slug,
+                reason
+            }, 'Experiment omitted from manifest')
+    });
+    await writeManifest(exec, manifest);
+    return manifest;
+}

package/dist/onInit.d.ts

@@ -0,0 +1,5 @@
+import type { Config } from 'payload';
+import type { ResolvedOptions } from './types/contracts.js';
+export declare function createOnInit<TUser extends {
+    id: string | number;
+}>(options: ResolvedOptions<TUser>): NonNullable<Config['onInit']>;

package/dist/onInit.js

@@ -0,0 +1,13 @@
+import { validateDimensions } from './events/dimensions.js';
+import { assertPostgresAdapter, probeTransactions } from './db/adapter.js';
+import { hasHostAttributesOf } from './server/serverRuntime.js';
+export function createOnInit(options) {
+    return async (payload)=>{
+        validateDimensions(options.events?.dimensions);
+        assertPostgresAdapter(payload);
+        await probeTransactions(payload);
+        if (Object.hasOwn(options.attributeKeys ?? {}, 'staff') && !hasHostAttributesOf(options.runtime)) {
+            throw new Error('`staff` is declared in attributeKeys, so pass an `attributesOf` that identifies staff to defineExperimentsServerRuntime');
+        }
+    };
+}

package/dist/options/fromReq.d.ts

@@ -0,0 +1,3 @@
+import type { PayloadRequest } from 'payload';
+import type { ResolvedOptions } from '../types/contracts.js';
+export declare function xpOptionsFromReq(req: PayloadRequest): ResolvedOptions;

package/dist/options/fromReq.js

@@ -0,0 +1,5 @@
+export function xpOptionsFromReq(req) {
+    const options = req.payload.config.custom?.xp;
+    if (!options) throw new Error('Experiments options are missing from req.payload.config.custom.xp; install the experiments plugin first.');
+    return options;
+}

package/dist/options.d.ts

@@ -0,0 +1,9 @@
+import type { ExperimentsPluginOptions, ResolvedOptions } from './types/contracts.js';
+/** Resolve once per registration list; every consumer shares the same field defaults. */
+export declare function puckCollections(options: Pick<ExperimentsPluginOptions, 'puck'>): Array<{
+    slug: string;
+    field: string;
+}>;
+export declare function resolveOptions<TUser extends {
+    id: string | number;
+}>(input: ExperimentsPluginOptions<TUser>): ResolvedOptions<TUser>;

package/dist/options.js

@@ -0,0 +1,99 @@
+import { DEFAULT_MAX_BODY_BYTES } from './constants.js';
+const normalisedCollections = new WeakMap();
+/** Resolve once per registration list; every consumer shares the same field defaults. */ export function puckCollections(options) {
+    const entries = options.puck?.collections;
+    if (!entries) return [];
+    const cached = normalisedCollections.get(entries);
+    if (cached) return cached;
+    const resolved = entries.map((entry)=>typeof entry === 'string' ? {
+            slug: entry,
+            field: 'puckData'
+        } : {
+            slug: entry.slug,
+            field: entry.field ?? 'puckData'
+        });
+    normalisedCollections.set(entries, resolved);
+    normalisedCollections.set(resolved, resolved);
+    return resolved;
+}
+export function resolveOptions(input) {
+    if (typeof input?.access?.manage !== 'function') throw new Error('Experiments access.manage must be a function');
+    const { manage, admin = manage, readResults = manage, readIdentities = admin } = input.access;
+    for (const [name, access] of Object.entries({
+        admin,
+        readResults,
+        readIdentities
+    })){
+        if (typeof access !== 'function') throw new Error(`Experiments access.${name} must be a function`);
+    }
+    const ids = new Set();
+    for (const point of input.flagPoints ?? []){
+        if (typeof point.id !== 'string' || !point.id || ids.has(point.id)) throw new Error('Experiments flag point ids must be unique nonempty strings');
+        ids.add(point.id);
+    }
+    // Record keys are unique by construction; validate each declared key and type.
+    for (const [key, attribute] of Object.entries(input.attributeKeys ?? {})){
+        if (!key || !attribute || ![
+            'string',
+            'number',
+            'boolean'
+        ].includes(attribute.type)) throw new Error(`Invalid experiments attribute key or type: ${key}`);
+        if (attribute.values !== undefined && (!Array.isArray(attribute.values) || attribute.values.some((value)=>typeof value !== 'string'))) {
+            throw new Error(`Experiments attribute values must be strings: ${key}`);
+        }
+    }
+    for (const name of input.eventSources ?? []){
+        if (typeof name !== 'string' || !/^[a-z0-9_]+$/.test(name)) throw new Error('Experiments event source names must match /^[a-z0-9_]+$/');
+    }
+    const retentionDays = input.events?.retentionDays ?? 180;
+    const maxBodyBytes = input.events?.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    for (const [name, value] of Object.entries({
+        retentionDays,
+        maxBodyBytes
+    })){
+        if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) throw new Error(`Experiments events.${name} must be a finite positive integer`);
+    }
+    const dimensions = input.events?.dimensions === undefined ? [] : input.events.dimensions;
+    return {
+        ...input,
+        access: {
+            manage,
+            admin,
+            readResults,
+            readIdentities
+        },
+        flagPoints: [
+            ...input.flagPoints ?? []
+        ],
+        metricSources: [
+            ...input.metricSources ?? []
+        ],
+        eventSources: [
+            ...input.eventSources ?? []
+        ],
+        attributeKeys: Object.fromEntries(Object.entries(input.attributeKeys ?? {}).map(([key, attribute])=>[
+                key,
+                {
+                    ...attribute,
+                    ...attribute.values ? {
+                        values: [
+                            ...attribute.values
+                        ]
+                    } : {}
+                }
+            ])),
+        events: {
+            ...input.events,
+            retentionDays,
+            maxBodyBytes,
+            dimensions: Array.isArray(dimensions) ? [
+                ...dimensions
+            ] : dimensions
+        },
+        puck: {
+            ...input.puck,
+            enabled: input.puck?.enabled ?? Boolean(input.puck?.collections?.length),
+            collections: puckCollections(input)
+        }
+    };
+}

package/dist/plugin.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from 'payload';
+import type { ExperimentsPluginOptions } from './types/contracts.js';
+export declare function createExperimentsPlugin<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(input: ExperimentsPluginOptions<TUser>): Plugin;

package/dist/plugin.js

@@ -0,0 +1,62 @@
+import { buildCollections } from './collections/index.js';
+import { buildEndpoints } from './endpoints/index.js';
+import { contentChangesBeforeHook, contentChangesHook } from './hooks/contentChanges.js';
+import { createOnInit } from './onInit.js';
+import { puckCollections, resolveOptions } from './options.js';
+export function createExperimentsPlugin(input) {
+    const options = resolveOptions(input);
+    return (config)=>{
+        const registrations = puckCollections(options);
+        for (const { slug } of registrations){
+            if (!config.collections?.some((collection)=>collection.slug === slug)) throw new Error(`Unknown experiments puck collection: ${slug}`);
+        }
+        // The frozen factories consume registration/access metadata, never TUser callbacks.
+        // Erase the user subtype only at this non-generic factory boundary.
+        const { collections, globals } = buildCollections(options);
+        const onInit = createOnInit(options);
+        return {
+            ...config,
+            collections: [
+                ...(config.collections ?? []).map((collection)=>{
+                    const puck = options.puck?.enabled && registrations.some((entry)=>entry.slug === collection.slug);
+                    if (!puck) return collection;
+                    return {
+                        ...collection,
+                        hooks: {
+                            ...collection.hooks,
+                            beforeChange: [
+                                ...collection.hooks?.beforeChange ?? [],
+                                contentChangesBeforeHook
+                            ],
+                            ...puck ? {
+                                afterChange: [
+                                    ...collection.hooks?.afterChange ?? [],
+                                    contentChangesHook
+                                ]
+                            } : {}
+                        }
+                    };
+                }),
+                ...collections
+            ],
+            globals: [
+                ...config.globals ?? [],
+                ...globals
+            ],
+            endpoints: [
+                ...config.endpoints ?? [],
+                ...buildEndpoints({
+                    options
+                })
+            ],
+            custom: {
+                ...config.custom,
+                xp: options
+            },
+            onInit: async (payload)=>{
+                await config.onInit?.(payload);
+                await onInit(payload);
+            }
+        };
+    };
+}

package/dist/proxy/apply.d.ts

@@ -0,0 +1,3 @@
+import type { NextResponse } from 'next/server';
+import type { ExperimentsProxyResult } from './resolve.js';
+export declare function applyExperiments(response: NextResponse, result: ExperimentsProxyResult): NextResponse;

package/dist/proxy/apply.js

@@ -0,0 +1,5 @@
+export function applyExperiments(response, result) {
+    for (const cookie of result.setCookies)response.cookies.set(cookie);
+    result.responseHeaders?.forEach((value, name)=>response.headers.set(name, value));
+    return response;
+}

package/dist/proxy/consentFallback.d.ts

@@ -0,0 +1,5 @@
+import { type AssignmentResult } from '../runtime/assign.js';
+import type { Attributes } from '../types/contracts.js';
+import type { Manifest } from '../types/manifest.js';
+/** Serve deterministic site content without assigning, hashing or retaining a unit id. */
+export declare function consentFallback(manifest: Manifest, attributes: Attributes, context: Pick<AssignmentResult, 'staff' | 'bot' | 'preview' | 'sessionUnknown' | 'method'>): AssignmentResult;

package/dist/proxy/consentFallback.js

@@ -0,0 +1,27 @@
+import { fillFlagPoints } from '../runtime/assign.js';
+import { evaluateTargeting } from '../runtime/targeting.js';
+import { controlAssignments } from './control.js';
+/** Serve deterministic site content without assigning, hashing or retaining a unit id. */ export function consentFallback(manifest, attributes, context) {
+    const result = controlAssignments(manifest, {
+        ...context,
+        visitorId: undefined,
+        userId: undefined
+    });
+    const identityFreeAttributes = {
+        ...attributes
+    };
+    delete identityFreeAttributes.userId;
+    delete identityFreeAttributes.visitorId;
+    if (context.sessionUnknown) {
+        delete identityFreeAttributes.loggedIn;
+        delete identityFreeAttributes.staff;
+    }
+    for (const experiment of manifest.experiments){
+        if (experiment.status !== 'decided' || experiment.phaseKind === 'rollout') continue;
+        const winner = experiment.arms.find((arm)=>arm.key === experiment.winnerArm);
+        if (!winner || !evaluateTargeting(experiment.targeting, identityFreeAttributes)) continue;
+        result.bySlug[experiment.slug].arm = winner.key;
+    }
+    fillFlagPoints(result, manifest);
+    return result;
+}

package/dist/proxy/control.d.ts

@@ -0,0 +1,6 @@
+import { type AssignmentResult } from '../runtime/assign.js';
+import type { Manifest } from '../types/manifest.js';
+/** Explicit control entries prevent deferred user/session assignments from becoming exposable. */
+export declare function controlAssignments(manifest: Manifest, context: Pick<AssignmentResult, 'visitorId' | 'userId' | 'staff' | 'bot' | 'preview' | 'sessionUnknown' | 'method'>): AssignmentResult;
+/** Last resort: do not inspect a manifest that could not even produce controls. */
+export declare function emptyAssignments(context: Pick<AssignmentResult, 'visitorId' | 'userId' | 'staff' | 'bot' | 'preview' | 'sessionUnknown' | 'method'>): AssignmentResult;

package/dist/proxy/control.js

@@ -0,0 +1,36 @@
+import { fillFlagPoints } from '../runtime/assign.js';
+/** Explicit control entries prevent deferred user/session assignments from becoming exposable. */ export function controlAssignments(manifest, context) {
+    const result = {
+        ...context,
+        revision: manifest.revision,
+        archivedWinners: {
+            ...manifest.archivedWinners
+        },
+        bySlug: Object.create(null),
+        flagPoints: Object.create(null),
+        deferred: []
+    };
+    for (const experiment of manifest.experiments){
+        result.bySlug[experiment.slug] = {
+            slug: experiment.slug,
+            experimentId: experiment.id,
+            arm: experiment.arms.find((arm)=>arm.kind === 'control')?.key ?? 'control',
+            phase: experiment.phase,
+            exposable: false,
+            policy: experiment.exposurePolicy,
+            source: 'fallback'
+        };
+    }
+    fillFlagPoints(result, manifest);
+    return result;
+}
+/** Last resort: do not inspect a manifest that could not even produce controls. */ export function emptyAssignments(context) {
+    return {
+        ...context,
+        revision: 0,
+        archivedWinners: {},
+        bySlug: Object.create(null),
+        flagPoints: Object.create(null),
+        deferred: []
+    };
+}

package/dist/proxy/createProxy.d.ts

@@ -0,0 +1,3 @@
+import { NextResponse, type NextRequest } from 'next/server.js';
+import type { ExperimentsProxyRuntime } from '../types/runtime.js';
+export declare function createExperimentProxy(proxyRuntime: ExperimentsProxyRuntime): (request: NextRequest) => Promise<NextResponse>;

package/dist/proxy/createProxy.js

@@ -0,0 +1,15 @@
+import { NextResponse } from 'next/server.js';
+import { resolveExperiments } from './resolve.js';
+import { applyExperiments } from './apply.js';
+export function createExperimentProxy(proxyRuntime) {
+    return async (request)=>{
+        const result = await resolveExperiments(request, proxyRuntime);
+        const options = {
+            request: {
+                headers: result.requestHeaders
+            }
+        };
+        const response = result.rewrite ? NextResponse.rewrite(result.rewrite, options) : NextResponse.next(options);
+        return applyExperiments(response, result);
+    };
+}

package/dist/proxy/pageRewrite.d.ts

@@ -0,0 +1,4 @@
+import type { AssignmentResult } from '../runtime/assign.js';
+import type { Manifest } from '../types/manifest.js';
+import type { NextRequest } from 'next/server';
+export declare function pageRewrite(manifest: Manifest, assignments: AssignmentResult, requestURL: NextRequest['nextUrl']): URL | undefined;

package/dist/proxy/pageRewrite.js

@@ -0,0 +1,41 @@
+import { findNormalisedPathKey, normalisePath } from '../runtime/normalisePath.js';
+// Manifest targets are local paths. A malformed target must never become an open rewrite.
+function targetURL(path, requestURL) {
+    if (!path?.startsWith('/') || path.startsWith('//') || /[\\\r\n?#]/.test(path)) return undefined;
+    try {
+        const url = requestURL.clone();
+        url.pathname = path;
+        if (url.origin !== requestURL.origin) return undefined;
+        return new URL(url.href);
+    } catch  {
+        return undefined;
+    }
+}
+export function pageRewrite(manifest, assignments, requestURL) {
+    const experiment = manifest.experiments.find((experiment)=>experiment.kind === 'page' && (experiment.status === 'running' || experiment.status === 'decided') && experiment.arms.some((arm)=>arm.pageTarget !== undefined && normalisePath(arm.pageTarget) === normalisePath(requestURL.pathname)));
+    if (experiment) {
+        const assignment = assignments.bySlug[experiment.slug];
+        const control = experiment.arms.find((arm)=>arm.kind === 'control');
+        const arm = experiment.arms.find((arm)=>arm.key === assignment?.arm);
+        const target = targetURL((arm?.kind === 'holdout' ? control : arm)?.pageTarget, requestURL);
+        if (target) return target;
+        if (control) {
+            // The proxy has committed to serving control. Deferred server evaluation
+            // must not later describe a different, exposable page for this request.
+            assignments.deferred = assignments.deferred.filter((slug)=>slug !== experiment.slug);
+            assignments.bySlug[experiment.slug] = {
+                slug: experiment.slug,
+                experimentId: experiment.id,
+                arm: control.key,
+                phase: experiment.phase,
+                exposable: false,
+                policy: experiment.exposurePolicy,
+                source: 'fallback'
+            };
+        }
+        return targetURL(control?.pageTarget, requestURL);
+    }
+    const archivedPath = findNormalisedPathKey(manifest.archivedPages, requestURL.pathname);
+    const archived = archivedPath === undefined ? undefined : manifest.archivedPages[archivedPath];
+    return targetURL(archived?.winnerPath, requestURL);
+}

package/dist/proxy/resolve.d.ts

@@ -0,0 +1,13 @@
+import type { NextRequest, NextResponse } from 'next/server';
+import type { ExperimentsProxyRuntime } from '../types/runtime.js';
+export interface ExperimentsProxyResult {
+    responseHeaders?: Headers;
+    requestHeaders: Headers;
+    requestCookies: Array<{
+        name: string;
+        value: string;
+    }>;
+    setCookies: Array<Exclude<Parameters<NextResponse['cookies']['set']>[0], string>>;
+    rewrite?: URL;
+}
+export declare function resolveExperiments(request: NextRequest, proxyRuntime: ExperimentsProxyRuntime): Promise<ExperimentsProxyResult>;