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

package/dist/results/analyse.js

@@ -0,0 +1,378 @@
+import { DEFAULT_GAUSSIAN_PRIOR, bonferroniAlpha, capValues, createThetaAdjustedStatistics, effectBayesianABTest, sequentialOneSidedTreatmentGreaterTTest, sequentialOneSidedTreatmentLesserTTest, sequentialTwoSidedTTest, statisticMean, statisticVariance } from '@delmaredigital/experiments-stats';
+import { timestampMs } from './aggregate.js';
+import { outcomeStatistic } from './cuped.js';
+import { guardrailStatus } from './guardrails.js';
+import { remainingPower } from './power.js';
+import { assembleSnapshot, jsonInterval } from './snapshot.js';
+import { exposureSrm } from './srm.js';
+import { computeVerdict } from './verdict.js';
+const severity = {
+    ok: 0,
+    insufficient: 1,
+    warning: 2,
+    failing: 3
+};
+/** Pure exposure-based analysis (§6, §7.6, §8.4). All inference, moments, capping,
+ * CUPED, power and SRM are delegated to experiments-stats; now is always injected.
+ */ export function analysePhase(input) {
+    const { phase, units } = input;
+    const { analysis } = phase;
+    const alpha = analysis.alpha ?? 0.05;
+    const prior = analysis.prior ?? DEFAULT_GAUSSIAN_PRIOR;
+    const bayesian = analysis.bayesian ?? {
+        ctw: 0.95,
+        risk: 0.0125
+    };
+    const rollout = phase.phaseKind === 'rollout';
+    const baselineArm = phase.arms.find((arm)=>arm.kind === (rollout ? 'holdout' : 'control'));
+    const winner = rollout ? phase.arms.find((arm)=>arm.key === input.winnerArm && arm.kind !== 'holdout') : undefined;
+    if (!baselineArm || rollout && (!winner || phase.arms.length !== 2)) throw new RangeError('Phase comparison baseline or shipped arm is missing');
+    const compared = phase.arms.filter((arm)=>rollout ? arm.key === winner.key : arm.kind === 'variant');
+    const k = compared.length;
+    const alphaAdjusted = analysis.method === 'sequential' ? bonferroniAlpha(alpha, k) : alpha;
+    const definitions = phase.metricDefinitions.map((metric)=>({
+            ...metric,
+            attributionWindowHours: analysis.attributionWindowHours ?? metric.attributionWindowHours,
+            minSampleSize: analysis.minSampleSizes?.[metric.metricId] ?? metric.minSampleSize,
+            guardrailThreshold: analysis.guardrailThresholds?.[metric.metricId] ?? metric.guardrailThreshold
+        }));
+    const primaryDefinition = definitions.find((metric)=>metric.role === 'primary');
+    if (!primaryDefinition || phase.metricDefinitions.filter((metric)=>metric.role === 'primary').length !== 1) {
+        throw new RangeError('Phase must have exactly one primary metric');
+    }
+    if (new Set(phase.metricDefinitions.map((metric)=>String(metric.metricId))).size !== phase.metricDefinitions.length || new Set(input.metricData.map((metric)=>String(metric.metricId))).size !== input.metricData.length) {
+        throw new RangeError('Duplicate metric id');
+    }
+    const from = timestampMs(phase.startedAt);
+    const now = timestampMs(input.now);
+    const to = Math.min(now, phase.endedAt == null ? now : timestampMs(phase.endedAt));
+    if (to < from) throw new RangeError('Analysis window ends before the phase starts');
+    const byArm = new Map(phase.arms.map((arm)=>[
+            arm.key,
+            []
+        ]));
+    for (const [id, unit] of units){
+        const ids = byArm.get(unit.arm);
+        if (!ids) throw new RangeError('Exposed unit has an unknown arm');
+        ids.push(id);
+    }
+    const perArm = Object.fromEntries([
+        ...byArm
+    ].map(([arm, ids])=>[
+            arm,
+            ids.length
+        ]));
+    const excludedMultiArm = input.excludedMultiArm ?? 0;
+    const exposures = {
+        total: units.size,
+        perArm,
+        excludedMultiArm,
+        multiArmShare: units.size + excludedMultiArm === 0 ? 0 : excludedMultiArm / (units.size + excludedMultiArm),
+        armMismatch: input.armMismatch ?? 0,
+        identityConflictShare: input.identityConflictShare ?? 0,
+        capped: {}
+    };
+    const params = {
+        sequentialTuningParameter: analysis.sequentialTuningParameter,
+        prior: {
+            ...prior
+        },
+        cupedLookbackDays: analysis.cupedLookbackDays ?? 14,
+        bayesian: {
+            ...bayesian
+        },
+        caps: {},
+        attributionWindows: {},
+        guardrailThresholds: {},
+        minSampleSizes: {}
+    };
+    const guardrails = [];
+    const verdictGuardrails = [];
+    let primaryStatistics;
+    const metrics = definitions.map((definition)=>{
+        const { metricId, kind } = definition;
+        params.attributionWindows[metricId] = definition.attributionWindowHours;
+        params.minSampleSizes[metricId] = definition.minSampleSize;
+        if (definition.role === 'guardrail') params.guardrailThresholds[metricId] = definition.guardrailThreshold ?? 0.05;
+        if (kind === 'revenue' && definition.capping) params.caps[metricId] = {
+            ...definition.capping,
+            resolvedCap: definition.resolvedCap ?? null,
+            ...definition.historyUnits === undefined ? {} : {
+                historyUnits: definition.historyUnits
+            }
+        };
+        exposures.capped[metricId] = 0;
+        const data = input.metricData.find((item)=>item.metricId === metricId);
+        const metric = {
+            metricId,
+            name: definition.name,
+            kind,
+            role: definition.role,
+            cupedApplied: false,
+            perArm: [],
+            comparisons: []
+        };
+        let worst = 'ok';
+        let worstArmLabel = compared[0]?.label ?? '';
+        try {
+            if (!data || data.unavailable !== undefined) throw new Error(data?.unavailable ?? 'Metric data was not supplied');
+            const stats = new Map();
+            const cap = kind === 'revenue' ? definition.resolvedCap ?? null : null;
+            const useCovariates = analysis.cuped === 'auto' && data.covariates !== undefined && data.covariates.size > 0;
+            for (const arm of phase.arms){
+                const ids = byArm.get(arm.key);
+                const values = ids.map((id)=>data.values.get(id) ?? 0);
+                if (!values.every(Number.isFinite)) throw new RangeError('Metric values must be finite');
+                const capped = capValues(values, cap);
+                const rawPre = useCovariates ? ids.map((id)=>data.covariates.get(id) ?? 0) : undefined;
+                if (rawPre && !rawPre.every(Number.isFinite)) throw new RangeError('Covariates must be finite');
+                const pre = rawPre && capValues(rawPre, cap).values;
+                const built = outcomeStatistic(kind, capped.values, pre);
+                stats.set(arm.key, built.statistic);
+                exposures.capped[metricId] += capped.cappedCount;
+                // These are the observed post-period moments; pair-specific theta is
+                // applied by the stats engine for inference, never to the displayed mean.
+                const post = outcomeStatistic(kind, capped.values).statistic;
+                metric.perArm.push({
+                    arm: arm.key,
+                    ...built.moments,
+                    converters: values.filter((value)=>value > 0).length,
+                    mean: statisticMean(post),
+                    variance: statisticVariance(post),
+                    ...built.covariate ? {
+                        covariate: built.covariate
+                    } : {},
+                    ...cap === null ? {} : {
+                        capped: {
+                            resolvedCap: cap,
+                            uncappedTotal: capped.uncappedTotal,
+                            cappedCount: capped.cappedCount
+                        }
+                    }
+                });
+            }
+            if (definition.role === 'primary') primaryStatistics = stats;
+            for (const arm of compared){
+                const [a, b] = createThetaAdjustedStatistics(stats.get(baselineArm.key), stats.get(arm.key));
+                metric.cupedApplied ||= a.type === 'regressionAdjusted' && b.type === 'regressionAdjusted';
+                const config = {
+                    alpha,
+                    sequentialTuningParameter: analysis.sequentialTuningParameter
+                };
+                const inverse = definition.direction === 'decrease';
+                let comparison;
+                let status = 'insufficient';
+                if (analysis.method === 'sequential') {
+                    const raw = sequentialTwoSidedTTest(a, b, config);
+                    const adjusted = definition.role === 'primary' ? sequentialTwoSidedTTest(a, b, {
+                        ...config,
+                        alpha: alphaAdjusted
+                    }) : raw;
+                    const ci = adjusted.errorMessage ? [
+                        null,
+                        null
+                    ] : jsonInterval(adjusted.ci);
+                    const positive = ci[0] !== null && ci[0] > 0;
+                    const negative = ci[1] !== null && ci[1] < 0;
+                    comparison = {
+                        arm: arm.key,
+                        lift: raw.expected,
+                        ci: raw.errorMessage ? [
+                            null,
+                            null
+                        ] : jsonInterval(raw.ci),
+                        ciAdjusted: ci,
+                        ...raw.pValue === null ? {} : {
+                            pValue: raw.pValue
+                        },
+                        ...adjusted.pValue === null ? {} : {
+                            pValueAdjusted: Math.min(1, adjusted.pValue * (definition.role === 'primary' ? k : 1))
+                        },
+                        significant: positive ? inverse ? 'worse' : 'better' : negative ? inverse ? 'better' : 'worse' : 'none'
+                    };
+                    if (definition.role === 'guardrail') {
+                        const greater = sequentialOneSidedTreatmentGreaterTTest(a, b, config);
+                        const lesser = sequentialOneSidedTreatmentLesserTTest(a, b, config);
+                        status = guardrailStatus({
+                            method: 'sequential',
+                            direction: definition.direction,
+                            n: Math.min(...metric.perArm.filter((group)=>group.arm === arm.key || group.arm === baselineArm.key).map((group)=>group.converters)),
+                            minSampleSize: definition.minSampleSize,
+                            threshold: definition.guardrailThreshold ?? 0.05,
+                            pointEstimate: raw.expected,
+                            lowerBound: greater.errorMessage ? null : jsonInterval(greater.ci)[0],
+                            upperBound: lesser.errorMessage ? null : jsonInterval(lesser.ci)[1]
+                        });
+                    }
+                } else {
+                    const result = effectBayesianABTest(a, b, {
+                        alpha,
+                        priorEffect: prior,
+                        inverse
+                    });
+                    comparison = {
+                        arm: arm.key,
+                        lift: result.expected,
+                        ci: result.errorMessage ? [
+                            null,
+                            null
+                        ] : jsonInterval(result.ci),
+                        ciAdjusted: result.errorMessage ? [
+                            null,
+                            null
+                        ] : jsonInterval(result.ci),
+                        chanceToWin: result.chanceToWin,
+                        risk: result.risk[1],
+                        significant: result.errorMessage ? 'none' : result.chanceToWin >= bayesian.ctw ? 'better' : result.chanceToWin <= 1 - bayesian.ctw ? 'worse' : 'none'
+                    };
+                    if (definition.role === 'guardrail') {
+                        const safety = effectBayesianABTest(a, b, {
+                            alpha: 0.10,
+                            priorEffect: prior,
+                            inverse
+                        });
+                        status = guardrailStatus({
+                            method: 'bayesian',
+                            direction: definition.direction,
+                            n: Math.min(...metric.perArm.filter((group)=>group.arm === arm.key || group.arm === baselineArm.key).map((group)=>group.converters)),
+                            minSampleSize: definition.minSampleSize,
+                            threshold: definition.guardrailThreshold ?? 0.05,
+                            pointEstimate: result.expected,
+                            lowerBound: safety.errorMessage ? null : jsonInterval(safety.ci)[0],
+                            upperBound: safety.errorMessage ? null : jsonInterval(safety.ci)[1],
+                            pWorse: safety.errorMessage ? undefined : 1 - safety.chanceToWin
+                        });
+                    }
+                }
+                metric.comparisons.push(comparison);
+                if (severity[status] > severity[worst]) {
+                    worst = status;
+                    worstArmLabel = arm.label;
+                }
+            }
+        } catch (error) {
+            metric.unavailable = error instanceof Error ? error.message : 'Metric could not be analysed';
+            metric.perArm = [];
+            metric.comparisons = [];
+            metric.cupedApplied = false;
+            exposures.capped[metricId] = 0;
+            if (definition.role === 'primary') primaryStatistics = undefined;
+            worst = 'insufficient';
+        }
+        if (definition.role === 'guardrail') {
+            guardrails.push({
+                metricId,
+                status: worst
+            });
+            verdictGuardrails.push(worst === 'failing' ? {
+                name: definition.name,
+                status: worst,
+                worstArmLabel
+            } : {
+                name: definition.name,
+                status: worst
+            });
+        }
+        return metric;
+    });
+    const primary = metrics.find((metric)=>metric.role === 'primary');
+    const srm = exposureSrm(phase.arms, perArm);
+    let power = {
+        daysRemaining: null,
+        exposuresNeededPerArm: null,
+        lowerBound: analysis.method === 'sequential',
+        feasible: true
+    };
+    const common = {
+        status: input.status,
+        method: analysis.method,
+        primary: {
+            name: primary.name,
+            direction: primaryDefinition.direction,
+            ...primary.unavailable === undefined ? {} : {
+                unavailable: primary.unavailable
+            },
+            minSampleSize: primaryDefinition.minSampleSize,
+            convertersPerArm: primary.perArm.map((group)=>({
+                    arm: group.arm,
+                    kind: phase.arms.find((arm)=>arm.key === group.arm).kind,
+                    converters: group.converters
+                })),
+            comparisons: primary.comparisons.map((comparison)=>({
+                    ...comparison,
+                    ci: comparison.ciAdjusted,
+                    label: phase.arms.find((arm)=>arm.key === comparison.arm).label
+                }))
+        },
+        exposures: {
+            perArm: phase.arms.map((arm)=>({
+                    arm: arm.key,
+                    label: arm.label,
+                    kind: arm.kind,
+                    n: perArm[arm.key]
+                })),
+            minExposuresPerArm: analysis.minExposuresPerArm,
+            multiArmShare: exposures.multiArmShare
+        },
+        srm,
+        guardrails: verdictGuardrails,
+        power,
+        plannedDurationPassed: to - from >= analysis.plannedDurationDays * 86_400_000,
+        originalLabel: phase.arms.find((arm)=>arm.kind === 'control')?.label ?? 'Original',
+        controlArm: baselineArm.key
+    };
+    const verdictInput = rollout ? {
+        ...common,
+        phaseKind: 'rollout',
+        winnerArm: winner.key,
+        winnerLabel: winner.label
+    } : {
+        ...common,
+        phaseKind: 'test'
+    };
+    let verdict = computeVerdict(verdictInput);
+    if (input.status === 'running' && !rollout && (verdict.row === 4 || verdict.row === 9) && primaryStatistics) {
+        power = remainingPower({
+            baseline: primaryStatistics.get(baselineArm.key),
+            variants: compared.map((arm)=>primaryStatistics.get(arm.key)),
+            elapsedDays: (to - from) / 86_400_000,
+            alpha: alphaAdjusted,
+            method: analysis.method,
+            prior,
+            sequentialTuningParameter: analysis.sequentialTuningParameter
+        });
+        verdict = computeVerdict({
+            ...verdictInput,
+            power
+        });
+    }
+    return assembleSnapshot({
+        experiment: phase.experiment,
+        phase: phase.phase,
+        phaseKind: phase.phaseKind,
+        computedAt: new Date(now).toISOString(),
+        window: {
+            from: new Date(from).toISOString(),
+            to: new Date(to).toISOString()
+        },
+        method: analysis.method,
+        alpha,
+        alphaAdjusted,
+        k,
+        winnerArm: winner?.key ?? null,
+        minExposuresPerArm: analysis.minExposuresPerArm,
+        params,
+        exposures,
+        srm,
+        metrics,
+        guardrails,
+        power,
+        verdict,
+        contentChanges: (phase.contentChanges ?? []).map((change)=>({
+                ...change,
+                doc: {
+                    ...change.doc
+                }
+            }))
+    });
+}

