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

package/dist/results/rolloutUnits.d.ts

@@ -0,0 +1,17 @@
+import type { Timestamp } from './aggregate.js';
+/** Spec §7.6/§8.1.5 (X1): first-ever rollout exposures inside assignment's exact ranges. */
+export declare function rolloutAnalysisUnits({ exposuresAllPhases, rolloutPhase, seed, testWeights, coverage, layer }: {
+    exposuresAllPhases: readonly {
+        unitId: string;
+        phase: number;
+        ts: Timestamp;
+    }[];
+    rolloutPhase: number;
+    seed: string;
+    testWeights: readonly number[];
+    coverage: number;
+    layer?: {
+        slug: string;
+        slices: readonly number[];
+    };
+}): Set<string>;

package/dist/results/rolloutUnits.js

@@ -0,0 +1,26 @@
+import { hash, layerSlice, rolloutBucketRanges } from '@delmaredigital/experiments-stats';
+import { timestampMs } from './aggregate.js';
+/** Spec §7.6/§8.1.5 (X1): first-ever rollout exposures inside assignment's exact ranges. */ export function rolloutAnalysisUnits({ exposuresAllPhases, rolloutPhase, seed, testWeights, coverage, layer }) {
+    if (!seed.endsWith('|')) throw new RangeError('Assignment seed must end in |');
+    const first = new Map();
+    for (const row of exposuresAllPhases){
+        const ts = timestampMs(row.ts);
+        const previous = first.get(row.unitId);
+        // Phase numbers increase chronologically; prefer the older phase on a timestamp tie.
+        if (!previous || ts < previous.ts || ts === previous.ts && row.phase < previous.phase) {
+            first.set(row.unitId, {
+                phase: row.phase,
+                ts
+            });
+        }
+    }
+    const { winner, holdout } = rolloutBucketRanges(testWeights, coverage);
+    const units = new Set();
+    for (const [unitId, exposure] of first){
+        if (exposure.phase !== rolloutPhase) continue;
+        if (layer && !layer.slices.includes(layerSlice(layer.slug, unitId))) continue;
+        const bucket = hash(seed, unitId, 2);
+        if (bucket >= winner[0] && bucket < winner[1] || bucket >= holdout[0] && bucket < holdout[1]) units.add(unitId);
+    }
+    return units;
+}

package/dist/results/snapshot.d.ts

@@ -0,0 +1,9 @@
+import type { Snapshot } from '../types/snapshot.js';
+/** JSON cannot represent unbounded confidence limits. */
+export declare function jsonInterval(ci: readonly [number | null, number | null]): [number | null, number | null];
+/** Validate the frozen JSON shape and headline/rollout invariants before storage.
+ * This also accepts the shared CORE-13/admin fixtures without any I/O.
+ */
+export declare function validateSnapshot(value: unknown): asserts value is Snapshot;
+/** Assemble the already-computed snapshot at the pure/I/O boundary. */
+export declare function assembleSnapshot(snapshot: Snapshot): Snapshot;

package/dist/results/snapshot.js

