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

package/dist/db/appends.js

@@ -0,0 +1,116 @@
+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) {
+    const doc = await req.payload.db.findOne({
+        collection,
+        req,
+        where: {
+            id: {
+                equals: id
+            }
+        },
+        // Adapter reads have no access layer; document the audit's access posture.
+        overrideAccess: false
+    });
+    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
+    // the baseline (published main rows remain reliable after version pruning).
+    if (doc._status === 'draft') {
+        // §7.8 contentChanges exception: existence only, on the capture savepoint's req.
+        const published = await req.payload.db.findVersions({
+            collection,
+            req,
+            limit: 1,
+            pagination: false,
+            where: {
+                and: [
+                    {
+                        parent: {
+                            equals: id
+                        }
+                    },
+                    {
+                        'version._status': {
+                            equals: 'published'
+                        }
+                    }
+                ]
+            },
+            overrideAccess: false
+        });
+        if (!published.docs.length) return undefined;
+    }
+    return doc;
+}
+/** Serialize flagDefaults read/modify/write before the manifest builder bumps. */ export async function lockContentDefaults(exec) {
+    await exec.query("SELECT pg_advisory_xact_lock(hashtext('xp:state'), 0)");
+}
+/** §7.8 contentChanges exception: internal lookup on the host transaction.
+ * Use the executor directly: Payload Local API read errors kill the caller's
+ * transaction before a never-throw hook can recover its audit savepoint.
+ */ export async function runningContentExperiment(exec, binding) {
+    const table = qualifiedTable(exec, TABLES.experiments);
+    const c = COLUMNS.experiments;
+    const { rows } = await exec.query(`SELECT ${quote(c.id)} AS id, ${quote(c.phase)} AS phase FROM ${table} WHERE ${quote(c[binding.field])} = $1 AND ${quote(c.status)} = 'running' LIMIT 1`, [
+        binding.value
+    ]);
+    return rows[0];
+}
+async function append(exec, column, { experimentId, phase, entry }) {
+    const table = qualifiedTable(exec, TABLES.phases);
+    const c = COLUMNS.phases;
+    const { rowCount } = await exec.query(`UPDATE ${table} SET ${quote(column)} = coalesce(${quote(column)}, '[]'::jsonb) || $1::jsonb WHERE ${quote(c.experimentId)} = $2 AND ${quote(c.phase)} = $3`, [
+        JSON.stringify([
+            entry
+        ]),
+        experimentId,
+        phase
+    ]);
+    if (rowCount === 0) throw new XpRefusal('not-found', 'The phase record was not found.', {
+        experimentId,
+        phase
+    }, 404);
+}
+/** Requires the experiment lock on the transaction executor (withTransition).
+ * The generated schema stores allocationChanges as one JSONB column, not rows.
+ */ export function appendAllocationChange(exec, args) {
+    return append(exec, COLUMNS.phases.allocationChanges, args);
+}
+/** Requires the experiment lock on the transaction executor (withTransition).
+ * The generated schema stores contentChanges as one JSONB column, not rows.
+ */ export function appendContentChange(exec, args) {
+    return append(exec, COLUMNS.phases.contentChanges, args);
+}
+/** A best-effort audit must not abort the host write sharing its transaction.
+ * Recover SQL errors before returning them: catching alone leaves Postgres aborted.
+ */ export async function contentChangeSavepoint(exec, fn) {
+    await exec.query('SAVEPOINT xp_content_change');
+    try {
+        const { rows } = await exec.query("SELECT current_setting('lock_timeout') AS timeout");
+        const previousTimeout = rows[0].timeout;
+        await exec.query("SELECT set_config('lock_timeout', '2s', true)");
+        const result = await fn();
+        // RELEASE retains SET LOCAL changes; restore the caller's value explicitly.
+        await exec.query("SELECT set_config('lock_timeout', $1, true)", [
+            previousTimeout
+        ]);
+        await exec.query('RELEASE SAVEPOINT xp_content_change');
+        return {
+            ok: true,
+            result
+        };
+    } catch (error) {
+        // ROLLBACK TO restores SET LOCAL and releases locks acquired in this savepoint.
+        await exec.query('ROLLBACK TO SAVEPOINT xp_content_change');
+        await exec.query('RELEASE SAVEPOINT xp_content_change');
+        return {
+            ok: false,
+            error
+        };
+    }
+}