package/dist/results/cuped.d.ts

@@ -0,0 +1,16 @@
+import { summarizeUnits } from '@delmaredigital/experiments-stats';
+import type { TestStatistic } from '@delmaredigital/experiments-stats';
+import type { MetricSource } from '../types/contracts.js';
+/** Build candidate CUPED statistics; the stats engine pools each pair, infers theta,
+ * and falls back to the post statistic when pre-period variance/covariance is zero.
+ * Missing units in a supplied pre-period map are zero-filled by the caller.
+ */
+export declare function outcomeStatistic(kind: MetricSource['kind'], values: readonly number[], covariates?: readonly number[]): {
+    statistic: TestStatistic;
+    moments: ReturnType<typeof summarizeUnits>;
+    covariate?: {
+        preSum: number;
+        preSumSquares: number;
+        postPreSumOfProducts: number;
+    };
+};

package/dist/results/cuped.js

@@ -0,0 +1,31 @@
+import { buildRegressionAdjustedStatistic, buildStatistic, summarizeUnits, summarizeUnitsWithCovariate } from '@delmaredigital/experiments-stats';
+/** Build candidate CUPED statistics; the stats engine pools each pair, infers theta,
+ * and falls back to the post statistic when pre-period variance/covariance is zero.
+ * Missing units in a supplied pre-period map are zero-filled by the caller.
+ */ export function outcomeStatistic(kind, values, covariates) {
+    if (!values.every(Number.isFinite) || covariates && !covariates.every(Number.isFinite)) {
+        throw new RangeError('Metric values and covariates must be finite');
+    }
+    if (kind === 'binomial' && (values.some((value)=>value !== 0 && value !== 1) || covariates?.some((value)=>value !== 0 && value !== 1))) {
+        throw new RangeError('Binomial values and covariates must be 0 or 1');
+    }
+    const moments = summarizeUnits(values);
+    if (covariates === undefined) return {
+        moments,
+        statistic: buildStatistic(kind, moments)
+    };
+    const { preSum, preSumSquares, postPreSumOfProducts } = summarizeUnitsWithCovariate(values, covariates);
+    const covariate = {
+        preSum,
+        preSumSquares,
+        postPreSumOfProducts
+    };
+    return {
+        moments,
+        covariate,
+        statistic: buildRegressionAdjustedStatistic(kind, {
+            ...moments,
+            ...covariate
+        })
+    };
+}

