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

package/dist/arms/model.js

@@ -0,0 +1,173 @@
+import { addHoldout, checkArms } from '../collections/experiments/armInvariants.js';
+import { ARM_LABELS as GROUP_LABELS } from '../labels/arms.js';
+const VARIANTS = [
+    'variantA',
+    'variantB',
+    'variantC'
+];
+export function defaultArms(kind) {
+    return withSlotsFor([
+        {
+            key: 'control',
+            kind: 'control',
+            label: GROUP_LABELS.control,
+            weight: 50
+        },
+        {
+            key: 'variantA',
+            kind: 'variant',
+            label: GROUP_LABELS.variantA,
+            weight: 50
+        }
+    ], kind);
+}
+/** Keep content slots in step with the experiment kind, including an unset kind. */ export function withSlotsFor(arms, kind) {
+    const next = arms.map((arm)=>{
+        if (kind === 'block' && arm.kind !== 'holdout') return arm.slot === arm.key ? arm : {
+            ...arm,
+            slot: arm.key
+        };
+        // Postgres returns null for unset columns; null counts as "no slot" so a loaded doc is not rewritten.
+        if (arm.slot == null) return arm;
+        const { slot: _slot, ...rest } = arm;
+        return rest;
+    });
+    return next.every((arm, index)=>arm === arms[index]) ? arms : next;
+}
+const finiteWeight = (weight)=>Number.isFinite(weight) ? weight : 0;
+export function totalWeight(arms) {
+    return arms.reduce((sum, arm)=>sum + finiteWeight(arm.weight), 0);
+}
+export function addVariant(arms, kind) {
+    if (!arms.some((arm)=>arm.kind === 'control')) return arms;
+    const key = VARIANTS.find((candidate)=>!arms.some((arm)=>arm.key === candidate));
+    if (!key || arms.filter((arm)=>arm.kind === 'variant').length >= 3) return arms;
+    const block = kind === 'block' || kind === undefined && arms.some((arm)=>arm.slot !== undefined);
+    const variant = {
+        key,
+        kind: 'variant',
+        label: GROUP_LABELS[key],
+        weight: 0,
+        ...block ? {
+            slot: key
+        } : {}
+    };
+    const index = arms.findIndex((arm)=>arm.kind === 'holdout');
+    const result = [
+        ...arms
+    ];
+    result.splice(index < 0 ? arms.length : index, 0, variant);
+    return result;
+}
+export function removeArm(arms, key) {
+    if (arms.some((arm)=>arm.key === key && arm.kind === 'control')) return arms;
+    if (key === 'holdout') return removeHoldout(arms);
+    return arms.filter((arm)=>arm.key !== key);
+}
+export function addHoldoutArm(arms) {
+    if (!arms.some((arm)=>arm.kind === 'control') || arms.some((arm)=>arm.kind === 'holdout' || arm.key === 'holdout')) return arms;
+    return addHoldout(arms.map((arm)=>Number.isFinite(arm.weight) ? arm : {
+            ...arm,
+            weight: 0
+        }));
+}
+// Largest remainder, with equal fractional remainders awarded to Original first.
+function distribute(arms, total, proportional) {
+    if (!arms.length) return arms;
+    const weightTotal = totalWeight(arms);
+    const useWeights = proportional && weightTotal > 0;
+    const denominator = useWeights ? weightTotal : arms.length;
+    const numerators = arms.map((arm)=>(useWeights ? finiteWeight(arm.weight) : 1) * total);
+    const weights = numerators.map((numerator)=>Math.floor(numerator / denominator));
+    const order = arms.map((_, i)=>i).sort((a, b)=>numerators[b] % denominator - numerators[a] % denominator || Number(arms[b].kind === 'control') - Number(arms[a].kind === 'control') || a - b);
+    const remainder = total - weights.reduce((sum, weight)=>sum + weight, 0);
+    for(let i = 0; i < remainder; i++)weights[order[i % order.length]]++;
+    return arms.map((arm, i)=>({
+            ...arm,
+            weight: weights[i]
+        }));
+}
+export function removeHoldout(arms) {
+    if (!arms.some((arm)=>arm.kind === 'holdout')) return arms;
+    return distribute(arms.filter((arm)=>arm.kind !== 'holdout'), totalWeight(arms), true);
+}
+export function splitEvenly(arms) {
+    const holdout = arms.find((arm)=>arm.kind === 'holdout');
+    const weight = finiteWeight(holdout?.weight ?? 0);
+    return [
+        ...distribute(arms.filter((arm)=>arm.kind !== 'holdout'), 100 - weight, false),
+        ...holdout ? [
+            {
+                ...holdout,
+                weight
+            }
+        ] : []
+    ];
+}
+export function setWeight(arms, key, weight) {
+    return arms.map((arm)=>arm.key === key ? {
+            ...arm,
+            weight
+        } : arm);
+}
+export function issuesByRow(arms, kind) {
+    const rows = arms.map(()=>[]);
+    const form = [];
+    for (const issue of checkArms(arms, kind)){
+        const index = issue.armIndex ?? arms.findIndex((arm)=>arm.key === issue.armKey);
+        if (index >= 0 && index < arms.length) rows[index].push(issue);
+        else form.push(issue);
+    }
+    return {
+        rows,
+        form
+    };
+}
+export const ARM_FIELDS = [
+    'key',
+    'label',
+    'weight',
+    'kind',
+    'slot',
+    'params',
+    'pageTarget'
+];
+/** Payload arrays store each row's values at separate field paths. */ export function readArms(fields, path = 'arms') {
+    const indices = new Set();
+    for (const name of Object.keys(fields)){
+        if (!name.startsWith(`${path}.`)) continue;
+        const [index, field] = name.slice(path.length + 1).split('.');
+        if (/^\d+$/.test(index) && field === 'key') indices.add(Number(index));
+    }
+    return [
+        ...indices
+    ].sort((a, b)=>a - b).map((index)=>Object.fromEntries(ARM_FIELDS.flatMap((field)=>{
+            const value = fields[`${path}.${index}.${field}`]?.value;
+            return value === undefined ? [] : [
+                [
+                    field,
+                    value
+                ]
+            ];
+        })));
+}
+/** Keep the edited share exact and distribute the remaining whole percentages proportionally. */ export function balanceWeight(arms, key, weight) {
+    if (!arms.some((arm)=>arm.key === key) || !Number.isInteger(weight) || weight < 0 || weight > 100) return arms;
+    const others = arms.filter((arm)=>arm.key !== key);
+    if (!others.length) return arms;
+    const total = others.reduce((sum, arm)=>sum + Math.max(0, Number.isFinite(arm.weight) ? arm.weight : 0), 0);
+    const denominator = total || others.length;
+    const raw = others.map((arm)=>(total ? Math.max(0, Number.isFinite(arm.weight) ? arm.weight : 0) : 1) * (100 - weight) / denominator);
+    const whole = raw.map(Math.floor);
+    const order = raw.map((_, i)=>i).sort((a, b)=>raw[b] - whole[b] - (raw[a] - whole[a]) || a - b);
+    const remainder = 100 - weight - whole.reduce((sum, value)=>sum + value, 0);
+    for(let i = 0; i < remainder; i++)whole[order[i]]++;
+    const shares = new Map(others.map((arm, i)=>[
+            arm.key,
+            whole[i]
+        ]));
+    return setWeight(arms, key, weight).map((arm)=>shares.has(arm.key) ? {
+            ...arm,
+            weight: shares.get(arm.key)
+        } : arm);
+}