@@ -0,0 +1,154 @@
+/** JSON cannot represent unbounded confidence limits. */ export function jsonInterval(ci) {
+    return ci.map((bound)=>bound !== null && Number.isFinite(bound) ? bound : null);
+}
+const number = (value)=>typeof value === 'number' && Number.isFinite(value);
+const count = (value)=>number(value) && Number.isInteger(value) && value >= 0;
+const string = (value)=>typeof value === 'string';
+const boolean = (value)=>typeof value === 'boolean';
+const nullable = (check)=>(value)=>value === null || check(value);
+const list = (check)=>(value)=>Array.isArray(value) && value.every(check);
+const oneOf = (...values)=>(value)=>values.includes(value);
+const isObject = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value);
+const object = (fields, optional = {})=>(value)=>isObject(value) && Object.entries(fields).every(([key, check])=>check(value[key])) && Object.entries(optional).every(([key, check])=>value[key] === undefined || check(value[key]));
+const record = (check)=>(value)=>isObject(value) && Object.values(value).every(check);
+const id = (value)=>string(value) || number(value);
+const interval = (value)=>Array.isArray(value) && value.length === 2 && value.every(nullable(number));
+const timestamp = (value)=>typeof value === 'string' && Number.isFinite(new Date(value).getTime());
+const probability = (value)=>number(value) && value >= 0 && value <= 1;
+const status = oneOf('failing', 'ok', 'warning', 'insufficient');
+const shape = object({
+    experiment: id,
+    phase: count,
+    phaseKind: oneOf('test', 'rollout'),
+    computedAt: timestamp,
+    winnerArm: nullable(string),
+    minExposuresPerArm: count,
+    window: object({
+        from: timestamp,
+        to: timestamp
+    }),
+    method: oneOf('sequential', 'bayesian'),
+    alpha: probability,
+    alphaAdjusted: probability,
+    k: count,
+    params: object({
+        sequentialTuningParameter: number,
+        prior: object({
+            mean: number,
+            variance: number,
+            proper: boolean
+        }),
+        cupedLookbackDays: number,
+        caps: record(object({
+            type: oneOf('percentile', 'absolute'),
+            value: number,
+            resolvedCap: nullable(number)
+        }, {
+            historyUnits: count
+        })),
+        attributionWindows: record(number),
+        guardrailThresholds: record(number),
+        minSampleSizes: record(count),
+        bayesian: object({
+            ctw: probability,
+            risk: number
+        })
+    }),
+    exposures: object({
+        total: count,
+        perArm: record(count),
+        excludedMultiArm: count,
+        multiArmShare: probability,
+        armMismatch: count,
+        identityConflictShare: probability,
+        capped: record(count)
+    }),
+    srm: object({
+        p: probability,
+        flagged: boolean,
+        expected: record(probability)
+    }),
+    metrics: list(object({
+        metricId: id,
+        name: string,
+        kind: oneOf('binomial', 'count', 'revenue'),
+        role: oneOf('primary', 'secondary', 'guardrail'),
+        cupedApplied: boolean,
+        perArm: list(object({
+            arm: string,
+            n: count,
+            converters: count,
+            sum: number,
+            sumSquares: number,
+            mean: number,
+            variance: number
+        }, {
+            covariate: object({
+                preSum: number,
+                preSumSquares: number,
+                postPreSumOfProducts: number
+            }),
+            capped: object({
+                resolvedCap: number,
+                uncappedTotal: number,
+                cappedCount: count
+            })
+        })),
+        comparisons: list(object({
+            arm: string,
+            lift: number,
+            ci: interval,
+            ciAdjusted: interval,
+            significant: oneOf('better', 'worse', 'none')
+        }, {
+            pValue: probability,
+            pValueAdjusted: probability,
+            chanceToWin: probability,
+            risk: number
+        }))
+    }, {
+        unavailable: string
+    })),
+    guardrails: list(object({
+        metricId: id,
+        status
+    })),
+    power: object({
+        daysRemaining: nullable(number),
+        exposuresNeededPerArm: nullable(number),
+        lowerBound: boolean,
+        feasible: boolean
+    }),
+    verdict: object({
+        row: oneOf(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 'R1', 'R2', 'R3'),
+        code: oneOf('unavailable', 'data-problem', 'guardrail-failing', 'collecting', 'original-better', 'worse-none-better', 'winner', 'mixed', 'keep-running', 'no-difference', 'rollout-collecting', 'rollout-readout'),
+        finding: string,
+        action: nullable(string),
+        headline: string,
+        detail: string,
+        recommendedArm: nullable(string)
+    }, {
+        guardrailLine: string
+    }),
+    contentChanges: list(object({
+        at: timestamp,
+        doc: object({
+            collection: string,
+            id
+        }),
+        by: nullable(id)
+    }))
+});
+/** Validate the frozen JSON shape and headline/rollout invariants before storage.
+ * This also accepts the shared CORE-13/admin fixtures without any I/O.
+ */ export function validateSnapshot(value) {
+    if (!shape(value)) throw new TypeError('Invalid Snapshot shape (all numbers must be finite)');
+    const snapshot = value;
+    if (snapshot.phaseKind === 'test' && snapshot.winnerArm !== null || snapshot.phaseKind === 'rollout' && (snapshot.winnerArm === null || !(snapshot.winnerArm in snapshot.exposures.perArm)) || snapshot.verdict.headline !== snapshot.verdict.finding + (snapshot.verdict.action ? ` ${snapshot.verdict.action}` : '') || new Date(snapshot.window.to).getTime() < new Date(snapshot.window.from).getTime()) {
+        throw new TypeError('Invalid Snapshot invariants');
+    }
+}
+/** Assemble the already-computed snapshot at the pure/I/O boundary. */ export function assembleSnapshot(snapshot) {
+    validateSnapshot(snapshot);
+    return snapshot;
+}