package/dist/results/decideGuard.d.ts

@@ -0,0 +1,3 @@
+import type { Snapshot } from '../types/snapshot.js';
+/** A true result means required: true: typed confirmation and a note are both required (plan §2.7). */
+export declare function decideGuard(snapshot: Snapshot | null, chosenArm: string): boolean;

package/dist/results/decideGuard.js

@@ -0,0 +1,8 @@
+/** A true result means required: true: typed confirmation and a note are both required (plan §2.7). */ export function decideGuard(snapshot, chosenArm) {
+    return snapshot === null || snapshot.verdict.recommendedArm === null || chosenArm !== snapshot.verdict.recommendedArm || [
+        1,
+        2,
+        3,
+        4
+    ].some((row)=>row === snapshot.verdict.row);
+}

package/dist/results/guardrails.d.ts

@@ -0,0 +1,17 @@
+export interface GuardrailInput {
+    method: 'sequential' | 'bayesian';
+    n: number;
+    minSampleSize: number;
+    threshold: number;
+    /** Metric collection direction, passed through without translation. */
+    direction: 'increase' | 'decrease';
+    /** Raw relative-effect bounds: sequential greater-test lower and lesser-test upper.
+     * Bayesian bounds use alpha 0.10; pass raw bounds before direction inversion. */
+    lowerBound: number | null;
+    upperBound: number | null;
+    pointEstimate: number;
+    /** Probability of harm, already adjusted for direction. */
+    pWorse?: number;
+}
+/** Classify precomputed one-sided results in the order specified by plan CORE-15a. */
+export declare function guardrailStatus(input: GuardrailInput): 'failing' | 'ok' | 'warning' | 'insufficient';

