@delmaredigital/payload-experiments 0.3.0-rc.4 → 0.4.0-rc.2

package/dist/db/locks.d.ts

@@ -5,6 +5,7 @@ export declare const LOCK_NAMESPACES: {
     readonly flagPoint: "xp:flagpoint";
     readonly experiment: "xp:experiment";
     readonly pagePath: "xp:pagepath";
+    readonly slug: "xp:slug";
 };
 /** Transaction executor only. Call in layer → flag point → experiment order;
  * the manifest builder takes the state lock last, after transition writes.
@@ -19,3 +20,10 @@ export declare function lockTransitionScope(exec: Executor, scope: {
  * when different tests share several paths in different arm orders.
  */
 export declare function lockPagePaths(exec: Executor, paths: readonly string[]): Promise<void>;
+/** Locale-independent ordering for every multi-key advisory lock acquisition. */
+export declare function sortLockKeys(keys: readonly string[]): string[];
+export declare function lockSlug(exec: Executor, slug: string): Promise<void>;
+/** Guard takes the audit's entire E set first (KI-6), then its own path locks.
+ * SET LOCAL reverts on abort. Restore explicitly only after successful work.
+ */
+export declare function lockPlacementScope(exec: Executor, experiments: readonly string[], paths: readonly string[]): Promise<void>;

package/dist/db/locks.js

@@ -2,11 +2,13 @@ export const LOCK_NAMESPACES = {
     layer: 'xp:layer',
     flagPoint: 'xp:flagpoint',
     experiment: 'xp:experiment',
-    pagePath: 'xp:pagepath'
+    pagePath: 'xp:pagepath',
+    slug: 'xp:slug'
 };
 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))`,
+    slug: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.slug}'), 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))`
 };