package/dist/db/delete.d.ts

@@ -0,0 +1,17 @@
+import type { PayloadRequest } from 'payload';
+import type { DocId } from '../types/contracts.js';
+import type { Executor } from './executor.js';
+interface DeleteState {
+    tail: Promise<void>;
+    excludedIds: Map<string, DocId>;
+    pruneFlagDefaultIds: Map<string, DocId>;
+}
+/** Payload bulk delete runs hooks concurrently on a shared transaction. Queue
+ * each hook body, including the full manifest read/modify/write, on that session.
+ * Successful beforeDelete bodies retain exclusions until the transaction ends:
+ * another row can be between hooks with its children gone but its row present.
+ */
+export declare function serializeDelete<T>(req: PayloadRequest, fn: (state: DeleteState) => Promise<T>): Promise<T>;
+/** Select only snapshot ids and delete the entire set in one SQL statement. */
+export declare function deleteExperimentSnapshots(exec: Executor, experimentId: DocId): Promise<void>;
+export {};

package/dist/db/delete.js

@@ -0,0 +1,35 @@
+import { XpNoTransactionError } from '../errors.js';
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as quote } from './sql.js';
+// Key by the actual session: borrowed requests in one transaction share a queue,
+// different Payload instances do not, and commit/rollback permits GC of state.
+const transactions = new WeakMap();
+/** Payload bulk delete runs hooks concurrently on a shared transaction. Queue
+ * each hook body, including the full manifest read/modify/write, on that session.
+ * Successful beforeDelete bodies retain exclusions until the transaction ends:
+ * another row can be between hooks with its children gone but its row present.
+ */ export async function serializeDelete(req, fn) {
+    const id = await req.transactionID;
+    const session = id == null ? undefined : req.payload.db.sessions?.[id];
+    if (!session) throw new XpNoTransactionError();
+    let state = transactions.get(session);
+    if (!state) {
+        state = {
+            tail: Promise.resolve(),
+            excludedIds: new Map(),
+            pruneFlagDefaultIds: new Map()
+        };
+        transactions.set(session, state);
+    }
+    const current = state;
+    const work = current.tail.then(()=>fn(current));
+    current.tail = work.then(()=>undefined, ()=>undefined);
+    return work;
+}
+/** Select only snapshot ids and delete the entire set in one SQL statement. */ export async function deleteExperimentSnapshots(exec, experimentId) {
+    const table = qualifiedTable(exec, TABLES.resultsSnapshots);
+    const c = COLUMNS.resultsSnapshots;
+    await exec.query(`DELETE FROM ${table} WHERE ${quote(c.id)} IN (SELECT ${quote(c.id)} FROM ${table} WHERE ${quote(c.experimentId)} = $1)`, [
+        experimentId
+    ]);
+}

package/dist/db/erase.d.ts

@@ -0,0 +1,12 @@
+import type { Payload } from 'payload';
+import { type Executor } from './executor.js';
+/** The caller owns the transaction spanning the read and both deletes. */
+export declare function eraseUserRows(exec: Executor, userId: string): Promise<{
+    identities: number;
+    events: number;
+}>;
+/** Own a Payload transaction, then verify on the pool: Payload can swallow COMMIT errors. */
+export declare function eraseUserInTransaction(payload: Payload, userId: string): Promise<{
+    identities: number;
+    events: number;
+}>;

package/dist/db/erase.js