package/dist/results/guardrails.js

@@ -0,0 +1,10 @@
+/** Classify precomputed one-sided results in the order specified by plan CORE-15a. */ export function guardrailStatus(input) {
+    const inverse = input.direction === 'decrease';
+    const lower = inverse ? input.upperBound === null ? null : -input.upperBound : input.lowerBound;
+    const upper = inverse ? input.lowerBound === null ? null : -input.lowerBound : input.upperBound;
+    const harmful = input.method === 'bayesian' ? (input.pWorse ?? 0) >= 0.95 : upper !== null && upper < 0;
+    if (input.n >= input.minSampleSize && harmful) return 'failing';
+    if (lower !== null && lower > -input.threshold) return 'ok';
+    const warning = input.method === 'bayesian' ? (input.pWorse ?? 0) >= 0.70 : (inverse ? -input.pointEstimate : input.pointEstimate) < 0;
+    return warning ? 'warning' : 'insufficient';
+}

package/dist/results/history.d.ts

@@ -0,0 +1,13 @@
+import type { MetricEvent } from './aggregate.js';
+/**
+ * Spec §5.4: "Default for revenue sources is `percentile 0.99`; the threshold is resolved at Start from the source's own `query({ from: start − 90 d, to: start })` (no extra host contract): events are aggregated **per unit** in **repeated greedy windows**: the unit's first event in the lookback anchors a window of the metric's attribution length, every event inside `[anchor, anchor + window)` sums into that window's value, the first event at or after the window's end anchors the next window, and so on; each window sum is one value in the percentile population (each matches what one exposure-anchored analysis window would see, and repeat donors contribute several comparable samples), the percentile is taken over those per-unit values (GrowthBook caps unit-level values, not events), and the result is frozen into the phase (`metricDefinitions[].resolvedCap`, with `historyUnits`); fewer than 20 history units → no cap and a notice in the admin."
+ * The caller supplies only lookback events. `units` counts distinct units, not windows.
+ * Units without events never contribute: this conservative population is close to
+ * GrowthBook's ignore-zeros behavior and avoids a cap of 0 at low conversion.
+ */
+export declare function perUnitHistory(events: readonly MetricEvent[], { windowHours }: {
+    windowHours: number;
+}): {
+    values: number[];
+    units: number;
+};

