@delmaredigital/payload-experiments 0.2.0-rc.7 → 0.3.0-rc.4

package/dist/puck/editor/experimentOutlinePlugin.js

@@ -0,0 +1,89 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createUsePuck, walkTree } from '@puckeditor/core';
+import { useEffect, useMemo, useState } from 'react';
+import { EXPERIMENT_SLOT_TYPE } from '../../types/puck.js';
+import { useArms } from './armsCache.js';
+const usePuckSelector = createUsePuck();
+const slots = [
+    'control',
+    'variantA',
+    'variantB',
+    'variantC'
+];
+// Puck 0.24.0 dist/chunk-DQXMVPVM.mjs:8040 (item attribute), 8126–8135
+// (direct zone containers). Zones have no stable attribute; avoid the CSS-module hash.
+const zone = 'div[class*="Layer-zones"]';
+const chain = (count)=>Array(count).fill(zone).join(' ~ ');
+function SlotRules({ item: [id, testId, emptySlots] }) {
+    const known = useArms(testId ?? undefined);
+    const [mounted, setMounted] = useState(false);
+    useEffect(()=>{
+        setMounted(true);
+    }, []);
+    // CSS.escape is a browser API: SSR and the first hydration render emit no rules.
+    if (!mounted) return null;
+    const rules = slots.flatMap((slot, index)=>{
+        // Original always remains available. Unknown bound tests must reveal every zone.
+        if (slot === 'control' || testId !== null && (!known || known.arms.includes(slot))) return [];
+        if (!emptySlots[index]) return [];
+        // Exactly the nth zone sibling: the positive chain matches n onward and the
+        // negated chain excludes n+1 onward. Unlike nth-child, DropLine siblings do not count.
+        const selector = `li[data-puck-layer-tree-id="${CSS.escape(id)}"] > ${chain(index + 1)}:not(${chain(index + 2)})`;
+        return [
+            `${selector} { display: none; }`
+        ];
+    }).join('\n');
+    return /*#__PURE__*/ _jsx("style", {
+        "data-xp-outline": id,
+        children: rules
+    });
+}
+function ExperimentOutline({ children }) {
+    // Public selector API in Puck 0.24, rather than the deprecated usePuck hook.
+    const key = usePuckSelector((state)=>{
+        const { data } = state.appState;
+        const items = new Map();
+        const collect = (content)=>{
+            for (const item of content)if (item.type === EXPERIMENT_SLOT_TYPE) {
+                const testId = item.props.experiment?.id;
+                items.set(item.props.id, [
+                    item.props.id,
+                    testId === undefined ? null : String(testId),
+                    slots.map((slot)=>{
+                        const content = item.props[slot];
+                        return !Array.isArray(content) || content.length === 0;
+                    })
+                ]);
+            }
+        };
+        walkTree(data, state.config, (content)=>{
+            collect(content);
+        });
+        // walkTree visits slots inside legacy zones, but does not call back on the zone itself.
+        for (const content of Object.values(data.zones ?? {}))collect(content);
+        return JSON.stringify([
+            ...items.values()
+        ]);
+    });
+    // Only binding/emptiness changes rebuild the rules, not edits to other page fields.
+    const rules = useMemo(()=>JSON.parse(key).map((item)=>/*#__PURE__*/ _jsx(SlotRules, {
+                item: item
+            }, item[0])), [
+        key
+    ]);
+    return /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            children,
+            rules
+        ]
+    });
+}
+/** Add to Puck's plugins so its outline wrapper composes with the host's overrides. */ export function experimentOutlinePlugin() {
+    return {
+        name: 'experiment-outline',
+        overrides: {
+            outline: ExperimentOutline
+        }
+    };
+}

package/dist/puck/experimentSlotField.d.ts

@@ -1,5 +1,7 @@
 import type { CustomField } from '@puckeditor/core';
 import type { ExperimentRef } from '../types/puck.js';
