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

package/dist/runtime/header.d.ts

@@ -0,0 +1,17 @@
+import type { Assignments } from '../types/assignments.js';
+import type { Manifest } from '../types/manifest.js';
+import { type AssignmentResult } from './assign.js';
+/** Throws if compression still exceeds the 1 KB budget; callers fall back to recompute. */
+export declare function encodeAssignmentsHeader(assignments: Assignments & {
+    deferred?: readonly string[];
+}, opts: {
+    secrets: readonly string[];
+    manifest?: Manifest;
+}): string;
+/** A header newer than the supplied manifest returns null; callers reload the manifest and retry. */
+export declare function decodeAssignmentsHeader(value: string, opts: {
+    secrets: readonly string[];
+    visitorId?: string;
+    userId?: string;
+    manifest: Manifest;
+}): AssignmentResult | null;

package/dist/runtime/header.js

@@ -0,0 +1,97 @@
+import { createHash } from 'node:crypto';
+import { fillFlagPoints } from './assign.js';
+import { sign, verify } from './signing.js';
+const MAX_BYTES = 1024;
+const SLUG = /^[A-Za-z0-9_-]+$/;
+const ARM = /^(control|variantA|variantB|variantC|holdout)$/;
+const slugHash = (slug)=>`#${createHash('sha256').update(slug).digest('hex').slice(0, 8)}`;
+const message = (visitorId, userId, flags, entries, revision)=>`xp:assign:${visitorId ?? ''}|${userId ?? ''}|${flags}|${entries}|${revision}`;
+/** Throws if compression still exceeds the 1 KB budget; callers fall back to recompute. */ export function encodeAssignmentsHeader(assignments, opts) {
+    if (!Number.isSafeInteger(assignments.revision) || assignments.revision < 0) throw new Error('Invalid revision');
+    const flags = `${assignments.staff ? 's' : ''}${assignments.bot ? 'b' : ''}${assignments.preview ? 'p' : ''}${assignments.sessionUnknown ? 'u' : ''}`;
+    const slugs = [
+        ...Object.keys(assignments.bySlug),
+        ...assignments.deferred ?? []
+    ];
+    if (new Set(slugs).size !== slugs.length || slugs.some((slug)=>!SLUG.test(slug))) throw new Error('Invalid or duplicate slug');
+    for (const entry of Object.values(assignments.bySlug))if (!ARM.test(entry.arm)) throw new Error('Invalid arm');
+    const encode = (hashed)=>{
+        const entries = [
+            ...Object.entries(assignments.bySlug).map(([slug, entry])=>`${hashed ? slugHash(slug) : slug}=${entry.arm}${entry.exposable ? '' : '!'}`),
+            ...(assignments.deferred ?? []).map((slug)=>`?${hashed ? slugHash(slug) : slug}`)
+        ].join(';');
+        const revision = String(assignments.revision);
+        return `v1.${revision}.${flags}.${entries}.${sign(message(assignments.visitorId, assignments.userId, flags, entries, revision), opts.secrets)}`;
+    };
+    const plain = encode(false);
+    if (Buffer.byteLength(plain) <= MAX_BYTES) return plain;
+    const hashes = (opts.manifest?.experiments.map((experiment)=>experiment.slug) ?? slugs).map(slugHash);
+    if (new Set(hashes).size !== hashes.length) throw new Error('Ambiguous slug hash');
+    const hashed = encode(true);
+    if (Buffer.byteLength(hashed) > MAX_BYTES) throw new RangeError('Assignments header exceeds 1024 bytes');
+    return hashed;
+}
+/** A header newer than the supplied manifest returns null; callers reload the manifest and retry. */ export function decodeAssignmentsHeader(value, opts) {
+    if (typeof value !== 'string' || Buffer.byteLength(value) > MAX_BYTES) return null;
+    const parts = value.split('.');
+    if (parts.length !== 5) return null;
+    const [version, revision, flags, entries, mac] = parts;
+    if (version !== 'v1' || !/^(0|[1-9]\d*)$/.test(revision) || !Number.isSafeInteger(Number(revision))) return null;
+    // Phase and policy are reconstructed from this exact manifest, never a different revision.
+    if (Number(revision) !== opts.manifest.revision) return null;
+    if (!/^[sbpu]*$/.test(flags) || new Set(flags).size !== flags.length) return null;
+    if (!verify(message(opts.visitorId, opts.userId, flags, entries, revision), mac, opts.secrets)) return null;
+    const manifestBySlug = new Map(opts.manifest.experiments.map((experiment)=>[
+            experiment.slug,
+            experiment
+        ]));
+    const hashes = new Map();
+    for (const experiment of opts.manifest.experiments){
+        const key = slugHash(experiment.slug);
+        hashes.set(key, hashes.has(key) ? null : experiment.slug);
+    }
+    const result = {
+        revision: Number(revision),
+        visitorId: opts.visitorId,
+        userId: opts.userId,
+        staff: flags.includes('s'),
+        bot: flags.includes('b'),
+        preview: flags.includes('p'),
+        sessionUnknown: flags.includes('u'),
+        bySlug: Object.create(null),
+        flagPoints: Object.create(null),
+        archivedWinners: {
+            ...opts.manifest.archivedWinners
+        },
+        deferred: [],
+        method: 'GET'
+    };
+    const seen = new Set();
+    for (const entry of entries ? entries.split(';') : []){
+        const match = /^(\?)?([A-Za-z0-9_-]+|#[a-f0-9]{8})(?:=(control|variantA|variantB|variantC|holdout)(!)?)?$/.exec(entry);
+        if (!match) return null;
+        const [, deferred, key, arm, nonExposable] = match;
+        if (Boolean(deferred) === Boolean(arm)) return null;
+        const slug = key.startsWith('#') ? hashes.get(key) : key;
+        if (!slug || seen.has(slug)) return null;
+        const experiment = manifestBySlug.get(slug);
+        if (!experiment) return null;
+        seen.add(slug);
+        if (deferred) {
+            result.deferred.push(slug);
+            continue;
+        }
+        if (!experiment.arms.some((candidate)=>candidate.key === arm)) return null;
+        result.bySlug[slug] = {
+            slug,
+            experimentId: experiment.id,
+            arm: arm,
+            phase: experiment.phase,
+            policy: experiment.exposurePolicy,
+            exposable: !nonExposable && !result.staff && !result.bot && !result.preview,
+            source: 'header'
+        };
+    }
+    fillFlagPoints(result, opts.manifest);
+    return result;
+}

package/dist/runtime/loaders.d.ts

@@ -0,0 +1,17 @@
+import type { Pool } from 'pg';
+import type { ExperimentsProxyRuntimeOptions } from '../types/runtime.js';
+export type ManifestLoader = NonNullable<ExperimentsProxyRuntimeOptions['loadManifest']>;
+export interface PostgresManifestLoaderOptions {
+    pool: Pool;
+    schemaName?: string;
+}
+export interface HttpManifestLoaderOptions {
+    url: string;
+    key: string;
+    refreshTimeoutMs?: number;
+}
+/** Hosts must set connectionTimeoutMillis on their pg pool to bound connection
+ * acquisition; the manifest cache's refresh ceiling does not cancel pg work.
+ */
+export declare function createPostgresManifestLoader({ pool, schemaName }: PostgresManifestLoaderOptions): ManifestLoader;
+export declare function createHttpManifestLoader({ url, key, refreshTimeoutMs }: HttpManifestLoaderOptions): ManifestLoader;

package/dist/runtime/loaders.js

@@ -0,0 +1,29 @@
+import { pgPoolExecutor } from '../db/pgExecutor.js';
+import { readManifestRow } from '../db/manifest.js';
+/** Hosts must set connectionTimeoutMillis on their pg pool to bound connection
+ * acquisition; the manifest cache's refresh ceiling does not cancel pg work.
+ */ export function createPostgresManifestLoader({ pool, schemaName }) {
+    return async ({ ifRevision } = {})=>{
+        const row = await readManifestRow(pgPoolExecutor(pool), {
+            schemaName
+        });
+        return row ? row.revision === ifRevision ? 'not-modified' : row.manifest : null;
+    };
+}
+export function createHttpManifestLoader({ url, key, refreshTimeoutMs = 5_000 }) {
+    return async ({ ifRevision } = {})=>{
+        const response = await fetch(url, {
+            headers: {
+                'x-xp-manifest-key': key,
+                ...ifRevision != null ? {
+                    'if-none-match': String(ifRevision)
+                } : {}
+            },
+            signal: AbortSignal.timeout(refreshTimeoutMs),
+            cache: 'no-store'
+        });
+        if (response.status === 304) return 'not-modified';
+        if (!response.ok) throw new Error(`Manifest request failed (${response.status})`);
+        return await response.json();
+    };
+}

package/dist/runtime/normalisePath.d.ts

@@ -0,0 +1,7 @@
+import type { Attributes } from '../types/contracts.js';
+/** Normalise a pathname only: preserve root and percent encoding. */
+export declare function normalisePath(pathname: string): string;
+/** Match own path keys with the same rules as live page targets. */
+export declare function findNormalisedPathKey<T>(paths: Readonly<Record<string, T>>, pathname: string): string | undefined;
+/** The attribute set targeting sees, shared by the proxy and the server: the unit's attributes plus the normalised path (removed when the path is unknown). */
+export declare function requestAttributes(unit: Attributes, pathname: string | undefined): Attributes;

package/dist/runtime/normalisePath.js

@@ -0,0 +1,15 @@
+/** Normalise a pathname only: preserve root and percent encoding. */ export function normalisePath(pathname) {
+    return pathname.replace(/\/+$/, '') || '/';
+}
+/** Match own path keys with the same rules as live page targets. */ export function findNormalisedPathKey(paths, pathname) {
+    const path = normalisePath(pathname);
+    return Object.keys(paths).find((key)=>normalisePath(key) === path);
+}
+/** The attribute set targeting sees, shared by the proxy and the server: the unit's attributes plus the normalised path (removed when the path is unknown). */ export function requestAttributes(unit, pathname) {
+    const attributes = {
+        ...unit
+    };
+    if (pathname === undefined) delete attributes.path;
+    else attributes.path = normalisePath(pathname);
+    return attributes;
+}

package/dist/runtime/previewToken.d.ts

@@ -0,0 +1,9 @@
+import type { DocId } from '../types/contracts.js';
+export interface PreviewToken {
+    e: DocId;
+    a: string;
+    p: number;
+    exp: number;
+}
+export declare function signPreviewToken(token: PreviewToken, secrets: readonly string[], now?: number): string;
+export declare function verifyPreviewToken(value: string, secrets: readonly string[], now?: number): PreviewToken | null;

package/dist/runtime/previewToken.js

@@ -0,0 +1,23 @@
+import { sign, verify } from './signing.js';
+function validToken(value, now) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+    const token = value;
+    return Object.keys(token).sort().join(',') === 'a,e,exp,p' && (typeof token.e === 'string' && token.e.length > 0 || typeof token.e === 'number' && Number.isSafeInteger(token.e)) && typeof token.a === 'string' && /^(control|variantA|variantB|variantC|holdout)$/.test(token.a) && typeof token.p === 'number' && Number.isSafeInteger(token.p) && token.p >= 0 && typeof token.exp === 'number' && Number.isSafeInteger(token.exp) && token.exp > now && token.exp <= now + 3600;
+}
+export function signPreviewToken(token, secrets, now = Math.floor(Date.now() / 1000)) {
+    if (!validToken(token, now)) throw new Error('Invalid preview token or expiry');
+    const value = Buffer.from(JSON.stringify(token)).toString('base64url');
+    return `${value}.${sign(`xp:preview:${value}`, secrets)}`;
+}
+export function verifyPreviewToken(value, secrets, now = Math.floor(Date.now() / 1000)) {
+    try {
+        const match = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/.exec(value);
+        if (!match || !verify(`xp:preview:${match[1]}`, match[2], secrets)) return null;
+        const bytes = Buffer.from(match[1], 'base64url');
+        if (bytes.toString('base64url') !== match[1]) return null;
+        const token = JSON.parse(bytes.toString('utf8'));
+        return validToken(token, now) ? token : null;
+    } catch  {
+        return null;
+    }
+}