package/dist/results/srm.d.ts

@@ -0,0 +1,9 @@
+import type { Snapshot } from '../types/snapshot.js';
+/** SRM uses exposed units and renormalised frozen weights, never allocation or
+ * assignment counts. Rollout callers pass only shipped/holdout weights (100-h,h).
+ * Zero-weight arms are omitted from checkSrm as required by its public contract.
+ */
+export declare function exposureSrm(arms: readonly {
+    key: string;
+    weight: number;
+}[], perArm: Readonly<Record<string, number>>): Snapshot['srm'];

package/dist/results/srm.js

@@ -0,0 +1,22 @@
+import { checkSrm } from '@delmaredigital/experiments-stats';
+/** SRM uses exposed units and renormalised frozen weights, never allocation or
+ * assignment counts. Rollout callers pass only shipped/holdout weights (100-h,h).
+ * Zero-weight arms are omitted from checkSrm as required by its public contract.
+ */ export function exposureSrm(arms, perArm) {
+    const active = arms.filter((arm)=>arm.weight > 0);
+    const weight = active.reduce((sum, arm)=>sum + arm.weight, 0);
+    if (weight <= 0) throw new RangeError('SRM requires positive weights');
+    const expected = Object.fromEntries(arms.map((arm)=>[
+            arm.key,
+            arm.weight / weight
+        ]));
+    // A unit exposed to an impossible arm is a splitting problem even though
+    // checkSrm deliberately omits zero-weight groups from its degrees of freedom.
+    const impossible = arms.some((arm)=>arm.weight === 0 && (perArm[arm.key] ?? 0) > 0);
+    const p = impossible ? 0 : active.length < 2 ? 1 : checkSrm(active.map((arm)=>perArm[arm.key] ?? 0), active.map((arm)=>arm.weight));
+    return {
+        p,
+        flagged: p < 0.001,
+        expected
+    };
+}

package/dist/results/verdict.d.ts