@@ -27,9 +29,30 @@ const LOCK_STATEMENTS = {
  * 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, [
+    for (const path of sortLockKeys(paths))await exec.query(LOCK_STATEMENTS.pagePath, [
         path
     ]);
 }
+/** Locale-independent ordering for every multi-key advisory lock acquisition. */ export function sortLockKeys(keys) {
+    return [
+        ...new Set(keys)
+    ].sort();
+}
+export async function lockSlug(exec, slug) {
+    await exec.query(LOCK_STATEMENTS.slug, [
+        slug
+    ]);
+}
+/** Guard takes the audit's entire E set first (KI-6), then its own path locks.
+ * SET LOCAL reverts on abort. Restore explicitly only after successful work.
+ */ export async function lockPlacementScope(exec, experiments, paths) {
+    const { rows } = await exec.query("SELECT current_setting('lock_timeout') AS timeout");
+    await exec.query("SELECT set_config('lock_timeout', '5s', true)");
+    for (const id of sortLockKeys(experiments))await lockTransitionScope(exec, {
+        experimentId: id
+    });
+    await lockPagePaths(exec, paths);
+    await exec.query("SELECT set_config('lock_timeout', $1, true)", [
+        rows[0].timeout
+    ]);
+}

package/dist/db/names.d.ts

@@ -25,6 +25,7 @@ export declare const COLUMNS: {
         readonly revision: "revision";
         readonly manifest: "manifest";
         readonly flagDefaults: "flag_defaults";
+        readonly retiredSlugs: "retired_slugs";
         readonly updatedAt: "updated_at";
         readonly createdAt: "created_at";
     };
@@ -55,6 +56,7 @@ export declare const COLUMNS: {
         readonly slug: "slug";
         readonly hypothesis: "hypothesis";
         readonly kind: "kind";
+        readonly pageCollection: "page_collection";
         readonly flagPoint: "flag_point";
         readonly exposurePolicy: "exposure_policy";
         readonly unitType: "unit_type";
@@ -125,6 +127,7 @@ export declare const COLUMNS: {
         readonly versionSlug: "version_slug";
         readonly versionHypothesis: "version_hypothesis";
         readonly versionKind: "version_kind";
+        readonly versionPageCollection: "version_page_collection";
         readonly versionFlagPoint: "version_flag_point";
         readonly versionExposurePolicy: "version_exposure_policy";
         readonly versionUnitType: "version_unit_type";
@@ -181,6 +184,7 @@ export declare const COLUMNS: {
         readonly targeting: "targeting";
         readonly metricDefinitions: "metric_definitions";
         readonly analysis: "analysis";
+        readonly placementDocs: "placement_docs";
         readonly contentChanges: "content_changes";
         readonly updatedAt: "updated_at";
         readonly createdAt: "created_at";

package/dist/db/names.js

@@ -24,6 +24,7 @@ export const COLUMNS = {
         revision: 'revision',
         manifest: 'manifest',
         flagDefaults: 'flag_defaults',
+        retiredSlugs: 'retired_slugs',
         updatedAt: 'updated_at',
         createdAt: 'created_at'
     },
@@ -54,6 +55,7 @@ export const COLUMNS = {
         slug: 'slug',
         hypothesis: 'hypothesis',
         kind: 'kind',
+        pageCollection: 'page_collection',
         flagPoint: 'flag_point',
         exposurePolicy: 'exposure_policy',
         unitType: 'unit_type',
@@ -124,6 +126,7 @@ export const COLUMNS = {
         versionSlug: 'version_slug',
         versionHypothesis: 'version_hypothesis',
         versionKind: 'version_kind',
+        versionPageCollection: 'version_page_collection',
         versionFlagPoint: 'version_flag_point',
         versionExposurePolicy: 'version_exposure_policy',
         versionUnitType: 'version_unit_type',
@@ -180,6 +183,7 @@ export const COLUMNS = {
         targeting: 'targeting',
         metricDefinitions: 'metric_definitions',
         analysis: 'analysis',
+        placementDocs: 'placement_docs',
         contentChanges: 'content_changes',
         updatedAt: 'updated_at',
         createdAt: 'created_at'

package/dist/db/pageBindings.d.ts

@@ -0,0 +1,4 @@
+import type { DocId } from '../types/contracts.js';
+import type { Executor } from './executor.js';
+/** Current running round, independent of manifest compilation and typed targeting. */
+export declare function pageContentBindings(exec: Executor, collection: string, paths: readonly string[]): Promise<DocId[]>;

package/dist/db/pageBindings.js

@@ -0,0 +1,17 @@
+import { TABLES, COLUMNS } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+import { normalisePath } from '../runtime/normalisePath.js';
+/** Current running round, independent of manifest compilation and typed targeting. */ // Legacy tests without pageCollection match the same path in any collection; stored collections narrow the match.
+export async function pageContentBindings(exec, collection, paths) {
+    if (!paths.length) return [];
+    const e = COLUMNS.experiments, p = COLUMNS.phases;
+    const { rows } = await exec.query(`SELECT x.${q(e.id)} AS id, p.${q(p.arms)} AS arms
+    FROM ${qualifiedTable(exec, TABLES.experiments)} x JOIN ${qualifiedTable(exec, TABLES.phases)} p
+    ON p.${q(p.experimentId)} = x.${q(e.id)} AND p.${q(p.phase)} = x.${q(e.phase)}
+    WHERE x.${q(e.kind)} = 'page' AND x.${q(e.status)} = 'running'
+      AND (x.${q(e.pageCollection)} = $1 OR x.${q(e.pageCollection)} IS NULL)`, [
+        collection
+    ]);
+    const wanted = new Set(paths);
+    return rows.filter((row)=>row.arms.some((arm)=>typeof arm.pageTarget === 'string' && wanted.has(normalisePath(arm.pageTarget)))).map((row)=>row.id);
+}

package/dist/db/pageBusy.d.ts

@@ -0,0 +1,2 @@
+/** DrizzleQueryError wraps driver errors; driver SQLSTATE can occur anywhere in cause. */
+export declare function isPageBusy(error: unknown): boolean;

package/dist/db/pageBusy.js

@@ -0,0 +1,10 @@
+/** DrizzleQueryError wraps driver errors; driver SQLSTATE can occur anywhere in cause. */ export function isPageBusy(error) {
+    const seen = new Set();
+    while(error && typeof error === 'object' && !seen.has(error)){
+        seen.add(error);
+        const failure = error;
+        if (failure.code === '40P01' || failure.code === '55P03') return true;
+        error = failure.cause;
+    }
+    return false;
+}

package/dist/db/pageContent.d.ts

@@ -0,0 +1,10 @@
+import type { PayloadRequest } from 'payload';
+import type { DocId } from '../types/contracts.js';
+/** §7.8: version-identical compares published content raw (ids stripped). */
+export declare function pageVersionContent(req: PayloadRequest, collection: string, id: DocId): Promise<(Record<string, unknown> & {
+    id: DocId;
+}) | null>;
+/** §7.8: status computes a page's published (or never-published draft) path. */
+export declare function statusPageContent(req: PayloadRequest, collection: string, id: DocId): Promise<(Record<string, unknown> & {
+    id: DocId;
+}) | null>;

package/dist/db/pageContent.js

@@ -0,0 +1,79 @@
+/** §7.8: version-identical compares published content raw (ids stripped). */ export async function pageVersionContent(req, collection, id) {
+    return req.payload.db.findOne({
+        collection,
+        req,
+        where: {
+            id: {
+                equals: id
+            }
+        },
+        // Adapter read: version-identical compares published content raw (ids stripped).
+        overrideAccess: true
+    });
+}
+/** §7.8: status computes a page's published (or never-published draft) path. */ export async function statusPageContent(req, collection, id) {
+    const doc = await req.payload.db.findOne({
+        collection,
+        req,
+        where: {
+            id: {
+                equals: id
+            }
+        },
+        // Adapter read: status computes a page's published (or never-published draft) path.
+        overrideAccess: true
+    });
+    if (!doc || doc._status !== 'draft') return doc;
+    // A formerly published but currently unpublished page still uses its stored main-row path.
+    const published = await req.payload.db.findVersions({
+        collection,
+        req,
+        limit: 1,
+        pagination: false,
+        where: {
+            and: [
+                {
+                    parent: {
+                        equals: id
+                    }
+                },
+                {
+                    'version._status': {
+                        equals: 'published'
+                    }
+                }
+            ]
+        },
+        // Adapter read: status computes a page's published (or never-published draft) path.
+        overrideAccess: true
+    });
+    if (published.docs.length) return doc;
+    // §7.8: status computes a page's published (or never-published draft) path.
+    const latest = await req.payload.db.findVersions({
+        collection,
+        req,
+        limit: 1,
+        pagination: false,
+        sort: '-updatedAt',
+        where: {
+            and: [
+                {
+                    parent: {
+                        equals: id
+                    }
+                },
+                {
+                    latest: {
+                        equals: true
+                    }
+                }
+            ]
+        },
+        // Adapter read: status computes a page's published (or never-published draft) path.
+        overrideAccess: true
+    });
+    return latest.docs[0] ? {
+        ...latest.docs[0].version,
+        id
+    } : doc;
+}

package/dist/db/placements.d.ts

@@ -0,0 +1,33 @@
+import type { PayloadRequest } from 'payload';
+import type { Arm, DocId } from '../types/contracts.js';
+import type { Executor } from './executor.js';
+export interface PlacementDoc {
+    collection: string;
+    id: DocId;
+}
+export interface PlacementTest {
+    id: DocId;
+    slug: string;
+    name: string;
+    status: string;
+    kind: string;
+    pageCollection: string | null;
+    phase: number;
+    winnerArm?: string | null;
+    discardedAt?: string | null;
+    pagesReleasedAt?: string | null;
+    arms: Arm[];
+    placementDocs: PlacementDoc[] | null;
+}
+/** Raw reads only: guard discovery includes every status, interaction checks filter under the locks. */
+export declare function placementTests(exec: Executor): Promise<PlacementTest[]>;
+/** §7.8: interacting-tests computes placement paths from published rows. */
+export declare function placementPathContent(req: PayloadRequest, collection: string, id: DocId): Promise<(Record<string, unknown> & {
+    id: DocId;
+}) | null>;
+/** Caller holds E. Never coalesce null: old rounds must continue to scan. */
+export declare function appendPlacementDoc(exec: Executor, experimentId: DocId, phase: number, doc: PlacementDoc): Promise<void>;
+/** Deciding a stopped modern round restores routing on its detached rescan.
+ * Legacy null rounds retain scan-on-every-check semantics. Caller holds E.
+ */
+export declare function refreshPlacementDocs(exec: Executor, experimentId: DocId, phase: number, docs: readonly PlacementDoc[]): Promise<void>;

package/dist/db/placements.js

@@ -0,0 +1,54 @@
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+/** Raw reads only: guard discovery includes every status, interaction checks filter under the locks. */ export async function placementTests(exec) {
+    const e = COLUMNS.experiments, p = COLUMNS.phases;
+    const { rows } = await exec.query(`SELECT x.${q(e.id)} AS id, x.${q(e.slug)} AS slug, x.${q(e.name)} AS name,
+    x.${q(e.status)} AS status, x.${q(e.kind)} AS kind, x.${q(e.pageCollection)} AS "pageCollection",
+    x.${q(e.decisionWinnerArm)} AS "winnerArm", x.${q(e.decisionDiscardedAt)} AS "discardedAt", x.${q(e.decisionPagesReleasedAt)} AS "pagesReleasedAt", p.${q(p.phase)} AS phase, p.${q(p.arms)} AS arms, p.${q(p.placementDocs)} AS "placementDocs"
+    FROM ${qualifiedTable(exec, TABLES.experiments)} x
+    LEFT JOIN LATERAL (SELECT * FROM ${qualifiedTable(exec, TABLES.phases)} WHERE ${q(p.experimentId)} = x.${q(e.id)}
+      AND ${q(p.phaseKind)} = 'test' ORDER BY ${q(p.phase)} DESC LIMIT 1) p ON true`, []);
+    return rows.map((row)=>({
+            ...row,
+            arms: Array.isArray(row.arms) ? row.arms : [],
+            placementDocs: row.placementDocs ?? null
+        }));
+}
+/** §7.8: interacting-tests computes placement paths from published rows. */ export async function placementPathContent(req, collection, id) {
+    return req.payload.db.findOne({
+        collection,
+        req,
+        where: {
+            id: {
+                equals: id
+            }
+        },
+        // Adapter read: interacting-tests computes placement paths from published rows.
+        overrideAccess: true
+    });
+}
+/** Caller holds E. Never coalesce null: old rounds must continue to scan. */ export async function appendPlacementDoc(exec, experimentId, phase, doc) {
+    const p = COLUMNS.phases, column = q(p.placementDocs);
+    await exec.query(`UPDATE ${qualifiedTable(exec, TABLES.phases)} SET ${column} = ${column} || $1::jsonb
+    WHERE ${q(p.experimentId)} = $2 AND ${q(p.phase)} = $3 AND ${column} IS NOT NULL
+      AND NOT EXISTS (SELECT 1 FROM jsonb_array_elements(${column}) entry WHERE entry->>'collection' = $4 AND entry->>'id' = $5)`, [
+        JSON.stringify([
+            doc
+        ]),
+        experimentId,
+        phase,
+        doc.collection,
+        String(doc.id)
+    ]);
+}
+/** Deciding a stopped modern round restores routing on its detached rescan.
+ * Legacy null rounds retain scan-on-every-check semantics. Caller holds E.
+ */ export async function refreshPlacementDocs(exec, experimentId, phase, docs) {
+    const p = COLUMNS.phases;
+    await exec.query(`UPDATE ${qualifiedTable(exec, TABLES.phases)} SET ${q(p.placementDocs)} = $1::jsonb
+    WHERE ${q(p.experimentId)} = $2 AND ${q(p.phase)} = $3 AND ${q(p.placementDocs)} IS NOT NULL`, [
+        JSON.stringify(docs),
+        experimentId,
+        phase
+    ]);
+}

package/dist/db/slugs.d.ts

@@ -0,0 +1,8 @@
+import type { GlobalBeforeChangeHook } from 'payload';
+import { type Executor } from './executor.js';
+/** Each candidate is locked before its live and retired checks, including suffix collisions. */
+export declare function pickSlug(exec: Executor, stem: string, transactional: boolean): Promise<string>;
+/** Delete owns the experiment lock; state is always acquired last. */
+export declare function retireSlug(exec: Executor, slug: string): Promise<void>;
+/** Payload merges the previous global into writes. Refresh the append-only column under its lock. */
+export declare const preserveRetiredSlugs: GlobalBeforeChangeHook;

package/dist/db/slugs.js

@@ -0,0 +1,40 @@
+import { pooledExecutor, txExecutor } from './executor.js';
+import { lockSlug } from './locks.js';
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+/** Each candidate is locked before its live and retired checks, including suffix collisions. */ export async function pickSlug(exec, stem, transactional) {
+    // Overlapping stems across creates in one host transaction can deadlock; hashtext collisions can wait. The unique index remains the backstop.
+    const e = COLUMNS.experiments, s = COLUMNS.state;
+    for(let n = 1;; n++){
+        const suffix = n === 1 ? '' : `-${n}`;
+        const candidate = stem.slice(0, 64 - suffix.length) + suffix;
+        if (transactional) await lockSlug(exec, candidate);
+        const { rows } = await exec.query(`SELECT EXISTS (SELECT 1 FROM ${qualifiedTable(exec, TABLES.experiments)} WHERE ${q(e.slug)} = $1)
+      OR EXISTS (SELECT 1 FROM ${qualifiedTable(exec, TABLES.state)} WHERE coalesce(${q(s.retiredSlugs)}, '[]'::jsonb) ? $1) AS used`, [
+            candidate
+        ]);
+        if (!rows[0]?.used) return candidate;
+    }
+}
+/** Delete owns the experiment lock; state is always acquired last. */ export async function retireSlug(exec, slug) {
+    await exec.query("SELECT pg_advisory_xact_lock(hashtext('xp:state'), 0)");
+    const s = COLUMNS.state, table = qualifiedTable(exec, TABLES.state);
+    await exec.query(`INSERT INTO ${table} (${q(s.revision)}, ${q(s.retiredSlugs)}, ${q(s.createdAt)}, ${q(s.updatedAt)})
+    SELECT 0, '[]'::jsonb, now(), now() WHERE NOT EXISTS (SELECT 1 FROM ${table})`);
+    await exec.query(`UPDATE ${table} SET ${q(s.retiredSlugs)} = coalesce(${q(s.retiredSlugs)}, '[]'::jsonb) || $1::jsonb
+    WHERE NOT (coalesce(${q(s.retiredSlugs)}, '[]'::jsonb) ? $2)`, [
+        JSON.stringify([
+            slug
+        ]),
+        slug
+    ]);
+}
+/** Payload merges the previous global into writes. Refresh the append-only column under its lock. */ export const preserveRetiredSlugs = async ({ req, data })=>{
+    const transactional = await req.transactionID != null;
+    const exec = transactional ? txExecutor(req) : pooledExecutor(req.payload);
+    // A host write with disableTransaction can race a retirement and lose its append; plugin writes always use a transaction.
+    if (transactional) await exec.query("SELECT pg_advisory_xact_lock(hashtext('xp:state'), 0)");
+    const { rows } = await exec.query(`SELECT ${q(COLUMNS.state.retiredSlugs)} AS retired FROM ${qualifiedTable(exec, TABLES.state)} LIMIT 1`);
+    data.retiredSlugs = rows[0]?.retired ?? null;
+    return data;
+};

package/dist/db/snapshots.d.ts

@@ -1,5 +1,6 @@
 import type { Payload } from 'payload';
 import type { Arm, DocId, ExperimentKind, Status, UnitType } from '../types/contracts.js';
+import type { PlacementDoc } from './placements.js';
 import type { Snapshot } from '../types/snapshot.js';
 import type { AnalysisPhase, FrozenMetric } from '../results/analyse.js';
 import { type Executor } from './executor.js';
@@ -9,14 +10,19 @@ export interface ResultsPhase extends AnalysisPhase {
     allocation: number;
     metricDefinitions: Array<FrozenMetric & {
         source: string;
+        addedAt?: string;
         keyedBy?: UnitType;
         capNotice?: 'no-history';
     }>;
 }
 export interface ResultsCandidate {
+    slug?: string;
+    testPlacementDocs?: PlacementDoc[] | null;
     phase: ResultsPhase;
     frozenSnapshot?: Snapshot | null;
+    previousHealth?: Snapshot['health'] | null;
     kind?: ExperimentKind;
+    pageCollection?: string | null;
     currentPhase?: number;
     winnerArm?: string | null;
     unitType: UnitType;

package/dist/db/snapshots.js

@@ -31,21 +31,24 @@ const LATE_BEACON_GRACE_MS = 24 * 60 * 60 * 1000;
       'startedAt', p.${q(p.startedAt)}, 'endedAt', p.${q(p.endedAt)}, 'seed', p.${q(p.seed)},
       'arms', p.${q(p.arms)}, 'allocation', p.${q(p.allocation)}, 'metricDefinitions', p.${q(p.metricDefinitions)},
       'analysis', p.${q(p.analysis)}, 'contentChanges', p.${q(p.contentChanges)}) AS "phase",
-    e.${q(e.kind)} AS "kind", e.${q(e.phase)} AS "currentPhase", e.${q(e.unitType)} AS "unitType", e.${q(e.status)} AS "status", e.${q(e.decisionWinnerArm)} AS "winnerArm",
-    latest."computedAt" AS "latestComputedAt",
+    e.${q(e.slug)} AS "slug",
+    (SELECT t.${q(p.placementDocs)} FROM ${phases} t WHERE t.${q(p.experimentId)} = p.${q(p.experimentId)} AND t.${q(p.phaseKind)} = 'test' AND t.${q(p.phase)} <= p.${q(p.phase)} ORDER BY t.${q(p.phase)} DESC LIMIT 1) AS "testPlacementDocs",
+    e.${q(e.pageCollection)} AS "pageCollection", e.${q(e.kind)} AS "kind", e.${q(e.phase)} AS "currentPhase", e.${q(e.unitType)} AS "unitType", e.${q(e.status)} AS "status", e.${q(e.decisionWinnerArm)} AS "winnerArm",
+    latest."computedAt" AS "latestComputedAt", latest."health" AS "previousHealth",
     (SELECT t.${q(p.arms)} FROM ${phases} t WHERE t.${q(p.experimentId)} = p.${q(p.experimentId)} AND t.${q(p.phaseKind)} = 'test' AND t.${q(p.phase)} <= p.${q(p.phase)} ORDER BY t.${q(p.phase)} DESC LIMIT 1) AS "testArms",
     frozen."snapshot" AS "frozenSnapshot",
     l.${q(l.slug)} AS "layerSlug", e.${q(e.layerSlices)} AS "layerSlices"
     FROM ${phases} p JOIN ${qualifiedTable(exec, TABLES.experiments)} e ON e.${q(e.id)} = p.${q(p.experimentId)}
     LEFT JOIN ${qualifiedTable(exec, TABLES.layers)} l ON l.${q(l.id)} = e.${q(e.layerId)}
-    LEFT JOIN LATERAL (SELECT max(s.${q(s.computedAt)}) AS "computedAt" FROM ${snapshots} s
-      WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}) latest ON true
+    LEFT JOIN LATERAL (SELECT s.${q(s.computedAt)} AS "computedAt", s.${q(s.snapshot)}->'health' AS "health" FROM ${snapshots} s
+      WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}
+      ORDER BY s.${q(s.computedAt)} DESC, s.${q(s.id)} DESC LIMIT 1) latest ON true
     LEFT JOIN LATERAL (SELECT s.${q(s.snapshot)} AS "snapshot" FROM ${snapshots} s
       WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}
         AND p.${q(p.endedAt)} IS NOT NULL
         AND (s.${q(s.computedAt)} > p.${q(p.endedAt)} + $2 * interval '1 millisecond' OR p.${q(p.endedAt)} < $1)
       ORDER BY s.${q(s.computedAt)} DESC, s.${q(s.id)} DESC LIMIT 1) frozen ON true
-    WHERE ((e.${q(e.kind)} = 'page'
+    WHERE (((e.${q(e.kind)} = 'page' OR EXISTS (SELECT 1 FROM jsonb_array_elements(p.${q(p.metricDefinitions)}) goal WHERE goal->>'source' LIKE 'click:%'))
         AND (p.${q(p.endedAt)} IS NULL OR p.${q(p.endedAt)} >= $1 OR EXISTS
           (SELECT 1 FROM ${snapshots} existing WHERE existing.${q(s.experimentId)} = p.${q(p.experimentId)} AND existing.${q(s.phase)} = p.${q(p.phase)}))
         AND e.${q(e.status)} IN ('running', 'decided') AND (p.${q(p.phase)} = e.${q(e.phase)}

package/dist/endpoints/clickKeys.d.ts

@@ -0,0 +1,5 @@
+import type { PayloadRequest } from 'payload';
+import type { EndpointContext } from '../types/endpoints.js';
+export declare function handleClickKeys<TUser extends {
+    id: string | number;
+}>(req: PayloadRequest, { options }: EndpointContext<TUser>): Promise<Response>;

package/dist/endpoints/clickKeys.js

@@ -0,0 +1,17 @@
+import { goalContent } from '../goals/fairness.js';
+import { XpRefusal } from '../errors.js';
+export async function handleClickKeys(req, { options }) {
+    const id = req.routeParams?.id;
+    if (typeof id !== 'string' && typeof id !== 'number') throw new XpRefusal('invalid-body', 'Choose a test.', undefined, 422);
+    const experiment = await req.payload.findByID({
+        collection: 'xp-experiments',
+        id,
+        req,
+        overrideAccess: false,
+        depth: 0
+    });
+    const content = await goalContent(req, options, experiment);
+    return Response.json({
+        keys: content.keys
+    });
+}

package/dist/endpoints/events.js

@@ -1,3 +1,5 @@
+import { clickKeys } from '../goals/cache.js';
+import { validClickSource } from '../goals/key.js';
 import { safeError } from '../log.js';
 import { NextRequest } from 'next/server.js';
 import { DEFAULT_MAX_BODY_BYTES } from '../constants.js';
@@ -83,7 +85,8 @@ export async function handleEvents(req, { options }) {
             preview: isPreview(request)
         });
         if (unresolvedStaff) for (const assignment of Object.values(assignments.bySlug))assignment.exposable = false;
-        const rows = eventRows(events, manifest, assignments, options, visitorId, userId, new Date().toISOString(), attributes);
+        const keys = events.some((event)=>event && typeof event === 'object' && 'eventName' in event && validClickSource(event.eventName)) ? await clickKeys(req.payload) : undefined;
+        const rows = eventRows(events, manifest, assignments, options, visitorId, userId, new Date().toISOString(), attributes, keys);
         // §7.8 events insert / assignment lookup exception: pooled SQL and cached manifest,
         // no Local API calls (and hence no implicit overrideAccess defaults).
         if (rows.length) await insertEvents(pooledExecutor(req.payload), rows, (message)=>req.payload.logger.error(message));

package/dist/endpoints/index.js

@@ -1,3 +1,4 @@
+import { handleClickKeys } from './clickKeys.js';
 import { createHmac, timingSafeEqual } from 'node:crypto';
 import { XP_MANIFEST_KEY_HEADER } from '../constants.js';
 import { XpNotImplemented, XpRefusal } from '../errors.js';
@@ -9,6 +10,9 @@ import { handlePreflight } from './preflight.js';
 import { handlePreviewToken } from './previewToken.js';
 import { handleResults } from './results.js';
 import { handleRecompute } from './recompute.js';
+import { handleWrapBlock } from './wrapBlock.js';
+import { handlePages } from './pages.js';
+import { handlePlacementStatus } from './placementStatus.js';
 import { handleSummary } from './summary.js';
 export const ROUTES = [
     {
@@ -118,6 +122,30 @@ export const ROUTES = [
         path: '/xp/experiments/summary',
         access: 'readResults',
         handler: handleSummary
+    },
+    {
+        method: 'post',
+        path: '/xp/blocks/wrap',
+        access: 'manage',
+        handler: handleWrapBlock
+    },
+    {
+        method: 'get',
+        path: '/xp/experiments/:id/click-keys',
+        access: 'manage',
+        handler: handleClickKeys
+    },
+    {
+        method: 'get',
+        path: '/xp/pages',
+        access: 'manage',
+        handler: handlePages
+    },
+    {
+        method: 'post',
+        path: '/xp/placements/status',
+        access: 'manage',
+        handler: handlePlacementStatus
     }
 ];
 function error(status, code, message, detail) {

package/dist/endpoints/pages.d.ts

@@ -0,0 +1,5 @@
+import type { PayloadRequest } from 'payload';
+import type { EndpointContext } from '../types/endpoints.js';
+export declare function handlePages<TUser extends {
+    id: string | number;
+}>(req: PayloadRequest, { options }: EndpointContext<TUser>): Promise<Response>;