@@ -0,0 +1,55 @@
+import { pooledExecutor, txExecutor } from './executor.js';
+import { COLUMNS, TABLES } from './names.js';
+const quote = (name)=>`"${name.replaceAll('"', '""')}"`;
+const i = COLUMNS.identities;
+const e = COLUMNS.events;
+function table(exec, name) {
+    const schema = exec.schemaName;
+    return `${schema ? `${quote(schema)}.` : ''}${quote(name)}`;
+}
+const eventPredicate = `${quote(e.userId)} = $1 OR (${quote(e.unitType)} = 'user' AND ${quote(e.unitId)} = $1) OR ${quote(e.unitId)} = ANY($2::text[])`;
+async function erase(exec, userId) {
+    const linked = await exec.query(`SELECT ${quote(i.anonymousId)} AS "anonymousId" FROM ${table(exec, TABLES.identities)} WHERE ${quote(i.userId)} = $1`, [
+        userId
+    ]);
+    const anonymousIds = linked.rows.map((row)=>row.anonymousId);
+    const events = await exec.query(`DELETE FROM ${table(exec, TABLES.events)} WHERE ${eventPredicate} RETURNING ${quote(e.id)}`, [
+        userId,
+        anonymousIds
+    ]);
+    const identities = await exec.query(`DELETE FROM ${table(exec, TABLES.identities)} WHERE ${quote(i.userId)} = $1 RETURNING ${quote(i.id)}`, [
+        userId
+    ]);
+    return {
+        counts: {
+            identities: identities.rows.length,
+            events: events.rows.length
+        },
+        anonymousIds
+    };
+}
+/** The caller owns the transaction spanning the read and both deletes. */ export async function eraseUserRows(exec, userId) {
+    return (await erase(exec, userId)).counts;
+}
+/** Own a Payload transaction, then verify on the pool: Payload can swallow COMMIT errors. */ export async function eraseUserInTransaction(payload, userId) {
+    const transactionID = await payload.db.beginTransaction();
+    if (transactionID == null) throw new Error('Experiments: eraseUser requires a transaction');
+    let result;
+    try {
+        result = await erase(txExecutor({
+            payload,
+            transactionID
+        }), userId);
+        await payload.db.commitTransaction(transactionID);
+    } catch (error) {
+        await payload.db.rollbackTransaction(transactionID);
+        throw error;
+    }
+    const exec = pooledExecutor(payload);
+    const verified = await exec.query(`SELECT EXISTS (SELECT 1 FROM ${table(exec, TABLES.events)} WHERE ${eventPredicate}) OR EXISTS (SELECT 1 FROM ${table(exec, TABLES.identities)} WHERE ${quote(i.userId)} = $1) AS remaining`, [
+        userId,
+        result.anonymousIds
+    ]);
+    if (verified.rows[0]?.remaining !== false) throw new Error('Experiments: eraseUser commit unverified');
+    return result.counts;
+}

package/dist/db/events.d.ts

@@ -0,0 +1,21 @@
+import type { DocId, UnitType } from '../types/contracts.js';
+import type { Executor } from './executor.js';
+/** Delete cascade: caller holds the experiment lock in the delete transaction. */
+export declare function deleteExperimentEvents(exec: Executor, experimentId: DocId): Promise<void>;
+export interface EventRow {
+    type: 'exposure' | 'conversion' | 'arm-mismatch';
+    experimentId?: DocId;
+    phase?: number;
+    arm?: string;
+    unitId: string;
+    unitType: UnitType;
+    userId?: string;
+    eventName?: string;
+    value?: number;
+    ts: string;
+    dimensions?: Record<string, string | number | boolean> | null;
+    attributes?: Record<string, unknown>;
+    dedupeKey: string;
+}
+/** Pooled/autocommit executor required: an FK failure must not poison a caller's transaction. */
+export declare function insertEvents(exec: Executor, rows: EventRow[], log?: (message: string) => void): Promise<number>;

package/dist/db/events.js