package/dist/runtime/proxyRuntime.d.ts

@@ -0,0 +1,2 @@
+import type { ExperimentsProxyRuntime, ExperimentsProxyRuntimeOptions } from '../types/runtime.js';
+export declare function defineExperimentsProxyRuntime(opts: ExperimentsProxyRuntimeOptions): ExperimentsProxyRuntime;

package/dist/runtime/proxyRuntime.js

@@ -0,0 +1,22 @@
+import { XP_COOKIE } from '../constants.js';
+export function defineExperimentsProxyRuntime(opts) {
+    const secrets = typeof opts.secret === 'string' ? [
+        opts.secret
+    ] : [
+        ...opts.secret
+    ];
+    if (!secrets.length || secrets.some((secret)=>!secret.trim())) throw new Error('At least one non-empty secret is required');
+    const cookie = Object.freeze({
+        ...opts.cookie,
+        name: opts.cookie?.name ?? XP_COOKIE,
+        maxAgeDays: opts.cookie?.maxAgeDays ?? 365
+    });
+    Object.freeze(secrets);
+    return Object.freeze({
+        secrets,
+        apiRoute: opts.apiRoute,
+        cookie,
+        loadManifest: opts.loadManifest,
+        getUnit: opts.getUnit
+    });
+}

package/dist/runtime/seed.d.ts