package/dist/results/history.js

@@ -0,0 +1,39 @@
+import { timestampMs, windowMs } from './aggregate.js';
+/**
+ * Spec §5.4: "Default for revenue sources is `percentile 0.99`; the threshold is resolved at Start from the source's own `query({ from: start − 90 d, to: start })` (no extra host contract): events are aggregated **per unit** in **repeated greedy windows**: the unit's first event in the lookback anchors a window of the metric's attribution length, every event inside `[anchor, anchor + window)` sums into that window's value, the first event at or after the window's end anchors the next window, and so on; each window sum is one value in the percentile population (each matches what one exposure-anchored analysis window would see, and repeat donors contribute several comparable samples), the percentile is taken over those per-unit values (GrowthBook caps unit-level values, not events), and the result is frozen into the phase (`metricDefinitions[].resolvedCap`, with `historyUnits`); fewer than 20 history units → no cap and a notice in the admin."
+ * The caller supplies only lookback events. `units` counts distinct units, not windows.
+ * Units without events never contribute: this conservative population is close to
+ * GrowthBook's ignore-zeros behavior and avoids a cap of 0 at low conversion.
+ */ export function perUnitHistory(events, { windowHours }) {
+    const duration = windowMs(windowHours);
+    const byUnit = new Map();
+    for (const event of events){
+        const row = {
+            ts: timestampMs(event.ts),
+            value: event.value
+        };
+        const rows = byUnit.get(event.unitId);
+        if (rows) rows.push(row);
+        else byUnit.set(event.unitId, [
+            row
+        ]);
+    }
+    const values = [];
+    for (const rows of byUnit.values()){
+        rows.sort((a, b)=>a.ts - b.ts);
+        let anchor;
+        let sum = 0;
+        for (const row of rows){
+            if (anchor === undefined || row.ts >= anchor + duration) {
+                if (anchor !== undefined) values.push(sum);
+                anchor = row.ts;
+                sum = row.value;
+            } else sum += row.value;
+        }
+        values.push(sum);
+    }
+    return {
+        values,
+        units: byUnit.size
+    };
+}