@@ -0,0 +1,100 @@
+import { exposureDimensions } from '../events/dimensions.js';
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier } from './sql.js';
+/** Delete cascade: caller holds the experiment lock in the delete transaction. */ export async function deleteExperimentEvents(exec, experimentId) {
+    await exec.query(`DELETE FROM ${qualifiedTable(exec, TABLES.events)} WHERE ${quoteIdentifier(COLUMNS.events.experimentId)} = $1`, [
+        experimentId
+    ]);
+}
+const quote = (name)=>`"${name.replaceAll('"', '""')}"`;
+const c = COLUMNS.events;
+function foreignKeyViolation(error) {
+    const seen = new Set();
+    while(error && typeof error === 'object' && !seen.has(error)){
+        seen.add(error);
+        const failure = error;
+        if (failure.code === '23503') return true;
+        error = failure.cause;
+    }
+    return false;
+}
+/** Dimensions are optional: malformed host values (including custom toJSON or
+ * cyclic objects from JavaScript callers) must not abort any row in the batch. */ function serialiseDimensions(row) {
+    if (row.type !== 'exposure' || !row.dimensions) return null;
+    try {
+        const dimensions = exposureDimensions(row.dimensions, Object.keys(row.dimensions));
+        return dimensions ? JSON.stringify(dimensions) : null;
+    } catch  {
+        return null;
+    }
+}
+/** Pooled/autocommit executor required: an FK failure must not poison a caller's transaction. */ export async function insertEvents(exec, rows, log = console.error) {
+    const valid = rows.filter((row)=>{
+        if (row.value === undefined || Number.isFinite(row.value)) return true;
+        log('Experiments: dropped event with non-finite value');
+        return false;
+    });
+    if (!valid.length) return 0;
+    const schema = exec.schemaName;
+    const table = `${schema ? `${quote(schema)}.` : ''}${quote(TABLES.events)}`;
+    async function insert(batch) {
+        const params = [];
+        const values = batch.map((row)=>{
+            const fields = [
+                row.type,
+                row.experimentId ?? null,
+                row.phase ?? null,
+                row.arm ?? null,
+                row.unitId,
+                row.unitType,
+                row.userId ?? null,
+                row.eventName ?? null,
+                row.value ?? null,
+                row.ts,
+                serialiseDimensions(row),
+                row.attributes === undefined ? null : JSON.stringify(row.attributes),
+                row.dedupeKey
+            ];
+            return `(${fields.map((value)=>{
+                params.push(value);
+                return `$${params.length}`;
+            }).join(', ')}, now(), now())`;
+        });
+        const result = await exec.query(`INSERT INTO ${table} (${[
+            c.type,
+            c.experimentId,
+            c.phase,
+            c.arm,
+            c.unitId,
+            c.unitType,
+            c.userId,
+            c.eventName,
+            c.value,
+            c.ts,
+            c.dimensions,
+            c.attributes,
+            c.dedupeKey,
+            c.createdAt,
+            c.updatedAt
+        ].map(quote).join(', ')}) VALUES ${values.join(', ')} ON CONFLICT (${quote(c.dedupeKey)}) DO NOTHING RETURNING ${quote(c.id)}`, params);
+        return result.rows.length;
+    }
+    try {
+        return await insert(valid);
+    } catch (error) {
+        if (!foreignKeyViolation(error)) throw error;
+        // The failed statement is atomic. Retry separately to retain unaffected rows.
+        let count = 0;
+        for (const row of valid){
+            try {
+                count += await insert([
+                    row
+                ]);
+            } catch (error) {
+                if (!foreignKeyViolation(error)) throw error;
+                log('Experiments: dropped event after concurrent experiment deletion');
+            }
+        }
+        return count;
+    }
+}

package/dist/db/executor.d.ts

@@ -0,0 +1,10 @@
+import type { Payload, PayloadRequest } from 'payload';
+import type { Executor } from './pgExecutor.js';
+export type { Executor } from './pgExecutor.js';
+export { pgPoolExecutor, ownConnection, withStatementTimeout, raceDeadline, ResultsBudgetError, RESULTS_TIMEOUT_MARGIN_MS } from './pgExecutor.js';
+export declare function txExecutor(req: PayloadRequest): Executor & {
+    schemaName?: string;
+};
+export declare function pooledExecutor(payload: Payload): Executor & {
+    schemaName?: string;
+};

package/dist/db/executor.js

@@ -0,0 +1,37 @@
+import { sql } from '@payloadcms/db-postgres/drizzle';
+import { XpNoTransactionError } from '../errors.js';
+import { normalise, scanParameters } from './pgExecutor.js';
+export { pgPoolExecutor, ownConnection, withStatementTimeout, raceDeadline, ResultsBudgetError, RESULTS_TIMEOUT_MARGIN_MS } from './pgExecutor.js';
+/** Convert code-only $n placeholders to sql.raw chunks and sql.param values.
+ * Repeated/out-of-order placeholders rebind; arrays are always one parameter.
+ */ function bind(text, params) {
+    const chunks = [];
+    let start = 0;
+    for (const position of scanParameters(text, params)){
+        chunks.push(sql.raw(text.slice(start, position.start)), sql`${sql.param(params[position.index])}`);
+        start = position.end;
+    }
+    chunks.push(sql.raw(text.slice(start)));
+    return sql.join(chunks, sql.raw(''));
+}
+export function txExecutor(req) {
+    const db = req.payload.db;
+    return {
+        schemaName: db.schemaName,
+        async query (text, params = []) {
+            const id = await req.transactionID;
+            const session = id == null ? undefined : db.sessions?.[id];
+            if (!session) throw new XpNoTransactionError();
+            return normalise(await session.db.execute(bind(text, params)));
+        }
+    };
+}
+export function pooledExecutor(payload) {
+    const db = payload.db;
+    return {
+        schemaName: db.schemaName,
+        async query (text, params = []) {
+            return normalise(await db.drizzle.execute(bind(text, params)));
+        }
+    };
+}