@@ -0,0 +1,2 @@
+/** All assignment seeds include the stats engine's required separator. */
+export declare function newSeed(): string;

package/dist/runtime/seed.js

@@ -0,0 +1,4 @@
+import { randomBytes } from 'node:crypto';
+/** All assignment seeds include the stats engine's required separator. */ export function newSeed() {
+    return `${randomBytes(16).toString('hex')}|`;
+}

package/dist/runtime/signing.d.ts

@@ -0,0 +1,3 @@
+/** New signatures use the first key; verification accepts the entire rotation. */
+export declare function sign(value: string, secrets: readonly string[]): string;
+export declare function verify(value: string, mac: string, secrets: readonly string[]): boolean;

package/dist/runtime/signing.js

@@ -0,0 +1,16 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** New signatures use the first key; verification accepts the entire rotation. */ export function sign(value, secrets) {
+    if (!secrets.length || !secrets[0]) throw new Error('A signing secret is required');
+    return createHmac('sha256', secrets[0]).update(value).digest('base64url');
+}
+export function verify(value, mac, secrets) {
+    if (!/^[A-Za-z0-9_-]{43}$/.test(mac)) return false;
+    const supplied = Buffer.from(mac, 'base64url');
+    if (supplied.toString('base64url') !== mac) return false;
+    let valid = false;
+    for (const secret of secrets){
+        const expected = createHmac('sha256', secret).update(value).digest();
+        if (supplied.length === expected.length && timingSafeEqual(supplied, expected)) valid = true;
+    }
+    return valid;
+}