package/dist/results/identityCredit.d.ts

@@ -0,0 +1,16 @@
+import type { ExposedUnit, MetricEvent, Timestamp } from './aggregate.js';
+/**
+ * Spec §8.3: credit once to the earliest exposed linked visitor; conflicts are diagnostic only.
+ * Callers must pass user ids through String() for both identities and user-keyed source events.
+ */
+export declare function creditUserEvents(units: ReadonlyMap<string, ExposedUnit>, identities: readonly {
+    anonymousId: string;
+    userId: string;
+}[], userEvents: readonly {
+    userId: string;
+    value: number;
+    ts: Timestamp;
+}[]): {
+    events: MetricEvent[];
+    conflicts: number;
+};

package/dist/results/identityCredit.js

@@ -0,0 +1,46 @@
+import { timestampMs } from './aggregate.js';
+/**
+ * Spec §8.3: credit once to the earliest exposed linked visitor; conflicts are diagnostic only.
+ * Callers must pass user ids through String() for both identities and user-keyed source events.
+ */ export function creditUserEvents(units, identities, userEvents) {
+    const users = new Map();
+    const starts = new Map();
+    for (const [unitId, unit] of units)starts.set(unitId, timestampMs(unit.firstTs));
+    for (const { anonymousId, userId } of identities){
+        const unit = units.get(anonymousId);
+        if (!unit) continue;
+        const firstTs = starts.get(anonymousId);
+        const user = users.get(userId);
+        if (!user) users.set(userId, {
+            unitId: anonymousId,
+            firstTs,
+            arms: new Set([
+                unit.arm
+            ])
+        });
+        else {
+            user.arms.add(unit.arm);
+            // Stable tie-break for simultaneous exposures, independent of identity row order.
+            if (firstTs < user.firstTs || firstTs === user.firstTs && anonymousId < user.unitId) {
+                user.unitId = anonymousId;
+                user.firstTs = firstTs;
+            }
+        }
+    }
+    let conflicts = 0;
+    for (const user of users.values())if (user.arms.size > 1) conflicts++;
+    const events = [];
+    for (const event of userEvents){
+        timestampMs(event.ts);
+        const user = users.get(event.userId);
+        if (user) events.push({
+            unitId: user.unitId,
+            value: event.value,
+            ts: event.ts
+        });
+    }
+    return {
+        events,
+        conflicts
+    };
+}