package/dist/db/identities.d.ts

@@ -0,0 +1,11 @@
+import type { Payload } from 'payload';
+import { type Executor } from './executor.js';
+export declare function insertIdentity(exec: Executor, { anonymousId, userId }: {
+    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>;

package/dist/db/identities.js

@@ -0,0 +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 }) {
+    const schema = exec.schemaName;
+    const table = `${schema ? `${quote(schema)}.` : ''}${quote(TABLES.identities)}`;
+    const c = COLUMNS.identities;
+    await exec.query(`INSERT INTO ${table} (${[
+        c.anonymousId,
+        c.userId,
+        c.linkedAt,
+        c.createdAt,
+        c.updatedAt
+    ].map(quote).join(', ')}) VALUES ($1, $2, now(), now(), now()) ON CONFLICT (${quote(c.anonymousId)}) DO NOTHING`, [
+        anonymousId,
+        userId
+    ]);
+}
+/** §5.6 / §7.8: privileged insert, 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, {
+            schemaName: db.schemaName
+        }), identity);
+    } finally{
+        exec.release();
+    }
+}

package/dist/db/locks.d.ts

@@ -0,0 +1,15 @@
+import type { Executor } from './executor.js';
+import type { DocId } from '../types/contracts.js';
+export declare const LOCK_NAMESPACES: {
+    readonly layer: "xp:layer";
+    readonly flagPoint: "xp:flagpoint";
+    readonly experiment: "xp:experiment";
+};
+/** Transaction executor only. Call in layer → flag point → experiment order;
+ * the manifest builder takes the state lock last, after transition writes.
+ */
+export declare function lockTransitionScope(exec: Executor, scope: {
+    experimentId: DocId;
+    layerId?: DocId | null;
+    flagPointId?: string | null;
+}): Promise<void>;

package/dist/db/locks.js

@@ -0,0 +1,23 @@
+export const LOCK_NAMESPACES = {
+    layer: 'xp:layer',
+    flagPoint: 'xp:flagpoint',
+    experiment: 'xp:experiment'
+};
+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))`,
+    experiment: `SELECT pg_advisory_xact_lock(hashtext('${LOCK_NAMESPACES.experiment}'), hashtext($1))`
+};
+/** Transaction executor only. Call in layer → flag point → experiment order;
+ * the manifest builder takes the state lock last, after transition writes.
+ */ export async function lockTransitionScope(exec, scope) {
+    if (scope.layerId != null) await exec.query(LOCK_STATEMENTS.layer, [
+        String(scope.layerId)
+    ]);
+    if (scope.flagPointId) await exec.query(LOCK_STATEMENTS.flagPoint, [
+        scope.flagPointId
+    ]);
+    await exec.query(LOCK_STATEMENTS.experiment, [
+        String(scope.experimentId)
+    ]);
+}

package/dist/db/manifest.d.ts

@@ -0,0 +1,8 @@
+import type { Executor } from './pgExecutor.js';
+import type { Manifest } from '../types/manifest.js';
+export declare function readManifestRow(exec: Executor, options?: {
+    schemaName?: string;
+}): Promise<{
+    revision: number;
+    manifest: Manifest;
+} | null>;

package/dist/db/manifest.js

@@ -0,0 +1,8 @@
+import { readState } from './state.js';
+export async function readManifestRow(exec, options = {}) {
+    const row = await readState(exec, options);
+    return row?.manifest ? {
+        revision: row.revision,
+        manifest: row.manifest
+    } : null;
+}