package/dist/runtime/targeting.d.ts

@@ -0,0 +1,6 @@
+import type { Attributes, ExperimentsPluginOptions, TargetingRule } from '../types/contracts.js';
+export type AttributeKeys = NonNullable<ExperimentsPluginOptions['attributeKeys']>;
+/** Frozen manifest types take precedence; declarations still support draft rules. */
+export declare function evaluateTargeting(rules: readonly (TargetingRule & {
+    type?: 'string' | 'number' | 'boolean';
+})[], attributes: Attributes, attributeKeys?: AttributeKeys): boolean;

package/dist/runtime/targeting.js

@@ -0,0 +1,9 @@
+import { evaluateOp } from '../targeting/ops.js';
+/** Frozen manifest types take precedence; declarations still support draft rules. */ export function evaluateTargeting(rules, attributes, attributeKeys) {
+    return rules.every((rule)=>{
+        if (!Object.hasOwn(attributes, rule.attribute)) return false;
+        if (rule.type === undefined && attributeKeys && !Object.hasOwn(attributeKeys, rule.attribute)) return false;
+        const type = rule.type ?? attributeKeys?.[rule.attribute]?.type ?? (Array.isArray(rule.value) ? 'string' : typeof rule.value);
+        return evaluateOp(type, rule.op, attributes[rule.attribute], rule.value);
+    });
+}

package/dist/server/context.d.ts

@@ -0,0 +1,10 @@
+import type { Attributes } from '../types/contracts.js';
+import type { Assignments } from '../types/assignments.js';
+import type { Manifest } from '../types/manifest.js';
+import type { ExperimentsProxyRuntime } from '../types/runtime.js';
+export declare const emptyManifest: () => Manifest;
+export declare function serverManifest(runtime: ExperimentsProxyRuntime, reload?: boolean): Promise<Manifest | null>;
+export declare function rememberManifest(assignments: Assignments, manifest: Manifest, attributes?: Attributes): Assignments;
+export declare const requestAttributesOf: (assignments: Assignments) => Readonly<Attributes>;
+export declare const manifestOf: (assignments: Assignments) => Manifest | undefined;
+export declare const suppressExposure: (a: Assignments) => boolean;

package/dist/server/context.js