package/dist/results/power.d.ts

@@ -0,0 +1,15 @@
+import type { GaussianPrior, TestStatistic } from '@delmaredigital/experiments-stats';
+import type { Snapshot } from '../types/snapshot.js';
+/** Present the stats engine's pairwise sample estimate at observed exposed-unit
+ * traffic. v1 planning uses 10% relative lift and 80% power (as Review does).
+ * Called for running test verdict rows 4 and 9; rollout and concluded tests omit estimates.
+ */
+export declare function remainingPower(input: {
+    baseline: TestStatistic;
+    variants: readonly TestStatistic[];
+    elapsedDays: number;
+    alpha: number;
+    method: Snapshot['method'];
+    sequentialTuningParameter: number;
+    prior: GaussianPrior;
+}): Snapshot['power'];

package/dist/results/power.js

@@ -0,0 +1,60 @@
+import { abTestMoments, midExperimentPower, sequentialTwoSidedTTest } from '@delmaredigital/experiments-stats';
+/** Present the stats engine's pairwise sample estimate at observed exposed-unit
+ * traffic. v1 planning uses 10% relative lift and 80% power (as Review does).
+ * Called for running test verdict rows 4 and 9; rollout and concluded tests omit estimates.
+ */ export function remainingPower(input) {
+    const lowerBound = input.method === 'sequential';
+    const unknown = {
+        daysRemaining: null,
+        exposuresNeededPerArm: null,
+        lowerBound,
+        feasible: true
+    };
+    if (input.elapsedDays <= 0 || input.variants.length === 0) return unknown;
+    const estimates = input.variants.map((variant)=>{
+        const moments = abTestMoments(input.baseline, variant);
+        const result = sequentialTwoSidedTTest(input.baseline, variant, {
+            alpha: input.alpha,
+            sequentialTuningParameter: input.sequentialTuningParameter
+        });
+        if (moments.errorMessage) return null;
+        try {
+            return {
+                result: midExperimentPower(moments, result, {
+                    alpha: input.alpha
+                }, {
+                    targetMde: 0.1,
+                    targetPower: 0.8,
+                    sequential: lowerBound,
+                    sequentialTuningParameter: input.sequentialTuningParameter,
+                    priorEffect: input.method === 'bayesian' ? input.prior : null
+                }),
+                n: moments.pairwiseSampleSize
+            };
+        } catch  {
+            return null;
+        }
+    });
+    if (estimates.some((estimate)=>estimate === null)) return unknown;
+    if (estimates.some((estimate)=>estimate.result.updateMessage === 'unsuccessful')) return {
+        ...unknown,
+        feasible: false
+    };
+    let daysRemaining = 0;
+    let exposuresNeededPerArm = 0;
+    for (const estimate of estimates){
+        const { result, n } = estimate;
+        const additional = result.scalingFactor === 0 ? 0 : result.additionalUsers;
+        if (additional === null || !Number.isFinite(additional)) return unknown;
+        daysRemaining = Math.max(daysRemaining, Math.ceil(additional / (n / input.elapsedDays)));
+        // Upstream additionalUsers is pairwise, so the UI's per-arm total is half
+        // the projected pair. Day estimates preserve the actual observed arm ratio.
+        exposuresNeededPerArm = Math.max(exposuresNeededPerArm, Math.ceil((n + additional) / 2));
+    }
+    return {
+        daysRemaining,
+        exposuresNeededPerArm,
+        lowerBound,
+        feasible: daysRemaining <= 90
+    };
+}