@@ -0,0 +1,82 @@
+import type { Snapshot } from '../types/snapshot.js';
+/** Already-computed results. Rollouts require the shipped winner's key and label;
+ * R3 reads that winner's comparison, regardless of comparison order. */
+export type VerdictInput = VerdictInputFields & ({
+    phaseKind: 'test';
+    winnerArm?: string;
+    winnerLabel?: string;
+} | {
+    phaseKind: 'rollout';
+    winnerArm: string;
+    winnerLabel: string;
+});
+interface VerdictInputFields {
+    status: 'running' | 'stopped' | 'decided';
+    method: 'sequential' | 'bayesian';
+    primary: {
+        name: string;
+        direction: 'increase' | 'decrease';
+        unavailable?: string;
+        /** Minimums apply per compared group, excluding the holdout in a test and
+         * including it in a rollout. Copy uses the smallest converter count. */
+        convertersPerArm: Array<{
+            arm: string;
+            kind: 'control' | 'variant' | 'holdout';
+            converters: number;
+        }>;
+        minSampleSize: number;
+        /** Include every computed comparison. Multiple winners use "Both" for two
+         * and "All N variants" for three or more; mixed/worse copy names each result. */
+        comparisons: Array<{
+            arm: string;
+            label: string;
+            significant: 'better' | 'worse' | 'none';
+            lift: number;
+            /** Snapshot ciAdjusted: alpha/k in a test; raw interval in a rollout (k=1). */
+            ci: [number | null, number | null];
+            /** Probability in [0, 1]; copy floors whole percentages, uses "more than
+             * 99%" at >=99.5%, and omits the parenthesis when unavailable. */
+            chanceToWin?: number;
+        }>;
+    };
+    exposures: {
+        perArm: Array<{
+            arm: string;
+            label: string;
+            kind: 'control' | 'variant' | 'holdout';
+            n: number;
+        }>;
+        minExposuresPerArm: number;
+        multiArmShare: number;
+    };
+    srm: {
+        flagged: boolean;
+    };
+    /** One status per guardrail across variants, holdout excluded: worst wins
+     * (failing > warning > insufficient > ok). A failing result names the variant
+     * that triggered it. R3 uses this order, with explicit harm wording for failing;
+     * no configured guardrails means no guardrailLine, never a claim of safety. */
+    guardrails: Array<{
+        name: string;
+    } & ({
+        status: 'failing';
+        worstArmLabel: string;
+    } | {
+        status: 'ok' | 'warning' | 'insufficient';
+        worstArmLabel?: string;
+    })>;
+    /** Additional days needed, rounded up by CORE-15a: 0 = already enough data,
+     * null = unknown. Infeasible or >90 days uses the long-duration copy; positive
+     * days use an estimate; 0/null with feasible=true runs to the planned end date. */
+    power: {
+        daysRemaining: number | null;
+        feasible: boolean;
+    };
+    plannedDurationPassed: boolean;
+    /** Reserved for future use; "the Original" remains literal UI vocabulary. */
+    originalLabel: string;
+    controlArm: string;
+}
+/** Apply spec §8.5 in order to already-computed results; no inference is performed here. */
+export declare function computeVerdict(input: VerdictInput): Snapshot['verdict'];
+export {};

package/dist/results/verdict.js