@@ -0,0 +1,59 @@
+import { createManifestCache } from '../manifest/cache.js';
+const caches = new WeakMap();
+// Rendering details stay server-side, outside the frozen public assignment wire shape.
+const manifests = new WeakMap();
+const requestAttributeSets = new WeakMap();
+export const emptyManifest = ()=>({
+        v: 1,
+        revision: 0,
+        experiments: [],
+        flagDefaults: {},
+        archivedWinners: {},
+        archivedPages: {}
+    });
+export async function serverManifest(runtime, reload = false) {
+    if (!runtime.loadManifest) return null;
+    let entry = caches.get(runtime);
+    if (!entry) {
+        entry = {
+            cache: createManifestCache(runtime.loadManifest)
+        };
+        caches.set(runtime, entry);
+    }
+    if (entry.forced) return entry.forced;
+    if (!reload) return entry.cache.get();
+    const state = entry, load = runtime.loadManifest;
+    state.forced = (async ()=>{
+        const previous = await state.cache.get();
+        let initial = true;
+        const refreshed = createManifestCache(async (opts)=>{
+            const first = initial;
+            initial = false;
+            const value = await load(first && previous ? {
+                ifRevision: previous.revision
+            } : opts);
+            // Only the cold forced read needs seeding. Later refreshes use this cache's
+            // own revision and last-good retention, rather than the original snapshot.
+            return first && (value === 'not-modified' || value === null) ? previous : value;
+        });
+        const value = await refreshed.get();
+        if (value) state.cache = refreshed;
+        return value ?? previous;
+    })().finally(()=>{
+        state.forced = undefined;
+    });
+    return state.forced;
+}
+export function rememberManifest(assignments, manifest, attributes) {
+    manifests.set(assignments, manifest);
+    if (attributes) requestAttributeSets.set(assignments, Object.freeze({
+        ...attributes
+    }));
+    return assignments;
+}
+export const requestAttributesOf = (assignments)=>requestAttributeSets.get(assignments) ?? {};
+export const manifestOf = (assignments)=>manifests.get(assignments);
+export const suppressExposure = (a)=>a.staff || a.bot || a.preview || [
+        'HEAD',
+        'UNKNOWN'
+    ].includes(a.method.toUpperCase());

package/dist/server/eraseUser.d.ts

@@ -0,0 +1,7 @@
+import type { Payload } from 'payload';
+export declare function eraseUser(payload: Payload, opts: {
+    userId: string;
+}): Promise<{
+    identities: number;
+    events: number;
+}>;

package/dist/server/eraseUser.js

@@ -0,0 +1,4 @@
+import { eraseUserInTransaction } from '../db/erase.js';
+export async function eraseUser(payload, opts) {
+    return eraseUserInTransaction(payload, String(opts.userId));
+}

package/dist/server/getAssignments.d.ts

@@ -0,0 +1,9 @@
+import type { ExperimentsServerRuntime } from '../types/runtime.js';
+import type { Assignments } from '../types/assignments.js';
+export declare function getAssignments<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(serverRuntime: ExperimentsServerRuntime<TUser>, opts?: {
+    user?: TUser | null;
+}): Promise<Assignments>;

package/dist/server/getAssignments.js