+import { type PuckRoutes } from './routes.js';
 export declare function createExperimentSlotField(opts?: {
     label?: string;
+    routes?: PuckRoutes;
 }): CustomField<ExperimentRef | null>;

package/dist/puck/experimentSlotField.js

@@ -1,13 +1,21 @@
 import { createElement } from 'react';
 import { ExperimentPicker } from './ExperimentPicker.js';
+import { resolvePuckRoutes } from './routes.js';
+import { PuckHostProvider } from './hostContext.js';
 import { pickerCopy } from './copy.js';
 export function createExperimentSlotField(opts) {
+    const routes = resolvePuckRoutes(opts?.routes);
     return {
         type: 'custom',
         label: opts?.label ?? pickerCopy.label,
-        render: ({ value, onChange })=>createElement(ExperimentPicker, {
-                value,
-                onChange
+        render: ({ value, onChange })=>createElement(PuckHostProvider, {
+                routes,
+                children: createElement('div', {
+                    className: 'xp-puck-field'
+                }, createElement(ExperimentPicker, {
+                    value,
+                    onChange
+                }))
             })
     };
 }

package/dist/puck/hostContext.d.ts

@@ -0,0 +1,10 @@
+import { resolvePuckRoutes } from './routes.js';
+import type { ReactNode } from 'react';
+export declare const usePuckRoutes: () => {
+    admin: string;
+    api: string;
+};
+export declare function PuckHostProvider({ routes, children }: {
+    routes: ReturnType<typeof resolvePuckRoutes>;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/puck/hostContext.js

@@ -0,0 +1,12 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+import { resolvePuckRoutes } from './routes.js';
+const PuckHostContext = /*#__PURE__*/ createContext(resolvePuckRoutes());
+export const usePuckRoutes = ()=>useContext(PuckHostContext);
+export function PuckHostProvider({ routes, children }) {
+    return /*#__PURE__*/ _jsx(PuckHostContext.Provider, {
+        value: routes,
+        children: children
+    });
+}

package/dist/puck/routes.d.ts

@@ -0,0 +1,12 @@
+export interface PuckRoutes {
+    admin?: string;
+    api?: string;
+}
+export declare const DEFAULT_PUCK_ROUTES: {
+    readonly admin: "/admin";
+    readonly api: "/api";
+};
+export declare function resolvePuckRoutes(routes?: PuckRoutes): {
+    admin: string;
+    api: string;
+};

package/dist/puck/routes.js

@@ -0,0 +1,11 @@
+// Payload's documented route defaults; hosts pass config.routes when customized.
+export const DEFAULT_PUCK_ROUTES = {
+    admin: '/admin',
+    api: '/api'
+};
+export function resolvePuckRoutes(routes) {
+    return {
+        admin: (routes?.admin ?? DEFAULT_PUCK_ROUTES.admin).replace(/\/$/, ''),
+        api: (routes?.api ?? DEFAULT_PUCK_ROUTES.api).replace(/\/$/, '')
+    };
+}

package/dist/puck/slotConfig.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentConfig } from '@puckeditor/core';
 import type { ExperimentSlotProps } from '../types/puck.js';
-export declare const experimentSlotLabel: "Experiment";
+export declare const experimentSlotLabel = "Experiment block";
 export declare const experimentSlotFields: NonNullable<ComponentConfig<ExperimentSlotProps>['fields']>;
 export declare const experimentSlotDefaultProps: NonNullable<ComponentConfig<ExperimentSlotProps>['defaultProps']>;

package/dist/puck/slotConfig.js

@@ -1,6 +1,6 @@
 import { createExperimentSlotField } from './experimentSlotField.js';
-import { pickerCopy, slotLabels } from './copy.js';
-export const experimentSlotLabel = pickerCopy.label;
+import { slotLabels } from './copy.js';
+export const experimentSlotLabel = 'Experiment block';
 export const experimentSlotFields = {
     experiment: createExperimentSlotField(),
     // Puck 0.24's defaultSlots prepends each slot, reversing declaration order in the outline.

package/dist/results/aggregate.js

@@ -1,14 +1,15 @@
+import { XpAnalysisError } from '../errors.js';
 /** Accept Date, timestamp text, or epoch milliseconds; reject invalid dates. */ export function timestampMs(ts) {
     if (!(ts instanceof Date) && typeof ts !== 'string' && typeof ts !== 'number') {
-        throw new RangeError('Invalid timestamp');
+        throw new XpAnalysisError('invalid-timestamp');
     }
     const ms = ts instanceof Date ? ts.getTime() : new Date(ts).getTime();
-    if (!Number.isFinite(ms)) throw new RangeError('Invalid timestamp');
+    if (!Number.isFinite(ms)) throw new XpAnalysisError('invalid-timestamp');
     return ms;
 }
 /** Attribution windows must have a finite, positive length in hours. */ export function windowMs(windowHours) {
     if (!Number.isFinite(windowHours) || windowHours <= 0) {
-        throw new RangeError('windowHours must be a finite number greater than 0');
+        throw new XpAnalysisError('window-hours');
     }
     return windowHours * 3_600_000;
 }

package/dist/results/analyse.d.ts

@@ -1,4 +1,5 @@
 import type { GaussianPrior } from '@delmaredigital/experiments-stats';
+import type { MetricUnavailableReason } from '../types/reasons.js';
 import type { Arm, DocId, MetricSource } from '../types/contracts.js';
 import type { Snapshot } from '../types/snapshot.js';
 import type { ExposedUnit, Timestamp } from './aggregate.js';
@@ -55,10 +56,12 @@ export interface MetricUnitData {
     values: ReadonlyMap<string, number>;
     /** Host pre-period outcomes; absent entries in a supplied map mean zero. */
     covariates?: ReadonlyMap<string, number>;
-    unavailable?: string;
+    unavailable?: MetricUnavailableReason;
 }
 export type AnalysePhaseInput = {
     phase: AnalysisPhase;
+    /** The runner logs failures; injecting this keeps analysis free of I/O imports. */
+    onMetricError?: (error: unknown, metricId: DocId) => void;
     status: 'running' | 'stopped' | 'decided';
     now: Timestamp;
     /** CORE-14a firstExposures output; same-unit multi-arm units already excluded. */

package/dist/results/analyse.js

@@ -1,3 +1,4 @@
+import { XpAnalysisError } from '../errors.js';
 import { DEFAULT_GAUSSIAN_PRIOR, bonferroniAlpha, capValues, createThetaAdjustedStatistics, effectBayesianABTest, sequentialOneSidedTreatmentGreaterTTest, sequentialOneSidedTreatmentLesserTTest, sequentialTwoSidedTTest, statisticMean, statisticVariance } from '@delmaredigital/experiments-stats';
 import { DEFAULT_SEQUENTIAL_TUNING_PARAMETER } from '../constants.js';
 import { timestampMs } from './aggregate.js';
@@ -18,8 +19,8 @@ const severity = {
  */ export function analysePhase(input) {
     const { phase, units } = input;
     const { analysis } = phase;
-    // Start freezes this optional collection field as-is. Match the stats engine's
-    // default and record the effective value in every snapshot, including n = 0.
+    // Compatibility for phases created before Start froze the effective tuning
+    // value. Record that effective value in every snapshot, including n = 0.
     const sequentialTuningParameter = analysis.sequentialTuningParameter ?? DEFAULT_SEQUENTIAL_TUNING_PARAMETER;
     const alpha = analysis.alpha ?? 0.05;
     const prior = analysis.prior ?? DEFAULT_GAUSSIAN_PRIOR;
@@ -30,7 +31,7 @@ const severity = {
     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');
+    if (!baselineArm || rollout && (!winner || phase.arms.length !== 2)) throw new XpAnalysisError('no-baseline');
     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;
@@ -42,22 +43,22 @@ const severity = {
         }));
     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');
+        throw new XpAnalysisError('primary-metric-count');
     }
     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');
+        throw new XpAnalysisError('duplicate-metric');
     }
     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');
+    if (to < from) throw new XpAnalysisError('window-before-start');
     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');
+        if (!ids) throw new XpAnalysisError('unknown-arm');
         ids.push(id);
     }
     const perArm = Object.fromEntries([
@@ -120,17 +121,19 @@ const severity = {
         let worstArmLabel = compared[0]?.label ?? '';
         let worstArm = compared[0]?.key ?? '';
         try {
-            if (!data || data.unavailable !== undefined) throw new Error(data?.unavailable ?? 'Metric data was not supplied');
+            if (!data || data.unavailable !== undefined) {
+                throw new XpAnalysisError('metric-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');
+                if (!values.every(Number.isFinite)) throw new XpAnalysisError('non-finite-values');
                 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');
+                if (rawPre && !rawPre.every(Number.isFinite)) throw new XpAnalysisError('non-finite-covariates');
                 const pre = rawPre && capValues(rawPre, cap).values;
                 const built = outcomeStatistic(kind, capped.values, pre);
                 stats.set(arm.key, built.statistic);
@@ -257,7 +260,20 @@ const severity = {
                 }
             }
         } catch (error) {
-            metric.unavailable = error instanceof Error ? error.message : 'Metric could not be analysed';
+            input.onMetricError?.(error, metricId);
+            let reason = 'analysis-failed';
+            if (error instanceof XpAnalysisError) {
+                switch(error.code){
+                    case 'metric-not-supplied':
+                        reason = data?.unavailable ?? 'not-supplied';
+                        break;
+                    case 'non-finite-values':
+                    case 'non-finite-covariates':
+                        reason = error.code;
+                        break;
+                }
+            }
+            metric.unavailable = reason;
             metric.perArm = [];
             metric.comparisons = [];
             metric.cupedApplied = false;

package/dist/results/cuped.js

@@ -1,13 +1,14 @@
+import { XpAnalysisError } from '../errors.js';
 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');
+        throw new XpAnalysisError('cuped-non-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');
+        throw new XpAnalysisError('cuped-binomial');
     }
     const moments = summarizeUnits(values);
     if (covariates === undefined) return {

package/dist/results/identityCredit.d.ts

@@ -1,16 +1,24 @@
 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 {
+export interface IdentityLink {
     anonymousId: string;
     userId: string;
-}[], userEvents: readonly {
+    verifiedAt: Timestamp | null;
+    /** Earliest verification across all the user's browsers, exposed or not. */
+    ownedAt: Timestamp | null;
+}
+/** Unverified links credit only events before anyone proves account ownership.
+ * Never-verified accounts keep crediting without a time limit.
+ */
+export declare function eligibleIdentityLinks<T extends IdentityLink>(links: readonly T[], ts: Timestamp): T[];
+/** Credit each event to the earliest exposed eligible visitor, with a stable ID
+ * tie-break. A user counts once if eligible links span arms for a credited event.
+ * Callers must normalize user IDs with String().
+ */
+export declare function creditUserEvents(units: ReadonlyMap<string, ExposedUnit>, identities: readonly IdentityLink[], userEvents: readonly {
     userId: string;
     value: number;
     ts: Timestamp;
-}[]): {
+}[], onConflict?: (userId: string) => void): {
     events: MetricEvent[];
     conflicts: number;
 };

package/dist/results/identityCredit.js

@@ -1,46 +1,45 @@
 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) {
+/** Unverified links credit only events before anyone proves account ownership.
+ * Never-verified accounts keep crediting without a time limit.
+ */ export function eligibleIdentityLinks(links, ts) {
+    const t = timestampMs(ts);
+    return links.filter((link)=>link.verifiedAt !== null || link.ownedAt === null || t < timestampMs(link.ownedAt));
+}
+/** Credit each event to the earliest exposed eligible visitor, with a stable ID
+ * tie-break. A user counts once if eligible links span arms for a credited event.
+ * Callers must normalize user IDs with String().
+ */ export function creditUserEvents(units, identities, userEvents, onConflict) {
+    const starts = new Map([
+        ...units
+    ].map(([id, unit])=>[
+            id,
+            timestampMs(unit.firstTs)
+        ]));
     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;
-            }
-        }
+    for (const link of identities){
+        if (!units.has(link.anonymousId)) continue;
+        const links = users.get(link.userId) ?? [];
+        links.push(link);
+        users.set(link.userId, links);
     }
-    let conflicts = 0;
-    for (const user of users.values())if (user.arms.size > 1) conflicts++;
+    for (const links of users.values())links.sort((a, b)=>starts.get(a.anonymousId) - starts.get(b.anonymousId) || (a.anonymousId < b.anonymousId ? -1 : a.anonymousId > b.anonymousId ? 1 : 0));
+    const conflicts = new Set();
     const events = [];
     for (const event of userEvents){
-        timestampMs(event.ts);
-        const user = users.get(event.userId);
-        if (user) events.push({
-            unitId: user.unitId,
+        const eligible = eligibleIdentityLinks(users.get(event.userId) ?? [], event.ts);
+        if (!eligible.length) continue;
+        events.push({
+            unitId: eligible[0].anonymousId,
             value: event.value,
             ts: event.ts
         });
+        if (new Set(eligible.map((link)=>units.get(link.anonymousId).arm)).size > 1) {
+            conflicts.add(event.userId);
+            onConflict?.(event.userId);
+        }
     }
     return {
         events,
-        conflicts
+        conflicts: conflicts.size
     };
 }

package/dist/results/rolloutUnits.js

@@ -1,7 +1,8 @@
+import { XpAnalysisError } from '../errors.js';
 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 |');
+    if (!seed.endsWith('|')) throw new XpAnalysisError('seed-format');
     const first = new Map();
     for (const row of exposuresAllPhases){
         const ts = timestampMs(row.ts);

package/dist/results/snapshot.js

@@ -1,3 +1,4 @@
+import { XpAnalysisError } from '../errors.js';
 /** JSON cannot represent unbounded confidence limits. */ export function jsonInterval(ci) {
     return ci.map((bound)=>bound !== null && Number.isFinite(bound) ? bound : null);
 }
@@ -138,14 +139,19 @@ const shape = object({
         }),
         by: nullable(id)
     }))
+}, {
+    health: list(object({
+        code: oneOf('version-page-unavailable', 'version-page-unchecked'),
+        path: string
+    }))
 });
 /** 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)');
+    if (!shape(value)) throw new XpAnalysisError('snapshot-shape');
     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');
+        throw new XpAnalysisError('snapshot-invariants');
     }
 }
 /** Assemble the already-computed snapshot at the pure/I/O boundary. */ export function assembleSnapshot(snapshot) {

package/dist/results/srm.js

@@ -1,3 +1,4 @@
+import { XpAnalysisError } from '../errors.js';
 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).
@@ -5,7 +6,7 @@ import { checkSrm } from '@delmaredigital/experiments-stats';
  */ 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');
+    if (weight <= 0) throw new XpAnalysisError('srm-weights');
     const expected = Object.fromEntries(arms.map((arm)=>[
             arm.key,
             arm.weight / weight

package/dist/sanitizeReadinessDetail.d.ts

@@ -0,0 +1,7 @@
+import type { ReadinessCode } from './types/endpoints.js';
+/** Summary details contain identifiers only. Project known shapes rather than
+ * recursively copying host objects: titles, messages and placement detail are text.
+ * Other checks use authored client fallbacks and need no detail (including slot
+ * counts and layer capacity, which are not identifiers).
+ */
+export declare function sanitizeReadinessDetail(code: ReadinessCode, detail: unknown): unknown;

package/dist/sanitizeReadinessDetail.js

@@ -0,0 +1,63 @@
+const object = (value)=>value !== null && typeof value === 'object' && !Array.isArray(value);
+// The runtime's slug/key alphabet, bounded even for host-provided parameter keys.
+const key = (value)=>typeof value === 'string' && value.length <= 128 && /^[A-Za-z0-9_-]+$/.test(value);
+const arm = (value)=>typeof value === 'string' && [
+        'control',
+        'variantA',
+        'variantB',
+        'variantC',
+        'holdout'
+    ].includes(value);
+const path = (value)=>typeof value === 'string' && value.length <= 128 && value.startsWith('/') && !value.includes('//') && !/[^A-Za-z0-9_/-]/.test(value);
+const failure = (value)=>value === 'placements-failed' || value === 'forbidden' || value === 'not-found';
+/** Summary details contain identifiers only. Project known shapes rather than
+ * recursively copying host objects: titles, messages and placement detail are text.
+ * Other checks use authored client fallbacks and need no detail (including slot
+ * counts and layer capacity, which are not identifiers).
+ */ export function sanitizeReadinessDetail(code, detail) {
+    switch(code){
+        case 'block-path-rule':
+            return object(detail) && Array.isArray(detail.rules) && detail.rules.length && detail.rules.every((index)=>Number.isSafeInteger(index) && index >= 0) ? {
+                rules: detail.rules
+            } : undefined;
+        case 'no-placements':
+            return failure(detail) ? detail : undefined;
+        case 'page-in-use':
+            {
+                if (!object(detail) || !Array.isArray(detail.paths)) return undefined;
+                const paths = detail.paths.filter(path);
+                return paths.length ? {
+                    paths
+                } : undefined;
+            }
+        case 'page-target-unpublished':
+            // Paths only: no query, fragment, whitespace, URL authority or encoded text.
+            return path(detail) ? detail : undefined;
+        case 'flag-params-invalid':
+            {
+                if (!Array.isArray(detail) || !detail.length || !detail.every((item)=>object(item) && arm(item.arm) && key(item.field))) return undefined;
+                return detail.map((item)=>({
+                        arm: item.arm,
+                        field: item.field
+                    }));
+            }
+        case 'flag-placement-missing':
+            {
+                if (failure(detail)) return detail;
+                if (!object(detail) || !Array.isArray(detail.missing) || !detail.missing.every(arm) || !Array.isArray(detail.placements) || !detail.placements.every((item)=>object(item) && arm(item.arm))) return undefined;
+                return {
+                    missing: detail.missing,
+                    placements: detail.placements.map((item)=>({
+                            arm: item.arm
+                        }))
+                };
+            }
+        case 'undeclared-targeting-key':
+        case 'invalid-targeting-rule':
+            return object(detail) && Array.isArray(detail.attributes) && detail.attributes.length && detail.attributes.every(key) ? {
+                attributes: detail.attributes
+            } : undefined;
+        default:
+            return undefined;
+    }
+}

package/dist/server/linkIdentity.d.ts

@@ -1,4 +1,12 @@
 import type { ExperimentsServerRuntime } from '../types/runtime.js';
+import { type IdentityWriteOutcome } from '../db/identities.js';
+export type LinkIdentityOutcome = IdentityWriteOutcome | 'failed';
+/**
+ * verified: true means this request proves, in this browser, that the person owns
+ * the account: a magic-link or one-time-code callback, password sign-in, or OAuth
+ * callback. It does not mean "a session exists" or "the email is verified".
+ * Never throws into registration or sign-in.
+ */
 export declare function linkIdentity<TUser extends {
     id: string | number;
 } = {
@@ -6,4 +14,5 @@ export declare function linkIdentity<TUser extends {
 }>(serverRuntime: ExperimentsServerRuntime<TUser>, opts: {
     headers: Headers;
     userId: string;
-}): Promise<void>;
+    verified: boolean;
+}): Promise<LinkIdentityOutcome>;