@@ -0,0 +1,85 @@
+function percent(value) {
+    if (value === null) return '…';
+    const rounded = Math.round(value * 100);
+    return `${rounded >= 0 ? '+' : ''}${rounded}%`;
+}
+function guardrailLine(input) {
+    if (input.guardrails.length === 0) return undefined;
+    const failing = input.guardrails.find((item)=>item.status === 'failing');
+    if (failing) return `Harm detected: ${failing.name} is worse since shipping.`;
+    const warning = input.guardrails.find((item)=>item.status === 'warning');
+    if (warning) return `Watch ${warning.name}: trending worse.`;
+    if (input.guardrails.some((item)=>item.status === 'insufficient')) return 'Too little data to rule out harm';
+    return 'No harm detected so far';
+}
+function labels(items) {
+    return items.length < 2 ? items[0].label : `${items.slice(0, -1).map((item)=>item.label).join(', ')} and ${items.at(-1).label}`;
+}
+function chance(value) {
+    if (value === undefined) return '';
+    return value >= 0.995 ? ' (more than 99%)' : ` (${Math.floor(value * 100)}%)`;
+}
+/** Apply spec §8.5 in order to already-computed results; no inference is performed here. */ export function computeVerdict(input) {
+    const rollout = input.phaseKind === 'rollout';
+    const make = (row, code, finding, action, detail, recommendedArm, line)=>({
+            row,
+            code,
+            finding,
+            action,
+            headline: finding + (action ? ` ${action}` : ''),
+            detail,
+            recommendedArm,
+            ...line === undefined ? {} : {
+                guardrailLine: line
+            }
+        });
+    if (input.primary.unavailable !== undefined) {
+        return make(rollout ? 'R1' : 1, 'unavailable', `Results unavailable: ${input.primary.name} could not be read.`, 'Recompute; if it persists, contact a developer.', 'The main outcome could not be loaded.', null);
+    }
+    if (input.srm.flagged || input.exposures.multiArmShare >= 0.01) {
+        return make(rollout ? 'R1' : 2, 'data-problem', "Data problem: traffic isn't splitting as set.", "Don't trust these results. Check for caching or a page placed twice; contact a developer.", 'The people counted do not match the expected split.', null);
+    }
+    const compared = input.exposures.perArm.filter((item)=>rollout || item.kind !== 'holdout');
+    const minimum = compared.length ? Math.min(...compared.map((item)=>item.n)) : 0;
+    const converters = input.primary.convertersPerArm.filter((item)=>rollout || item.kind !== 'holdout');
+    const minimumConverters = converters.length ? Math.min(...converters.map((item)=>item.converters)) : 0;
+    const collecting = minimum < input.exposures.minExposuresPerArm || minimumConverters < input.primary.minSampleSize;
+    if (input.phaseKind === 'rollout') {
+        const winner = input.winnerLabel;
+        if (collecting) return make('R2', 'rollout-collecting', `Since shipping ${winner}: collecting data (${minimum} of ${input.exposures.minExposuresPerArm} people, ${minimumConverters} of ${input.primary.minSampleSize} conversions).`, null, 'More people and conversions are needed to describe the shipped result.', null);
+        const comparison = input.primary.comparisons.find((item)=>item.arm === input.winnerArm);
+        const lift = comparison?.lift ?? null;
+        const ci = comparison?.ci ?? [
+            null,
+            null
+        ];
+        return make('R3', 'rollout-readout', `Since shipping ${winner}: ${percent(lift)} vs the holdout (CI ${percent(ci[0])} to ${percent(ci[1])}).`, null, 'This describes the shipped version compared with people still seeing the Original.', null, guardrailLine(input));
+    }
+    const failing = input.guardrails.find((item)=>item.status === 'failing');
+    if (failing) return make(3, 'guardrail-failing', `Stop: ${failing.worstArmLabel} harms ${failing.name}.`, null, 'An outcome that must stay safe has become worse.', input.controlArm);
+    if (collecting) return make(4, 'collecting', input.status === 'stopped' ? 'Stopped before enough data was collected.' : `Collecting data: ${minimum} of ${input.exposures.minExposuresPerArm} people, ${minimumConverters} of ${input.primary.minSampleSize} conversions.`, null, 'More people or conversions are needed before drawing a conclusion.', null);
+    const variantKeys = new Set(compared.filter((item)=>item.kind === 'variant').map((item)=>item.arm));
+    const variants = input.primary.comparisons.filter((item)=>variantKeys.has(item.arm));
+    const better = variants.filter((item)=>item.significant === 'better');
+    const worse = variants.filter((item)=>item.significant === 'worse');
+    const direction = input.primary.direction === 'decrease' ? -1 : 1;
+    const best = [
+        ...better
+    ].sort((a, b)=>direction * (b.lift - a.lift))[0];
+    const worst = worse[0];
+    if (variants.length > 0 && worse.length === variants.length) return make(5, 'original-better', 'The Original is better.', 'Decide for the Original.', 'Every tested alternative performed worse.', input.controlArm);
+    if (worst && !best) return make(6, 'worse-none-better', `${labels(worse)} ${worse.length === 1 ? 'is' : 'are'} worse; no variant is better.`, `Decide for the Original or restart without ${worse.length === 1 ? 'it' : 'them'}.`, 'At least one alternative performed worse and none improved the main outcome.', input.controlArm);
+    if (best && !worst) {
+        const finding = better.length >= 2 ? `${better.length === 2 ? 'Both' : `All ${better.length} variants`} beat the Original; not tested against each other — ${best.label} has the larger improvement.` : input.method === 'bayesian' ? `${best.label} is very likely better${chance(best.chanceToWin)}.` : `${best.label} is statistically better: ${percent(best.lift)} (CI ${percent(best.ci[0])} to ${percent(best.ci[1])}).`;
+        return make(7, 'winner', finding, null, 'The main outcome improved compared with the Original.', best.arm, guardrailLine(input));
+    }
+    if (best && worst) return make(8, 'mixed', `Mixed: ${labels(better)} better, ${labels(worse)} worse.`, 'Review before deciding.', 'The tested alternatives moved the main outcome in different directions.', best.arm);
+    if (input.status === 'running' && !input.plannedDurationPassed) {
+        if (input.power.feasible === false || input.power.daysRemaining !== null && input.power.daysRemaining > 90) {
+            return make(9, 'keep-running', 'A clear answer would take more than 90 days at this traffic.', 'Consider a bigger change or a different metric.', 'Current traffic is too low for a timely answer.', null);
+        }
+        const action = input.power.daysRemaining !== null && input.power.daysRemaining >= 1 ? `Keep running about ${Math.ceil(input.power.daysRemaining)} days.` : 'Keep running to the planned end date.';
+        return make(9, 'keep-running', 'No clear winner yet.', action, 'The current results do not yet distinguish the tested versions.', null);
+    }
+    return make(10, 'no-difference', 'No detectable difference at this size.', null, 'The data collected did not show a clear improvement or decline.', input.controlArm);
+}