@@ -0,0 +1,227 @@
+import { cache } from 'react';
+import { headers } from 'next/headers.js';
+import { XP_HEADER } from '../constants.js';
+import { assign, fillFlagPoints } from '../runtime/assign.js';
+import { readUnitCookie } from '../runtime/cookie.js';
+import { decodeAssignmentsHeader } from '../runtime/header.js';
+import { verifyPreviewToken } from '../runtime/previewToken.js';
+import { isBot } from '../runtime/bot.js';
+import { consentFallback } from '../proxy/consentFallback.js';
+import { requestAttributes } from '../runtime/normalisePath.js';
+import { controlAssignments, emptyAssignments } from '../proxy/control.js';
+import { emptyManifest, rememberManifest, serverManifest, suppressExposure } from './context.js';
+import { serverRequest } from './request.js';
+import { previewDraft } from './previewDraft.js';
+import { verifiedHeaderRevision } from './headerRevision.js';
+// The mutable cell lives in React's request cache, never a process-wide user cache.
+const requestCell = cache((_runtime, _userId)=>({
+        value: undefined
+    }));
+export async function getAssignments(serverRuntime, opts) {
+    const key = opts?.user === undefined ? 'auto' : opts.user === null ? 'anonymous' : `user:${serverRuntime.userIdOf(opts.user)}`;
+    const cell = requestCell(serverRuntime, key);
+    return cell.value ??= readAssignments(serverRuntime, opts?.user);
+}
+async function readAssignments(runtime, suppliedUser) {
+    const requestHeaders = new Headers(await headers());
+    const proxy = runtime.proxyRuntime;
+    const { request, hasContext, consent } = serverRequest(requestHeaders, proxy.secrets);
+    const visitorId = consent === false ? undefined : readUnitCookie(requestHeaders, proxy) ?? undefined;
+    let payload;
+    let payloadFailed = false;
+    try {
+        payload = await runtime.getPayload();
+    } catch  {
+        payloadFailed = true;
+        console.error('[payload-experiments] getPayload failed; serving non-exposable control');
+    }
+    const options = payload?.config?.custom?.xp;
+    let unit = {
+        attributes: {}
+    };
+    try {
+        unit = await proxy.getUnit?.(request) ?? unit;
+    } catch  {
+        unit = {
+            attributes: {},
+            sessionUnknown: true
+        };
+        console.error('[payload-experiments] getUnit failed; treating session as unknown');
+    }
+    if (consent === false) unit = {
+        attributes: unit.attributes,
+        sessionUnknown: unit.sessionUnknown
+    };
+    let user = consent === false ? null : suppliedUser;
+    const canResolveUser = consent !== false && (suppliedUser !== undefined || Boolean(runtime.getUser));
+    let userFailed = false;
+    const resolveUser = async ()=>{
+        if (user !== undefined) return user;
+        try {
+            user = await runtime.getUser?.() ?? null;
+        } catch  {
+            userFailed = true;
+            user = null;
+            console.error('[payload-experiments] getUser failed; suppressing exposures');
+        }
+        return user;
+    };
+    const value = requestHeaders.get(XP_HEADER);
+    // Consent-false proxy headers are signed without either identity.
+    let headerUserId = visitorId ? unit.userId : undefined;
+    const authenticate = (userId)=>verifiedHeaderRevision(value, {
+            secrets: proxy.secrets,
+            visitorId,
+            userId
+        });
+    let revision = authenticate(headerUserId);
+    if (revision === null && visitorId && value && (runtime.getUser || suppliedUser)) {
+        const resolved = await resolveUser();
+        if (resolved) {
+            const resolvedId = runtime.userIdOf(resolved);
+            revision = authenticate(resolvedId);
+            if (revision !== null) headerUserId = resolvedId;
+        }
+    }
+    const cached = await serverManifest(proxy);
+    let manifest = cached ?? emptyManifest();
+    // A cold miss has already spent its sole coldStartMs window. Do not wait again.
+    if (cached && revision !== null && revision > manifest.revision) manifest = await serverManifest(proxy, true) ?? manifest;
+    const decoded = value && revision !== null ? decodeAssignmentsHeader(value, {
+        secrets: proxy.secrets,
+        visitorId,
+        userId: headerUserId,
+        manifest
+    }) : null;
+    const mustResolveStaff = Boolean(options?.attributeKeys?.staff && (decoded?.sessionUnknown || unit.sessionUnknown));
+    const needsUser = !decoded || decoded.deferred.length > 0 || mustResolveStaff || suppliedUser !== undefined;
+    if (needsUser && canResolveUser) await resolveUser();
+    const pathname = hasContext ? request.nextUrl.pathname : undefined;
+    let attributes = requestAttributes(unit.attributes, pathname);
+    if (needsUser && canResolveUser) {
+        try {
+            attributes = requestAttributes({
+                ...attributes,
+                ...runtime.attributesOf(user ?? null)
+            }, pathname);
+        } catch  {
+            userFailed = true;
+        }
+    }
+    const userId = visitorId ? user === undefined ? unit.userId : user ? runtime.userIdOf(user) : undefined : undefined;
+    const context = {
+        visitorId,
+        userId,
+        staff: decoded?.staff === true || unit.attributes.staff === true || attributes.staff === true,
+        bot: decoded?.bot === true || isBot(requestHeaders.get('user-agent')),
+        preview: decoded?.preview ?? false,
+        sessionUnknown: needsUser && canResolveUser && !userFailed ? false : decoded?.sessionUnknown ?? unit.sessionUnknown ?? false,
+        method: request.method
+    };
+    const fillHostDefaults = (result)=>{
+        for (const point of options?.flagPoints ?? [])if (!Object.hasOwn(result.flagPoints, point.id)) {
+            result.flagPoints[point.id] = {
+                arm: 'control',
+                params: {
+                    ...point.defaultParams
+                },
+                source: 'default',
+                exposable: false
+            };
+        }
+        return result;
+    };
+    const lastResort = ()=>rememberManifest(fillHostDefaults(emptyAssignments(context)), emptyManifest());
+    let result;
+    if (payloadFailed) {
+        try {
+            result = controlAssignments(manifest, context);
+        } catch  {
+            return lastResort();
+        }
+    } else if (consent === false && !decoded) {
+        try {
+            result = consentFallback(manifest, attributes, context);
+        } catch  {
+            console.error('[payload-experiments] consent fallback failed; serving non-exposable control');
+            try {
+                result = controlAssignments(manifest, context);
+            } catch  {
+                return lastResort();
+            }
+        }
+    } else if (decoded) {
+        result = {
+            ...decoded,
+            ...context,
+            archivedWinners: {
+                ...manifest.archivedWinners
+            }
+        };
+        const slugs = new Set(hasContext ? decoded.deferred : []);
+        if (visitorId && user !== undefined && userId !== headerUserId) {
+            for (const e of manifest.experiments)if (e.unitType === 'user') slugs.add(e.slug);
+        }
+        if (visitorId && slugs.size && canResolveUser && !userFailed) {
+            try {
+                const resolved = assign(manifest, {
+                    visitorId,
+                    userId,
+                    sessionUnknown: context.sessionUnknown
+                }, attributes, {
+                    ...context,
+                    now: Math.floor(Date.now() / 1000)
+                });
+                for (const slug of slugs){
+                    result.bySlug[slug] = resolved.bySlug[slug] ?? controlAssignments(manifest, context).bySlug[slug];
+                }
+            } catch  {
+                userFailed = true;
+            }
+        }
+    } else if (!visitorId || !hasContext) result = controlAssignments(manifest, context);
+    else {
+        try {
+            result = assign(manifest, {
+                visitorId,
+                userId,
+                sessionUnknown: context.sessionUnknown
+            }, attributes, {
+                ...context,
+                now: Math.floor(Date.now() / 1000)
+            });
+        } catch  {
+            console.error('[payload-experiments] assign failed; serving non-exposable control');
+            result = controlAssignments(manifest, context);
+        }
+    }
+    // Missing users left deferred by assign must still render explicit, safe control.
+    const controls = controlAssignments(manifest, context);
+    for (const experiment of manifest.experiments){
+        if (!result.bySlug[experiment.slug]) result.bySlug[experiment.slug] = controls.bySlug[experiment.slug];
+    }
+    fillFlagPoints(result, manifest);
+    fillHostDefaults(result);
+    const token = hasContext ? verifyPreviewToken(request.nextUrl.searchParams.get('xp_preview') ?? '', proxy.secrets) : null;
+    if (token && visitorId && payload) {
+        const live = manifest.experiments.find((e)=>e.id === token.e && e.phase === token.p && e.arms.some((a)=>a.key === token.a));
+        if (live) {
+            result.preview = true;
+            result.bySlug[live.slug] = {
+                slug: live.slug,
+                experimentId: live.id,
+                arm: token.a,
+                phase: token.p,
+                policy: live.exposurePolicy,
+                exposable: false,
+                source: 'preview'
+            };
+            fillFlagPoints(result, manifest);
+        } else await previewDraft(payload, await resolveUser(), token, result, requestHeaders);
+    }
+    if (suppressExposure(result) || !hasContext || !visitorId || payloadFailed || userFailed || mustResolveStaff && !runtime.getUser && suppliedUser === undefined) {
+        for (const assignment of Object.values(result.bySlug))assignment.exposable = false;
+        for (const point of Object.values(result.flagPoints))point.exposable = false;
+    }
+    return rememberManifest(result, manifest, attributes);
+}

package/dist/server/getFlagPoint.d.ts

@@ -0,0 +1,11 @@
+import type { ExperimentsServerRuntime } from '../types/runtime.js';
+import type { FlagPointResult } from '../types/assignments.js';
+export declare function getFlagPoint<TUser extends {
+    id: string | number;
+} = {
+    id: string | number;
+}>(serverRuntime: ExperimentsServerRuntime<TUser>, id: string, opts?: {
+    user?: TUser | null;
+}): Promise<FlagPointResult & {
+    expose(renderedArm: string): Promise<void>;
+}>;