package/dist/collections/experiments/config.js

@@ -2,12 +2,14 @@ import * as paths from '../../admin/paths.js';
 import { managedAccess } from '../access.js';
 import { serializeAttributeKeys, serializeFlagPoints } from '../serialize.js';
 import { TARGETING_OPS, isOpValid } from '../../targeting/ops.js';
+import { readListValue } from '../../targeting/values.js';
 import { createDefaults } from './createDefaults.js';
 import { flagControlParams } from './flagControlParams.js';
 import { lockHook } from './lockHook.js';
 import { deleteGuard, deleteGuardAfter } from './deleteGuard.js';
 import { checkArms } from './armInvariants.js';
 import { XpNotImplemented, XpRefusal } from '../../errors.js';
+const targetingValue = (rule)=>rule.op === 'in' || rule.op === 'nin' ? readListValue(rule.value) : rule.value;
 const positiveInteger = (value)=>value != null && Number.isInteger(value) && value > 0 || 'Enter a positive whole number.';
 export function experimentsCollection(options) {
     const flagPoints = serializeFlagPoints(options);
@@ -224,6 +226,21 @@ export function experimentsCollection(options) {
                             {
                                 name: 'targeting',
                                 type: 'array',
+                                validate: (value, { data, previousValue })=>{
+                                    // Payload 3.90.2 beforeChange/promise.js passes merged document data
+                                    // and this document's stored array as previousValue, including in bulk updates.
+                                    const status = data?.status ?? 'draft';
+                                    if (data?.kind === 'block' && (status === 'draft' || status === 'stopped')) {
+                                        for (const rule of value ?? []){
+                                            if (rule.attribute !== 'path') continue;
+                                            const previous = rule.id == null ? undefined : previousValue?.find((stored)=>stored.id != null && String(stored.id) === String(rule.id));
+                                            if (!previous || previous.attribute !== rule.attribute || previous.op !== rule.op || JSON.stringify(targetingValue(previous)) !== JSON.stringify(targetingValue(rule))) {
+                                                return 'Page block tests run on their page; remove the page-path rule.';
+                                            }
+                                        }
+                                    }
+                                    return true;
+                                },
                                 fields: [
                                     {
                                         name: 'attribute',
@@ -477,6 +494,14 @@ export function experimentsCollection(options) {
                     {
                         name: 'holdoutReleasedAt',
                         type: 'date'
+                    },
+                    {
+                        name: 'pagesReleasedAt',
+                        type: 'date'
+                    },
+                    {
+                        name: 'pagesReleasedBy',
+                        type: 'text'
                     }
                 ]
             }

package/dist/collections/experiments/lockHook.js

@@ -12,6 +12,7 @@ const relationships = new Set([
     'metrics.secondary',
     'metrics.guardrails',
     'decision.decidedBy',
+    'decision.pagesReleasedBy',
     'decision.snapshotId'
 ]);
 const dates = new Set([
@@ -20,7 +21,8 @@ const dates = new Set([
     'decidedAt',
     'archivedAt',
     'decision.discardedAt',
-    'decision.holdoutReleasedAt'
+    'decision.holdoutReleasedAt',
+    'decision.pagesReleasedAt'
 ]);
 /** Schema-aware: JSON retains its own ids and date-like strings. */ function normalize(value, path, json = false) {
     json ||= [

package/dist/collections/identities.js

@@ -19,12 +19,17 @@ export function identitiesCollection(options) {
             {
                 name: 'userId',
                 type: 'text',
-                required: true
+                required: true,
+                index: true
             },
             {
                 name: 'linkedAt',
                 type: 'date',
                 required: true
+            },
+            {
+                name: 'verifiedAt',
+                type: 'date'
             }
         ]
     };

package/dist/collections/metrics.js

@@ -2,6 +2,7 @@ import { XP_METRIC_SOURCE_SELECT } from '../admin/paths.js';
 import { managedAccess } from './access.js';
 import { serializeMetricSources } from './serialize.js';
 import { validateCappingType, validateCappingValue } from './metricValidation.js';
+import { metricChangeGuard, metricDeleteGuard } from './metricsGuards.js';
 export function metricsCollection(options) {
     const sources = serializeMetricSources(options);
     return {
@@ -20,6 +21,12 @@ export function metricsCollection(options) {
         },
         access: managedAccess(options),
         hooks: {
+            beforeDelete: [
+                metricDeleteGuard
+            ],
+            beforeChange: [
+                metricChangeGuard
+            ],
             beforeValidate: [
                 ({ data, originalDoc })=>{
                     if (!data) return data;

package/dist/collections/metricsGuards.d.ts

@@ -0,0 +1,9 @@
+import type { CollectionBeforeChangeHook, CollectionBeforeDeleteHook } from 'payload';
+/** Payload's REST formatter preserves public plugin errors and their 4xx status. */
+export declare class XpGoalInUseError extends Error {
+    name: string;
+    readonly status = 400;
+    readonly isPublic = true;
+}
+export declare const metricDeleteGuard: CollectionBeforeDeleteHook;
+export declare const metricChangeGuard: CollectionBeforeChangeHook;

package/dist/collections/metricsGuards.js

@@ -0,0 +1,33 @@
+import { pooledExecutor, txExecutor } from '../db/executor.js';
+import { findMetricUsage, lockMetricRow } from '../db/metricUsage.js';
+/** Payload's REST formatter preserves public plugin errors and their 4xx status. */ export class XpGoalInUseError extends Error {
+    name = 'XpGoalInUseError';
+    status = 400;
+    isPublic = true;
+}
+async function executor(req, id, mode) {
+    const transactionID = await req.transactionID;
+    if (transactionID != null) {
+        const exec = txExecutor(req);
+        await lockMetricRow(exec, id, mode);
+        return exec;
+    }
+    // With no transaction a pooled row lock would expire before the usage read;
+    // retain the existing best-effort usage check without taking a lock.
+    return pooledExecutor(req.payload);
+}
+export const metricDeleteGuard = async ({ req, id })=>{
+    const usage = await findMetricUsage(await executor(req, id, 'delete'), id);
+    if (usage) throw new XpGoalInUseError(`This goal is used by the test "${usage.name}". Remove it from the test first.`);
+};
+export const metricChangeGuard = async ({ req, data, originalDoc, operation })=>{
+    if (operation !== 'update') return data;
+    const changed = [
+        'slug',
+        'source'
+    ].some((field)=>field in data && data[field] !== originalDoc[field]);
+    if (changed && await findMetricUsage(await executor(req, originalDoc.id, 'change'), originalDoc.id)) {
+        throw new XpGoalInUseError("This goal is used by a test, so its short name and what it measures can't change. Create a new goal instead.");
+    }
+    return data;
+};

package/dist/contentDone.d.ts

@@ -0,0 +1,4 @@
+import type { ContentReport } from './types/endpoints.js';
+/** Every recorded content entry is updated or handled by the manager. A present but empty report is done:
+ * page tests and flag tests without a host callback record no entries. An absent report is not done. */
+export declare function contentDone(report: ContentReport | null | undefined): boolean;

package/dist/contentDone.js

@@ -0,0 +1,5 @@
+/** Every recorded content entry is updated or handled by the manager. A present but empty report is done:
+ * page tests and flag tests without a host callback record no entries. An absent report is not done. */ export function contentDone(report) {
+    const docs = Array.isArray(report) ? report : report?.docs;
+    return Array.isArray(docs) && docs.every((doc)=>doc?.ok === true || Boolean(doc?.dismissedAt));
+}

package/dist/db/appends.d.ts

@@ -19,9 +19,13 @@ type AppendArgs<T> = {
     phase: number;
     entry: T;
 };
+/** Raw main-row read on the host transaction, without afterRead expansion.
+ * Adapter reads avoid Local API error handling killing the host transaction
+ * before the audit savepoint can recover.
+ */
+export declare function storedContent(req: PayloadRequest, collection: string, id: DocId): Promise<Record<string, unknown> | undefined>;
 /** Read the main collection row BEFORE the host write. Draft version retention
- * and unpublishing cannot remove this baseline. Adapter reads avoid Local API
- * error handling killing the host transaction before savepoint recovery.
+ * and unpublishing cannot remove this baseline.
  */
 export declare function previousPublishedContent(req: PayloadRequest, collection: string, id: DocId): Promise<Record<string, unknown> | undefined>;
 /** Serialize flagDefaults read/modify/write before the manifest builder bumps. */

package/dist/db/appends.js

@@ -1,10 +1,10 @@
 import { COLUMNS, TABLES } from './names.js';
 import { XpRefusal } from '../errors.js';
 import { qualifiedTable, quoteIdentifier as quote } from './sql.js';
-/** Read the main collection row BEFORE the host write. Draft version retention
- * and unpublishing cannot remove this baseline. Adapter reads avoid Local API
- * error handling killing the host transaction before savepoint recovery.
- */ export async function previousPublishedContent(req, collection, id) {
+/** Raw main-row read on the host transaction, without afterRead expansion.
+ * Adapter reads avoid Local API error handling killing the host transaction
+ * before the audit savepoint can recover.
+ */ export async function storedContent(req, collection, id) {
     const doc = await req.payload.db.findOne({
         collection,
         req,
@@ -16,6 +16,12 @@ import { qualifiedTable, quoteIdentifier as quote } from './sql.js';
         // Adapter reads have no access layer; document the audit's access posture.
         overrideAccess: false
     });
+    return doc ?? undefined;
+}
+/** Read the main collection row BEFORE the host write. Draft version retention
+ * and unpublishing cannot remove this baseline.
+ */ export async function previousPublishedContent(req, collection, id) {
+    const doc = await storedContent(req, collection, id);
     if (!doc) return undefined;
     // A draft created with content is already in the main table. Only the
     // existence of a published version matters here; never use its content as

package/dist/db/identities.d.ts

@@ -1,11 +1,12 @@
 import type { Payload } from 'payload';
 import { type Executor } from './executor.js';
-export declare function insertIdentity(exec: Executor, { anonymousId, userId }: {
+export type IdentityWriteOutcome = 'linked' | 'verified' | 'skipped';
+type IdentityInput = {
     anonymousId: string;
     userId: string;
-}): Promise<void>;
-/** §5.6 / §7.8: privileged insert, isolated from the caller's sign-in transaction. */
-export declare function insertIdentityOnOwnConnection(payload: Payload, identity: {
-    anonymousId: string;
-    userId: string;
-}): Promise<void>;
+    verified: boolean;
+};
+export declare function insertIdentity(exec: Executor, { anonymousId, userId, verified }: IdentityInput): Promise<IdentityWriteOutcome>;
+/** §5.6 / §7.8: privileged insert/upgrade, isolated from the caller's sign-in transaction. */
+export declare function insertIdentityOnOwnConnection(payload: Payload, identity: IdentityInput): Promise<IdentityWriteOutcome>;
+export {};

package/dist/db/identities.js

@@ -1,26 +1,29 @@
 import { ownConnection } from './executor.js';
 import { COLUMNS, TABLES } from './names.js';
 const quote = (name)=>`"${name.replaceAll('"', '""')}"`;
-export async function insertIdentity(exec, { anonymousId, userId }) {
+export async function insertIdentity(exec, { anonymousId, userId, verified }) {
     const schema = exec.schemaName;
     const table = `${schema ? `${quote(schema)}.` : ''}${quote(TABLES.identities)}`;
     const c = COLUMNS.identities;
-    await exec.query(`INSERT INTO ${table} (${[
+    const { rows } = await exec.query(`INSERT INTO ${table} AS identity (${[
         c.anonymousId,
         c.userId,
         c.linkedAt,
+        c.verifiedAt,
         c.createdAt,
         c.updatedAt
-    ].map(quote).join(', ')}) VALUES ($1, $2, now(), now(), now()) ON CONFLICT (${quote(c.anonymousId)}) DO NOTHING`, [
+    ].map(quote).join(', ')}) VALUES ($1, $2, now(), CASE WHEN $3 THEN now() END, now(), now()) ON CONFLICT (${quote(c.anonymousId)}) DO UPDATE SET ${quote(c.verifiedAt)} = now(), ${quote(c.updatedAt)} = now() WHERE identity.${quote(c.userId)} = EXCLUDED.${quote(c.userId)} AND identity.${quote(c.verifiedAt)} IS NULL AND $3 RETURNING (xmax = 0) AS inserted`, [
         anonymousId,
-        userId
+        userId,
+        verified
     ]);
+    return rows.length === 0 ? 'skipped' : rows[0].inserted ? 'linked' : 'verified';
 }
-/** §5.6 / §7.8: privileged insert, isolated from the caller's sign-in transaction. */ export async function insertIdentityOnOwnConnection(payload, identity) {
+/** §5.6 / §7.8: privileged insert/upgrade, isolated from the caller's sign-in transaction. */ export async function insertIdentityOnOwnConnection(payload, identity) {
     const db = payload.db;
     const exec = await ownConnection(db.pool);
     try {
-        await insertIdentity(Object.assign(exec, {
+        return await insertIdentity(Object.assign(exec, {
             schemaName: db.schemaName
         }), identity);
     } finally{

package/dist/db/locks.d.ts

@@ -4,6 +4,7 @@ export declare const LOCK_NAMESPACES: {
     readonly layer: "xp:layer";
     readonly flagPoint: "xp:flagpoint";
     readonly experiment: "xp:experiment";
+    readonly pagePath: "xp:pagepath";
 };
 /** Transaction executor only. Call in layer → flag point → experiment order;
  * the manifest builder takes the state lock last, after transition writes.
@@ -13,3 +14,8 @@ export declare function lockTransitionScope(exec: Executor, scope: {
     layerId?: DocId | null;
     flagPointId?: string | null;
 }): Promise<void>;
+/** After layer → flag point → experiment, before metric/state locks. Paths must
+ * already be normalised with the runtime's rules. Sorted keys avoid deadlocks
+ * when different tests share several paths in different arm orders.
+ */
+export declare function lockPagePaths(exec: Executor, paths: readonly string[]): Promise<void>;

package/dist/db/locks.js

@@ -1,11 +1,13 @@
 export const LOCK_NAMESPACES = {
     layer: 'xp:layer',
     flagPoint: 'xp:flagpoint',
-    experiment: 'xp:experiment'
+    experiment: 'xp:experiment',
+    pagePath: 'xp:pagepath'
 };
 const LOCK_STATEMENTS = {
     layer: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.layer}'), hashtext($1))`,
     flagPoint: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.flagPoint}'), hashtext($1))`,
+    pagePath: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.pagePath}'), hashtext($1))`,
     experiment: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.experiment}'), hashtext($1))`
 };
 /** Transaction executor only. Call in layer → flag point → experiment order;
@@ -21,3 +23,13 @@ const LOCK_STATEMENTS = {
         String(scope.experimentId)
     ]);
 }
+/** After layer → flag point → experiment, before metric/state locks. Paths must
+ * already be normalised with the runtime's rules. Sorted keys avoid deadlocks
+ * when different tests share several paths in different arm orders.
+ */ export async function lockPagePaths(exec, paths) {
+    for (const path of [
+        ...new Set(paths)
+    ].sort())await exec.query(LOCK_STATEMENTS.pagePath, [
+        path
+    ]);
+}

package/dist/db/metricUsage.d.ts

@@ -0,0 +1,19 @@
+import type { Executor } from './executor.js';
+import type { DocId } from '../types/contracts.js';
+/** Request transaction only: serialize the guard with FK checks and freezes. */
+export declare function lockMetricRow(exec: Executor, id: DocId, mode: 'delete' | 'change'): Promise<void>;
+/** Transition transaction only, after advisory locks. SQL orders by the native
+ * id type so overlapping freezes always acquire row locks in the same order.
+ * Return the locked identities so callers can reject a change that committed
+ * after preflight. Missing rows mean a goal was deleted; never freeze that copy.
+ * txExecutor throws if the request no longer has a transaction session.
+ */
+export declare function lockMetricsForFreeze(exec: Executor, ids: DocId[]): Promise<Array<{
+    id: DocId;
+    slug: string;
+    source: string;
+}> | null>;
+/** Live selections cover drafts; frozen definitions keep historical goals in use. */
+export declare function findMetricUsage(exec: Executor, id: DocId): Promise<{
+    name: string;
+} | null>;

package/dist/db/metricUsage.js

@@ -0,0 +1,54 @@
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+/** Request transaction only: serialize the guard with FK checks and freezes. */ export async function lockMetricRow(exec, id, mode) {
+    const lock = mode === 'delete' ? 'FOR UPDATE' : 'FOR NO KEY UPDATE';
+    await exec.query(`SELECT 1 FROM ${qualifiedTable(exec, TABLES.metrics)} WHERE ${q(COLUMNS.metrics.id)} = $1 ${lock}`, [
+        id
+    ]);
+}
+/** Transition transaction only, after advisory locks. SQL orders by the native
+ * id type so overlapping freezes always acquire row locks in the same order.
+ * Return the locked identities so callers can reject a change that committed
+ * after preflight. Missing rows mean a goal was deleted; never freeze that copy.
+ * txExecutor throws if the request no longer has a transaction session.
+ */ export async function lockMetricsForFreeze(exec, ids) {
+    // Deduplicate for the row-count check; SQL ORDER BY sets the lock order.
+    const sorted = [
+        ...new Map(ids.map((id)=>[
+                String(id),
+                id
+            ])).values()
+    ].sort((a, b)=>typeof a === 'number' && typeof b === 'number' ? a - b : String(a).localeCompare(String(b)));
+    const m = COLUMNS.metrics, id = q(m.id);
+    const result = await exec.query(`SELECT ${id}, ${q(m.slug)}, ${q(m.source)} FROM ${qualifiedTable(exec, TABLES.metrics)} WHERE ${id} = ANY($1) ORDER BY ${id} FOR SHARE`, [
+        sorted
+    ]);
+    return result.rows.length === sorted.length ? result.rows : null;
+}
+/** Live selections cover drafts; frozen definitions keep historical goals in use. */ export async function findMetricUsage(exec, id) {
+    const e = COLUMNS.experiments, p = COLUMNS.phases, r = COLUMNS.experimentsRels;
+    const result = await exec.query(`
+    SELECT COALESCE(usage.name, 'Deleted test') AS name FROM (
+      SELECT e.${q(e.name)} AS name, e.${q(e.status)} AS status
+      FROM ${qualifiedTable(exec, TABLES.phases)} p
+      LEFT JOIN ${qualifiedTable(exec, TABLES.experiments)} e ON e.${q(e.id)} = p.${q(p.experimentId)}
+      WHERE jsonb_typeof(p.${q(p.metricDefinitions)}) = 'array' AND EXISTS (
+        SELECT 1 FROM jsonb_array_elements(p.${q(p.metricDefinitions)}) definition
+        WHERE definition->>'metricId' = $1::text
+      )
+      UNION ALL
+      SELECT e.${q(e.name)} AS name, e.${q(e.status)} AS status
+      FROM ${qualifiedTable(exec, TABLES.experiments)} e
+      WHERE e.${q(e.metricsPrimaryId)}::text = $1::text OR EXISTS (
+        SELECT 1 FROM ${qualifiedTable(exec, TABLES.experimentsRels)} r
+        WHERE r.${q(r.parentId)} = e.${q(e.id)}
+          AND r.${q(r.path)} IN ('metrics.secondary', 'metrics.guardrails')
+          AND r.${q(r.xpMetricsId)}::text = $1::text
+      )
+    ) usage
+    ORDER BY CASE WHEN usage.status IN ('running', 'decided') THEN 0 ELSE 1 END, usage.name
+    LIMIT 1`, [
+        String(id)
+    ]);
+    return result.rows[0] ?? null;
+}

package/dist/db/names.d.ts

@@ -83,6 +83,8 @@ export declare const COLUMNS: {
         readonly decisionDiscardedAt: "decision_discarded_at";
         readonly decisionContentReport: "decision_content_report";
         readonly decisionHoldoutReleasedAt: "decision_holdout_released_at";
+        readonly decisionPagesReleasedAt: "decision_pages_released_at";
+        readonly decisionPagesReleasedBy: "decision_pages_released_by";
         readonly updatedAt: "updated_at";
         readonly createdAt: "created_at";
     };
@@ -151,6 +153,8 @@ export declare const COLUMNS: {
         readonly versionDecisionDiscardedAt: "version_decision_discarded_at";
         readonly versionDecisionContentReport: "version_decision_content_report";
         readonly versionDecisionHoldoutReleasedAt: "version_decision_holdout_released_at";
+        readonly versionDecisionPagesReleasedAt: "version_decision_pages_released_at";
+        readonly versionDecisionPagesReleasedBy: "version_decision_pages_released_by";
         readonly versionUpdatedAt: "version_updated_at";
         readonly versionCreatedAt: "version_created_at";
         readonly createdAt: "created_at";
@@ -227,6 +231,7 @@ export declare const COLUMNS: {
         readonly anonymousId: "anonymous_id";
         readonly userId: "user_id";
         readonly linkedAt: "linked_at";
+        readonly verifiedAt: "verified_at";
         readonly updatedAt: "updated_at";
         readonly createdAt: "created_at";
     };

package/dist/db/names.js

@@ -82,6 +82,8 @@ export const COLUMNS = {
         decisionDiscardedAt: 'decision_discarded_at',
         decisionContentReport: 'decision_content_report',
         decisionHoldoutReleasedAt: 'decision_holdout_released_at',
+        decisionPagesReleasedAt: 'decision_pages_released_at',
+        decisionPagesReleasedBy: 'decision_pages_released_by',
         updatedAt: 'updated_at',
         createdAt: 'created_at'
     },
@@ -150,6 +152,8 @@ export const COLUMNS = {
         versionDecisionDiscardedAt: 'version_decision_discarded_at',
         versionDecisionContentReport: 'version_decision_content_report',
         versionDecisionHoldoutReleasedAt: 'version_decision_holdout_released_at',
+        versionDecisionPagesReleasedAt: 'version_decision_pages_released_at',
+        versionDecisionPagesReleasedBy: 'version_decision_pages_released_by',
         versionUpdatedAt: 'version_updated_at',
         versionCreatedAt: 'version_created_at',
         createdAt: 'created_at',
@@ -226,6 +230,7 @@ export const COLUMNS = {
         anonymousId: 'anonymous_id',
         userId: 'user_id',
         linkedAt: 'linked_at',
+        verifiedAt: 'verified_at',
         updatedAt: 'updated_at',
         createdAt: 'created_at'
     },

package/dist/db/pageOccupancy.d.ts

@@ -0,0 +1,12 @@
+import type { Arm, DocId } from '../types/contracts.js';
+import type { Executor } from './executor.js';
+/** Page tests that occupy paths, with the arms the runtime routes on (`compileManifest`):
+ * - running or decided: the latest round's arms, or for a rollout the latest test round's;
+ * - archived with a standing result (winner, not discarded, pages not released): the latest test
+ *   round's arms whose paths are rewritten to the winner (archivedPages), so a new test cannot
+ *   silently take them over.
+ * Documents' arms may have been edited while stopped, so occupancy never reads them. */
+export declare function routedPageTests(exec: Executor): Promise<Array<{
+    id: DocId;
+    arms: Arm[];
+}>>;