package/dist/runtime/assign.d.ts

@@ -0,0 +1,23 @@
+import type { Assignments } from '../types/assignments.js';
+import type { Attributes } from '../types/contracts.js';
+import type { Manifest } from '../types/manifest.js';
+import { type AssignmentUnit } from './eligibility.js';
+import type { AttributeKeys } from './targeting.js';
+/** Deferred slugs travel on the wire and are evaluated after server session resolution. */
+export interface AssignmentResult extends Assignments {
+    deferred: string[];
+}
+export interface AssignOptions {
+    now: number;
+    staff?: boolean;
+    bot?: boolean;
+    preview?: boolean;
+    sessionUnknown?: boolean;
+    method?: string;
+    attributeKeys?: AttributeKeys;
+    onInvalid?(slug: string, reason: string): void;
+}
+/** Also used after header decoding so flag results always reflect the rendered content. */
+export declare function fillFlagPoints(result: Assignments, manifest: Manifest): void;
+/** Pure shared assignment path; time is supplied by the request's caller. */
+export declare function assign(manifest: Manifest, unit: AssignmentUnit, attributes: Attributes, opts: AssignOptions): AssignmentResult;

package/dist/runtime/assign.js

@@ -0,0 +1,104 @@
+import { assignArm, hash, inRange, rolloutBucketRanges } from '@delmaredigital/experiments-stats';
+import { eligibility } from './eligibility.js';
+/** Also used after header decoding so flag results always reflect the rendered content. */ export function fillFlagPoints(result, manifest) {
+    for (const [id, value] of Object.entries(manifest.flagDefaults)){
+        result.flagPoints[id] = {
+            arm: value.winnerArm,
+            params: {
+                ...value.params
+            },
+            source: 'default',
+            exposable: false
+        };
+    }
+    for (const experiment of manifest.experiments){
+        const assignment = result.bySlug[experiment.slug];
+        if (!experiment.flagPoint || !assignment) continue;
+        const contentArm = experiment.arms.find((arm)=>arm.key === assignment.arm && arm.kind !== 'holdout') ?? experiment.arms.find((arm)=>arm.kind === 'control');
+        result.flagPoints[experiment.flagPoint] = {
+            arm: assignment.arm,
+            params: {
+                ...contentArm?.params
+            },
+            source: 'experiment',
+            experiment: experiment.slug,
+            experimentId: experiment.id,
+            phase: experiment.phase,
+            policy: assignment.policy,
+            exposable: assignment.exposable
+        };
+    }
+}
+/** Pure shared assignment path; time is supplied by the request's caller. */ export function assign(manifest, unit, attributes, opts) {
+    const result = {
+        revision: manifest.revision,
+        visitorId: unit.visitorId,
+        userId: unit.userId,
+        bySlug: Object.create(null),
+        flagPoints: Object.create(null),
+        archivedWinners: {
+            ...manifest.archivedWinners
+        },
+        deferred: [],
+        staff: opts.staff ?? attributes.staff === true,
+        bot: opts.bot ?? false,
+        preview: opts.preview ?? false,
+        sessionUnknown: opts.sessionUnknown ?? unit.sessionUnknown ?? false,
+        method: opts.method ?? 'GET'
+    };
+    for (const experiment of manifest.experiments){
+        if (experiment.status !== 'running' && experiment.status !== 'decided') continue;
+        if ((experiment.status === 'decided' || experiment.phaseKind === 'rollout') && !experiment.arms.some((arm)=>arm.key === experiment.winnerArm)) {
+            opts.onInvalid?.(experiment.slug, 'invalid-winner-arm');
+            continue;
+        }
+        if (experiment.phaseKind === 'rollout' && !experiment.arms.some((arm)=>arm.key === experiment.holdoutKey)) {
+            opts.onInvalid?.(experiment.slug, 'invalid-holdout-key');
+            continue;
+        }
+        const eligible = eligibility(experiment, unit, attributes, {
+            ...opts,
+            sessionUnknown: result.sessionUnknown
+        });
+        if (eligible.kind === 'deferred') {
+            result.deferred.push(experiment.slug);
+            continue;
+        }
+        const control = experiment.arms.find((arm)=>arm.kind === 'control');
+        let arm = control.key, exposable = false;
+        if (eligible.kind === 'eligible') {
+            if (experiment.status === 'decided' && !experiment.holdoutKey) {
+                arm = experiment.winnerArm;
+            } else if (experiment.phaseKind === 'rollout') {
+                if (!experiment.seed.endsWith('|')) throw new RangeError('Assignment seed must end in |');
+                const ranges = rolloutBucketRanges(experiment.arms.map((arm)=>arm.weight), eligible.coverage);
+                const bucket = hash(experiment.seed, eligible.unitId, 2);
+                const holdout = eligible.inLayer && inRange(bucket, ranges.holdout);
+                arm = holdout ? experiment.holdoutKey : experiment.winnerArm;
+                exposable = eligible.inLayer && (holdout || inRange(bucket, ranges.winner));
+            } else if (eligible.inLayer) {
+                const index = assignArm({
+                    seed: experiment.seed,
+                    unitId: eligible.unitId,
+                    weights: experiment.arms.map((arm)=>arm.weight),
+                    coverage: eligible.coverage
+                });
+                if (index !== -1) {
+                    arm = experiment.arms[index].key;
+                    exposable = true;
+                }
+            }
+        }
+        result.bySlug[experiment.slug] = {
+            slug: experiment.slug,
+            experimentId: experiment.id,
+            arm,
+            phase: experiment.phase,
+            exposable: exposable && !result.staff && !result.bot && !result.preview && result.method.toUpperCase() !== 'HEAD',
+            policy: experiment.exposurePolicy,
+            source: eligible.kind === 'ineligible' ? 'fallback' : 'recomputed'
+        };
+    }
+    fillFlagPoints(result, manifest);
+    return result;
+}

package/dist/runtime/bot.d.ts

@@ -0,0 +1 @@
+export declare function isBot(userAgent: string | null | undefined): boolean;

package/dist/runtime/bot.js

@@ -0,0 +1,7 @@
+// Spec §13 Q13: built-in UA list only, with no external lookup or dependency.
+// `bot` is matched as a suffix of a crawler name (AhrefsBot, GPTBot, AdsBot-Google) but not
+// inside device names (CUBOT); the Pinterest app is not a bot, Pinterestbot is.
+const BOT_UA = /(?<!cu)bot\b|crawler|spider|slurp|bingpreview|facebookexternalhit|facebot|whatsapp|google-inspectiontool|headlesschrome|lighthouse|pagespeed|pingdom|uptimerobot|\bcurl\b|\bwget\b|python-requests|go-http-client/i;
+export function isBot(userAgent) {
+    return typeof userAgent === 'string' && BOT_UA.test(userAgent);
+}

package/dist/runtime/cookie.d.ts

@@ -0,0 +1,17 @@
+import { NextRequest } from 'next/server.js';
+import type { ExperimentsProxyRuntime } from '../types/runtime.js';
+export declare function mintUnitId(): string;
+export declare function encodeUnitCookie(unitId: string, secrets: readonly string[]): string;
+export declare function verifyUnitCookie(cookie: string | undefined, secrets: readonly string[]): string | null;
+/** Use Next's cookie selection everywhere: the last cookie of a given name wins. */
+export declare function readUnitCookie(input: Headers | NextRequest, runtime: Pick<ExperimentsProxyRuntime, 'cookie' | 'secrets'>): string | null;
+export declare function cookieAttributes(runtime: Pick<ExperimentsProxyRuntime, 'cookie'>, { https }: {
+    https: boolean;
+}): {
+    domain?: string | undefined;
+    secure?: boolean | undefined;
+    httpOnly: boolean;
+    sameSite: "lax";
+    path: string;
+    maxAge: number;
+};

package/dist/runtime/cookie.js

@@ -0,0 +1,35 @@
+import { randomBytes } from 'node:crypto';
+import { NextRequest } from 'next/server.js';
+import { sign, verify } from './signing.js';
+export function mintUnitId() {
+    return randomBytes(16).toString('base64url');
+}
+export function encodeUnitCookie(unitId, secrets) {
+    if (!/^[A-Za-z0-9_-]+$/.test(unitId)) throw new Error('Invalid unit id');
+    return `${unitId}.${sign(`xp:unit:${unitId}`, secrets)}`;
+}
+export function verifyUnitCookie(cookie, secrets) {
+    if (typeof cookie !== 'string') return null;
+    const match = /^([A-Za-z0-9_-]+)\.([A-Za-z0-9_-]{43})$/.exec(cookie);
+    return match && verify(`xp:unit:${match[1]}`, match[2], secrets) ? match[1] : null;
+}
+/** Use Next's cookie selection everywhere: the last cookie of a given name wins. */ export function readUnitCookie(input, runtime) {
+    const request = input instanceof Headers ? new NextRequest('https://xp.invalid/', {
+        headers: input
+    }) : input;
+    return verifyUnitCookie(request.cookies.get(runtime.cookie.name)?.value, runtime.secrets);
+}
+export function cookieAttributes(runtime, { https }) {
+    return {
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+        maxAge: runtime.cookie.maxAgeDays * 86400,
+        ...https ? {
+            secure: true
+        } : {},
+        ...runtime.cookie.domain ? {
+            domain: runtime.cookie.domain
+        } : {}
+    };
+}

package/dist/runtime/eligibility.d.ts

@@ -0,0 +1,22 @@
+import type { Attributes } from '../types/contracts.js';
+import type { ManifestExperiment } from '../types/manifest.js';
+import { type AttributeKeys } from './targeting.js';
+export interface AssignmentUnit {
+    visitorId?: string;
+    userId?: string;
+    sessionUnknown?: boolean;
+}
+export type Eligibility = {
+    kind: 'deferred';
+} | {
+    kind: 'ineligible';
+} | {
+    kind: 'eligible';
+    unitId: string;
+    inLayer: boolean;
+    coverage: number;
+};
+export declare function eligibility(experiment: ManifestExperiment, unit: AssignmentUnit, attributes: Attributes, opts?: {
+    sessionUnknown?: boolean;
+    attributeKeys?: AttributeKeys;
+}): Eligibility;

package/dist/runtime/eligibility.js

@@ -0,0 +1,20 @@
+import { layerSlice } from '@delmaredigital/experiments-stats';
+import { evaluateTargeting } from './targeting.js';
+export function eligibility(experiment, unit, attributes, opts = {}) {
+    const unitId = experiment.unitType === 'visitor' ? unit.visitorId : unit.userId;
+    if (!unitId) return {
+        kind: experiment.unitType === 'user' ? 'deferred' : 'ineligible'
+    };
+    if ((opts.sessionUnknown ?? unit.sessionUnknown) && experiment.targeting.some((rule)=>rule.attribute === 'loggedIn' || rule.attribute === 'staff')) return {
+        kind: 'deferred'
+    };
+    if (!evaluateTargeting(experiment.targeting, attributes, opts.attributeKeys)) return {
+        kind: 'ineligible'
+    };
+    return {
+        kind: 'eligible',
+        unitId,
+        inLayer: !experiment.layer || experiment.layer.slices.includes(layerSlice(experiment.layer.slug, unitId)),
+        coverage: experiment.layer ? 1 : experiment.coverage
+    };
+}