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

package/dist/db/pgExecutor.js

@@ -0,0 +1,250 @@
+import pg from 'pg';
+/** Scan only SQL code, leaving quoted text, identifiers and nested comments alone.
+ * Both transports validate unused/missing params here before touching a database.
+ */ export function scanParameters(text, params) {
+    const positions = [];
+    const used = new Set();
+    const identifier = (char)=>char !== undefined && /[\p{L}\p{N}_$]/u.test(char);
+    let i = 0;
+    while(i < text.length){
+        if (text.startsWith('--', i)) {
+            const end = text.indexOf('\n', i + 2);
+            i = end < 0 ? text.length : end + 1;
+        } else if (text.startsWith('/*', i)) {
+            let depth = 1;
+            i += 2;
+            while(i < text.length && depth){
+                if (text.startsWith('/*', i)) {
+                    depth++;
+                    i += 2;
+                } else if (text.startsWith('*/', i)) {
+                    depth--;
+                    i += 2;
+                } else i++;
+            }
+        } else if (text[i] === "'" || text[i] === '"') {
+            const quote = text[i++];
+            const escaped = quote === "'" && /[eE]/.test(text[i - 2] ?? '') && !identifier(text[i - 3]);
+            while(i < text.length){
+                if (escaped && text[i] === '\\') i += 2;
+                else if (text[i++] === quote) {
+                    if (text[i] === quote) i++;
+                    else break;
+                }
+            }
+        } else if (text[i] === '$' && !identifier(text[i - 1])) {
+            const tag = /^(?:\$[A-Za-z_][A-Za-z_0-9]*\$|\$\$)/.exec(text.slice(i))?.[0];
+            if (tag) {
+                const end = text.indexOf(tag, i + tag.length);
+                i = end < 0 ? text.length : end + tag.length;
+                continue;
+            }
+            const token = /^\$(\d+)/.exec(text.slice(i));
+            if (token) {
+                const index = Number(token[1]) - 1;
+                if (!Number.isSafeInteger(index) || index < 0 || index >= params.length) throw new RangeError(`Missing SQL parameter ${token[0]}`);
+                positions.push({
+                    start: i,
+                    end: i + token[0].length,
+                    index
+                });
+                used.add(index);
+                i += token[0].length;
+            } else i++;
+        } else i++;
+    }
+    if (used.size !== params.length) throw new RangeError('Unused SQL parameters');
+    return positions;
+}
+function numeric(value, integer) {
+    if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'bigint' || typeof value === 'string' && !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(value)) {
+        throw new RangeError('Invalid PostgreSQL numeric value');
+    }
+    const number = Number(value);
+    if (!Number.isFinite(number)) throw new RangeError('Non-finite PostgreSQL numeric value');
+    if (integer && !Number.isSafeInteger(number)) throw new RangeError('PostgreSQL int8 exceeds the safe integer range');
+    return number;
+}
+/** Normalise top-level columns only. Finite numeric (1700) always becomes a
+ * number, accepting double precision rounding as the stats engine does. int8 (20)
+ * becomes a number only within the safe integer range; invalid/non-finite numeric
+ * and unsafe int8 values throw instead of changing a column's JS type by value.
+ * Nulls stay null. timestamp/timestamptz (1114/1184) become UTC ISO strings; infinity
+ * stays a string. JSON, text and opaque IDs stay intact. Drivers must retain raw
+ * numeric text (pg's default, and per-query overrides below) until this boundary.
+ */ export function normalise(value) {
+    const result = value;
+    const types = new Map(result.fields?.map((field)=>[
+            field.name,
+            field.dataTypeID
+        ]));
+    const rows = result.rows.map((row)=>Object.fromEntries(Object.entries(row).map(([key, value])=>{
+            const type = types.get(key);
+            if ((type === 1700 || type === 20) && value !== null) value = numeric(value, type === 20);
+            else if (value instanceof Date) value = value.toISOString();
+            else if (typeof value === 'string' && (type === 1114 || type === 1184) && !/^-?infinity$/i.test(value)) {
+                const timestamp = type === 1114 && !/(?:Z|[+-]\d{2}(?::?\d{2})?)$/.test(value) ? `${value}Z` : value;
+                value = new Date(timestamp).toISOString();
+            }
+            return [
+                key,
+                value
+            ];
+        })));
+    return {
+        rows,
+        rowCount: result.rowCount ?? result.affectedRows ?? rows.length
+    };
+}
+/** Per-query overrides avoid process-global pg parser changes and local-time
+ * timestamp parsing. Other OIDs retain pg's default parsers (including JSON).
+ */ const queryTypes = {
+    getTypeParser (oid, format) {
+        if (format !== 'binary' && [
+            20,
+            1700,
+            1114,
+            1184
+        ].includes(oid)) return (value)=>value;
+        return pg.types.getTypeParser(oid, format);
+    }
+};
+export function pgPoolExecutor(pool) {
+    return {
+        async query (text, params = []) {
+            scanParameters(text, params);
+            // QueryConfig is required to scope type parsers to this query.
+            return normalise(await pool.query({
+                text,
+                values: params,
+                types: queryTypes
+            }));
+        }
+    };
+}
+/** The caller must release in finally; this connection never joins a Payload transaction. */ export async function ownConnection(pool) {
+    const client = await pool.connect();
+    const exec = pgPoolExecutor(client);
+    let queryError;
+    return {
+        async query (text, params) {
+            try {
+                return await exec.query(text, params);
+            } catch (error) {
+                queryError ??= connectionError(error);
+                throw error;
+            }
+        },
+        release: (error)=>client.release(error ?? queryError)
+    };
+}
+export const RESULTS_TIMEOUT_MARGIN_MS = 10;
+export class ResultsBudgetError extends Error {
+    name = 'ResultsBudgetError';
+    constructor(){
+        super('Results budget exhausted');
+    }
+}
+/** SQL errors leave a usable connection after rollback. Transport failures and
+ * deadline races can leave queries in flight, so those clients must be discarded. */ function connectionError(error) {
+    const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined;
+    if (!(error instanceof ResultsBudgetError) && typeof code === 'string' && /^[0-9A-Z]{5}$/.test(code) && !code.startsWith('08') && !code.startsWith('57P')) return undefined;
+    return error instanceof Error ? error : new Error('Query failed', {
+        cause: error
+    });
+}
+/** Invoke lazily so expired work never starts. Promise.race observes late source
+ * rejections too; clearing the timer keeps successful cron calls from lingering. */ export async function raceDeadline(deadline, work) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new ResultsBudgetError();
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve().then(work),
+            new Promise((_, reject)=>{
+                timer = setTimeout(()=>reject(new ResultsBudgetError()), remaining);
+            })
+        ]);
+    } finally{
+        clearTimeout(timer);
+    }
+}
+export async function withStatementTimeout(pool, ms, fn, deadline) {
+    if (!Number.isSafeInteger(ms) || ms <= 0) throw new RangeError('statement timeout must be a positive integer');
+    if (deadline !== undefined) {
+        if (deadline - Date.now() <= RESULTS_TIMEOUT_MARGIN_MS) throw new ResultsBudgetError();
+        let abandoned = false;
+        const connection = Promise.resolve().then(()=>pool.connect()).then((client)=>{
+            if (abandoned) {
+                client.release(new ResultsBudgetError());
+                throw new ResultsBudgetError();
+            }
+            return client;
+        });
+        let client;
+        try {
+            client = await raceDeadline(deadline, ()=>connection);
+        } catch (error) {
+            abandoned = true;
+            throw error;
+        }
+        const exec = pgPoolExecutor(client);
+        let releaseError;
+        try {
+            return await raceDeadline(deadline, async ()=>{
+                if (deadline - Date.now() <= RESULTS_TIMEOUT_MARGIN_MS) throw new ResultsBudgetError();
+                await exec.query('BEGIN');
+                const timeout = Math.min(ms, Math.floor(deadline - Date.now() - RESULTS_TIMEOUT_MARGIN_MS));
+                if (timeout <= 0) throw new ResultsBudgetError();
+                await exec.query(`SET LOCAL statement_timeout = ${timeout}`);
+                if (deadline - Date.now() <= RESULTS_TIMEOUT_MARGIN_MS) throw new ResultsBudgetError();
+                const result = await fn(exec);
+                if (Date.now() >= deadline) throw new ResultsBudgetError();
+                // COMMIT may land while the deadline race reports this experiment as
+                // skipped. Harmless: the next results run rewrites the snapshot.
+                await exec.query('COMMIT');
+                return result;
+            });
+        } catch (error) {
+            const failure = error && typeof error === 'object' && 'code' in error && error.code === '57014' ? new ResultsBudgetError() : error;
+            releaseError = connectionError(error);
+            // Destroy deadline-raced clients immediately, including BEGIN/SET/COMMIT hangs.
+            // A rollback cannot be allowed to extend the caller's deadline either.
+            // A server statement timeout (57014) has settled; rollback can reuse it.
+            if (!(error instanceof ResultsBudgetError)) {
+                try {
+                    await raceDeadline(deadline, ()=>exec.query('ROLLBACK'));
+                } catch (rollbackError) {
+                    // Even an ordinary SQL error here leaves transaction state uncertain.
+                    releaseError = rollbackError instanceof Error ? rollbackError : new Error('Rollback failed', {
+                        cause: rollbackError
+                    });
+                }
+            }
+            throw failure;
+        } finally{
+            client.release(releaseError);
+        }
+    }
+    const exec = await ownConnection(pool);
+    let releaseError;
+    try {
+        await exec.query('BEGIN');
+        await exec.query(`SET LOCAL statement_timeout = ${ms}`);
+        const result = await fn(exec);
+        await exec.query('COMMIT');
+        return result;
+    } catch (error) {
+        releaseError = connectionError(error);
+        try {
+            await exec.query('ROLLBACK');
+        } catch (rollbackError) {
+            releaseError = rollbackError instanceof Error ? rollbackError : new Error('Rollback failed', {
+                cause: rollbackError
+            });
+        }
+        throw error;
+    } finally{
+        exec.release(releaseError);
+    }
+}

package/dist/db/results.d.ts

@@ -0,0 +1,53 @@
+import type { DocId } from '../types/contracts.js';
+import { type Timestamp } from '../results/aggregate.js';
+import type { Executor } from './executor.js';
+export interface PhaseExposureRow {
+    unitId: string;
+    arm: string;
+    ts: number;
+}
+export interface RolloutExposureRow {
+    unitId: string;
+    phase: number;
+    ts: number;
+}
+export interface MetricEventRow {
+    unitId: string;
+    userId: string | null;
+    value: number;
+    ts: number;
+}
+export interface IdentityRow {
+    anonymousId: string;
+    userId: string;
+}
+type PhaseQuery = {
+    experimentId: DocId;
+    phase: number;
+    endedAt?: Timestamp;
+};
+/** All phase exposures, including multi-arm rows for firstExposures to exclude. */
+export declare function phaseExposureRows(exec: Executor, opts: PhaseQuery): Promise<PhaseExposureRow[]>;
+/** Diagnostic distinct units only; this never contributes to multi-arm exclusion. */
+export declare function armMismatchCount(exec: Executor, opts: PhaseQuery): Promise<number>;
+/** All phases are required to identify first-ever exposure for rollout X1. */
+export declare function rolloutExposureRows(exec: Executor, { experimentId, respectPhaseEnds }: {
+    experimentId: DocId;
+    respectPhaseEnds?: boolean;
+}): Promise<RolloutExposureRow[]>;
+/** events:<name> conversion rows in [from, to). Choose unitIds for stored unit_id,
+ * or userIds for stored user_id (user units and visitor identity credit). Each distinct
+ * ID occurs in one ANY array of at most 10,000, so batching cannot duplicate rows.
+ */
+export declare function metricEventRows(exec: Executor, { eventName, unitIds, userIds, from, to }: {
+    eventName: string;
+    unitIds?: readonly string[];
+    userIds?: readonly string[];
+    from: Timestamp;
+    to: Timestamp;
+}): Promise<MetricEventRow[]>;
+/** Linked visitors for creditUserEvents; disjoint ANY batches of ≤ 10,000 IDs. */
+export declare function identityRows(exec: Executor, { anonymousIds }: {
+    anonymousIds: readonly string[];
+}): Promise<IdentityRow[]>;
+export {};

package/dist/db/results.js

@@ -0,0 +1,103 @@
+import { timestampMs } from '../results/aggregate.js';
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+const c = COLUMNS.events;
+const batchSize = 10_000;
+const iso = (ts)=>new Date(timestampMs(ts)).toISOString();
+// round()::bigint keeps exact milliseconds on servers where extract() returns a float (PG ≤ 13).
+const epochMs = `round(extract(epoch from ${q(c.ts)}) * 1000)::bigint`;
+function phaseFilter({ experimentId, phase, endedAt }, type) {
+    const params = [
+        experimentId,
+        phase,
+        type
+    ];
+    let text = `${q(c.experimentId)} = $1 AND ${q(c.phase)} = $2 AND ${q(c.type)} = $3`;
+    if (endedAt !== undefined) {
+        params.push(iso(endedAt));
+        text += ` AND ${q(c.ts)} < $4`;
+    }
+    return {
+        text,
+        params
+    };
+}
+/** All phase exposures, including multi-arm rows for firstExposures to exclude. */ export async function phaseExposureRows(exec, opts) {
+    const filter = phaseFilter(opts, 'exposure');
+    const { rows } = await exec.query(`SELECT ${q(c.unitId)} AS "unitId", ${q(c.arm)} AS "arm", ${epochMs} AS "ts" FROM ${qualifiedTable(exec, TABLES.events)} WHERE ${filter.text} ORDER BY ${q(c.ts)}, ${q(c.unitId)}`, filter.params);
+    return rows.map((row)=>({
+            unitId: row.unitId,
+            arm: row.arm,
+            ts: Number(row.ts)
+        }));
+}
+/** Diagnostic distinct units only; this never contributes to multi-arm exclusion. */ export async function armMismatchCount(exec, opts) {
+    const filter = phaseFilter(opts, 'arm-mismatch');
+    const { rows } = await exec.query(`SELECT count(DISTINCT ${q(c.unitId)}) AS "unitCount" FROM ${qualifiedTable(exec, TABLES.events)} WHERE ${filter.text}`, filter.params);
+    return Number(rows[0].unitCount);
+}
+/** All phases are required to identify first-ever exposure for rollout X1. */ export async function rolloutExposureRows(exec, { experimentId, respectPhaseEnds = false }) {
+    const p = COLUMNS.phases;
+    const cutoff = respectPhaseEnds ? ` AND NOT EXISTS (SELECT 1 FROM ${qualifiedTable(exec, TABLES.phases)} p WHERE p.${q(p.experimentId)} = ${qualifiedTable(exec, TABLES.events)}.${q(c.experimentId)} AND p.${q(p.phase)} = ${qualifiedTable(exec, TABLES.events)}.${q(c.phase)} AND p.${q(p.endedAt)} <= ${qualifiedTable(exec, TABLES.events)}.${q(c.ts)})` : '';
+    const { rows } = await exec.query(`SELECT ${q(c.unitId)} AS "unitId", ${q(c.phase)} AS "phase", ${epochMs} AS "ts" FROM ${qualifiedTable(exec, TABLES.events)} WHERE ${q(c.experimentId)} = $1 AND ${q(c.type)} = $2${cutoff} ORDER BY ${q(c.ts)}, ${q(c.unitId)}, ${q(c.phase)}`, [
+        experimentId,
+        'exposure'
+    ]);
+    return rows.map((row)=>({
+            unitId: row.unitId,
+            phase: Number(row.phase),
+            ts: Number(row.ts)
+        }));
+}
+/** events:<name> conversion rows in [from, to). Choose unitIds for stored unit_id,
+ * or userIds for stored user_id (user units and visitor identity credit). Each distinct
+ * ID occurs in one ANY array of at most 10,000, so batching cannot duplicate rows.
+ */ export async function metricEventRows(exec, { eventName, unitIds, userIds, from, to }) {
+    if (unitIds !== undefined && userIds !== undefined) throw new RangeError('Choose unitIds or userIds');
+    const params = [
+        'conversion',
+        eventName,
+        iso(from),
+        iso(to)
+    ];
+    const text = `SELECT ${q(c.unitId)} AS "unitId", ${q(c.userId)} AS "userId", ${q(c.value)} AS "value", ${epochMs} AS "ts" FROM ${qualifiedTable(exec, TABLES.events)} WHERE ${q(c.type)} = $1 AND ${q(c.eventName)} = $2 AND ${q(c.ts)} >= $3 AND ${q(c.ts)} < $4`;
+    const filterIds = userIds ?? unitIds;
+    const column = userIds === undefined ? c.unitId : c.userId;
+    const ids = filterIds === undefined ? undefined : [
+        ...new Set(filterIds)
+    ];
+    const rows = [];
+    for(let offset = 0; ids === undefined || offset < ids.length; offset += batchSize){
+        const result = await exec.query(`${text}${ids === undefined ? '' : ` AND ${q(column)} = ANY($5::text[])`} ORDER BY ${q(c.ts)}, ${q(c.unitId)}`, ids === undefined ? params : [
+            ...params,
+            ids.slice(offset, offset + batchSize)
+        ]);
+        for (const row of result.rows){
+            rows.push({
+                unitId: row.unitId,
+                userId: row.userId == null ? null : String(row.userId),
+                value: Number(row.value),
+                ts: Number(row.ts)
+            });
+        }
+        if (ids === undefined) break;
+    }
+    return rows;
+}
+/** Linked visitors for creditUserEvents; disjoint ANY batches of ≤ 10,000 IDs. */ export async function identityRows(exec, { anonymousIds }) {
+    const ids = [
+        ...new Set(anonymousIds)
+    ];
+    const i = COLUMNS.identities;
+    const rows = [];
+    for(let offset = 0; offset < ids.length; offset += batchSize){
+        const result = await exec.query(`SELECT ${q(i.anonymousId)} AS "anonymousId", ${q(i.userId)} AS "userId" FROM ${qualifiedTable(exec, TABLES.identities)} WHERE ${q(i.anonymousId)} = ANY($1::text[]) ORDER BY ${q(i.anonymousId)}`, [
+            ids.slice(offset, offset + batchSize)
+        ]);
+        rows.push(...result.rows.map((row)=>({
+                anonymousId: row.anonymousId,
+                userId: String(row.userId)
+            })));
+    }
+    return rows;
+}

package/dist/db/slices.d.ts

@@ -0,0 +1,18 @@
+import type { Executor } from './executor.js';
+import type { DocId } from '../types/contracts.js';
+/** Reclaim exactly the stopped test's slices while holding the layer lock. */
+export declare function reclaimSlices(exec: Executor, { layerId, experimentId, slices }: {
+    layerId: DocId;
+    experimentId: DocId;
+    slices: number[];
+}): Promise<number[]>;
+/** Caller holds the layer lock on this transaction executor. Returns additional
+ * free slices; the caller persists them in layerSlices. Existing slices, even
+ * those of experimentId itself, stay occupied until explicitly freed with [].
+ */
+export declare function claimSlices(exec: Executor, { layerId, experimentId, count, random }: {
+    layerId: DocId;
+    experimentId: DocId;
+    count: number;
+    random?: () => number;
+}): Promise<number[]>;

package/dist/db/slices.js

@@ -0,0 +1,51 @@
+import { COLUMNS, TABLES } from './names.js';
+import { XpRefusal } from '../errors.js';
+import { qualifiedTable, quoteIdentifier as quote } from './sql.js';
+/** Reclaim exactly the stopped test's slices while holding the layer lock. */ export async function reclaimSlices(exec, { layerId, experimentId, slices }) {
+    const c = COLUMNS.experiments;
+    const { rows } = await exec.query(`SELECT ${quote(c.layerSlices)} AS slices FROM ${qualifiedTable(exec, TABLES.experiments)} WHERE ${quote(c.layerId)} = $1 AND ${quote(c.status)} IN ('running', 'decided')`, [
+        layerId
+    ]);
+    const occupied = new Set(rows.flatMap((row)=>row.slices ?? []));
+    if (slices.some((slice)=>occupied.has(slice))) throw new XpRefusal('slices-taken', 'The original layer slices are now in use.', {
+        layerId,
+        experimentId
+    }, 422);
+    return [
+        ...slices
+    ];
+}
+/** Caller holds the layer lock on this transaction executor. Returns additional
+ * free slices; the caller persists them in layerSlices. Existing slices, even
+ * those of experimentId itself, stay occupied until explicitly freed with [].
+ */ export async function claimSlices(exec, { layerId, experimentId, count, random = Math.random }) {
+    if (!Number.isSafeInteger(count) || count < 0) throw new RangeError('Slice count must be a non-negative integer');
+    const table = qualifiedTable(exec, TABLES.experiments);
+    const c = COLUMNS.experiments;
+    const { rows } = await exec.query(`SELECT ${quote(c.layerSlices)} AS slices FROM ${table} WHERE ${quote(c.layerId)} = $1 AND ${quote(c.status)} IN ('running', 'decided')`, [
+        layerId
+    ]);
+    const occupied = new Set(rows.flatMap((row)=>row.slices ?? []));
+    const free = Array.from({
+        length: 100
+    }, (_, slice)=>slice).filter((slice)=>!occupied.has(slice));
+    if (free.length < count) {
+        throw new XpRefusal('layer-full', 'There is not enough room in this layer.', {
+            layerId,
+            experimentId,
+            requested: count,
+            available: free.length
+        }, 409);
+    }
+    // Partial Fisher–Yates: each subset of the requested size is equally likely.
+    for(let i = 0; i < count; i++){
+        const value = random();
+        if (!(value >= 0 && value < 1)) throw new RangeError('Random must return a number in [0, 1)');
+        const j = i + Math.floor(value * (free.length - i));
+        [free[i], free[j]] = [
+            free[j],
+            free[i]
+        ];
+    }
+    return free.slice(0, count).sort((a, b)=>a - b);
+}

package/dist/db/snapshots.d.ts

@@ -0,0 +1,47 @@
+import type { Payload } from 'payload';
+import type { DocId, UnitType } from '../types/contracts.js';
+import type { Snapshot } from '../types/snapshot.js';
+import type { AnalysisPhase, FrozenMetric } from '../results/analyse.js';
+import { type Executor } from './executor.js';
+export interface ResultsPhase extends AnalysisPhase {
+    seed: string;
+    allocation: number;
+    metricDefinitions: Array<FrozenMetric & {
+        source: string;
+        keyedBy?: UnitType;
+        capNotice?: 'no-history';
+    }>;
+}
+export interface ResultsCandidate {
+    phase: ResultsPhase;
+    unitType: UnitType;
+    status: 'running' | 'stopped' | 'decided' | 'archived';
+    latestComputedAt: string | null;
+    testArms: Array<{
+        weight: number;
+    }>;
+    layerSlug: string | null;
+    layerSlices: number[] | null;
+}
+/** Each query gets its own pooled connection and timeout transaction. A failed
+ * metric query cannot poison the next metric's transaction. */
+export declare function resultsExecutor(payload: Payload, timeoutMs: () => number): Executor;
+/** Scheduling and immutable assignment metadata only; metric/config data comes
+ * from the phase JSON, never from live metric or experiment analysis fields. */
+export declare function resultsCandidates(exec: Executor, { cutoff, experimentId }: {
+    cutoff: string;
+    experimentId?: DocId;
+}): Promise<ResultsCandidate[]>;
+export declare function writeSnapshot(exec: Executor, snapshot: Snapshot): Promise<void>;
+/** One atomic insert after all phases complete: a budget failure cannot leave
+ * the experiment with a partially persisted set of phase snapshots. */
+export declare function writeSnapshots(exec: Executor, snapshots: Snapshot[]): Promise<void>;
+/** Fetch pointers only, then the endpoint reads the bounded set through Payload
+ * with req/overrideAccess:false. Called behind the readResults/manage gate. */
+export declare function newestSnapshotIds(exec: Executor, ids: DocId[], per: 'phase' | 'experiment'): Promise<DocId[]>;
+/** Called only behind the endpoint's readResults gate. Experiment collection
+ * reads require manage, so read only the decision pointer needed by results. */
+export declare function resultsMetadata(exec: Executor, id: DocId): Promise<{
+    status: string;
+    snapshotId: DocId | null;
+} | null>;

package/dist/db/snapshots.js

@@ -0,0 +1,89 @@
+import { withStatementTimeout, ResultsBudgetError, RESULTS_TIMEOUT_MARGIN_MS } from './executor.js';
+import { COLUMNS, TABLES } from './names.js';
+import { qualifiedTable, quoteIdentifier as q } from './sql.js';
+/** Each query gets its own pooled connection and timeout transaction. A failed
+ * metric query cannot poison the next metric's transaction. */ export function resultsExecutor(payload, timeoutMs) {
+    const db = payload.db;
+    return Object.assign({
+        query (text, params) {
+            const remaining = Math.floor(timeoutMs());
+            if (remaining <= RESULTS_TIMEOUT_MARGIN_MS) return Promise.reject(new ResultsBudgetError());
+            return withStatementTimeout(db.pool, remaining - RESULTS_TIMEOUT_MARGIN_MS, (exec)=>exec.query(text, params), Date.now() + remaining);
+        }
+    }, {
+        schemaName: db.schemaName
+    });
+}
+// CORE-16 README: allow late beacons for 24 hours after a phase ends, then keep
+// its final snapshot frozen. This is internal scheduling policy, not public API.
+const LATE_BEACON_GRACE_MS = 24 * 60 * 60 * 1000;
+/** Scheduling and immutable assignment metadata only; metric/config data comes
+ * from the phase JSON, never from live metric or experiment analysis fields. */ export async function resultsCandidates(exec, { cutoff, experimentId }) {
+    const p = COLUMNS.phases, e = COLUMNS.experiments, s = COLUMNS.resultsSnapshots, l = COLUMNS.layers;
+    const phases = qualifiedTable(exec, TABLES.phases), snapshots = qualifiedTable(exec, TABLES.resultsSnapshots);
+    const params = [
+        cutoff,
+        LATE_BEACON_GRACE_MS
+    ];
+    if (experimentId !== undefined) params.push(experimentId);
+    const { rows } = await exec.query(`SELECT
+    jsonb_build_object('experiment', p.${q(p.experimentId)}, 'phase', p.${q(p.phase)}, 'phaseKind', p.${q(p.phaseKind)},
+      '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.unitType)} AS "unitType", e.${q(e.status)} AS "status",
+    (SELECT max(s.${q(s.computedAt)}) FROM ${snapshots} s WHERE s.${q(s.experimentId)} = p.${q(p.experimentId)} AND s.${q(s.phase)} = p.${q(p.phase)}) AS "latestComputedAt",
+    (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",
+    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)}
+    WHERE (p.${q(p.endedAt)} IS NULL OR p.${q(p.endedAt)} >= $1)
+    AND NOT EXISTS (SELECT 1 FROM ${snapshots} frozen WHERE frozen.${q(s.experimentId)} = p.${q(p.experimentId)} AND frozen.${q(s.phase)} = p.${q(p.phase)}
+      AND frozen.${q(s.computedAt)} > p.${q(p.endedAt)} + $2 * interval '1 millisecond')${experimentId === undefined ? '' : ` AND p.${q(p.experimentId)} = $3`}
+    ORDER BY "latestComputedAt" NULLS FIRST, p.${q(p.experimentId)}, p.${q(p.phase)}`, params);
+    return rows;
+}
+export async function writeSnapshot(exec, snapshot) {
+    return writeSnapshots(exec, [
+        snapshot
+    ]);
+}
+/** One atomic insert after all phases complete: a budget failure cannot leave
+ * the experiment with a partially persisted set of phase snapshots. */ export async function writeSnapshots(exec, snapshots) {
+    if (!snapshots.length) return;
+    const c = COLUMNS.resultsSnapshots;
+    const params = [];
+    const values = snapshots.map((snapshot)=>{
+        const offset = params.length;
+        params.push(snapshot.experiment, snapshot.phase, snapshot.computedAt, JSON.stringify(snapshot.window), JSON.stringify(snapshot));
+        return `($${offset + 1}, $${offset + 2}, $${offset + 3}, $${offset + 4}::jsonb, $${offset + 5}::jsonb)`;
+    });
+    // §7.8: runResults writes are privileged internal side effects, using pooled SQL.
+    await exec.query(`INSERT INTO ${qualifiedTable(exec, TABLES.resultsSnapshots)} (${q(c.experimentId)}, ${q(c.phase)}, ${q(c.computedAt)}, ${q(c.window)}, ${q(c.snapshot)}) VALUES ${values.join(', ')}`, params);
+}
+/** Fetch pointers only, then the endpoint reads the bounded set through Payload
+ * with req/overrideAccess:false. Called behind the readResults/manage gate. */ export async function newestSnapshotIds(exec, ids, per) {
+    if (!ids.length) return [];
+    const c = COLUMNS.resultsSnapshots;
+    const partition = [
+        c.experimentId,
+        ...per === 'phase' ? [
+            c.phase
+        ] : []
+    ].map(q).join(', ');
+    const params = [];
+    const placeholders = ids.map((id)=>{
+        params.push(id);
+        return `$${params.length}`;
+    });
+    const { rows } = await exec.query(`SELECT DISTINCT ON (${partition}) ${q(c.id)} AS "id" FROM ${qualifiedTable(exec, TABLES.resultsSnapshots)} WHERE ${q(c.experimentId)} IN (${placeholders.join(', ')}) ORDER BY ${partition}, ${q(c.computedAt)} DESC, ${q(c.id)} DESC`, params);
+    return rows.map((row)=>row.id);
+}
+/** Called only behind the endpoint's readResults gate. Experiment collection
+ * reads require manage, so read only the decision pointer needed by results. */ export async function resultsMetadata(exec, id) {
+    const c = COLUMNS.experiments;
+    const { rows } = await exec.query(`SELECT ${q(c.status)} AS "status", ${q(c.decisionSnapshotId)} AS "snapshotId" FROM ${qualifiedTable(exec, TABLES.experiments)} WHERE ${q(c.id)} = $1`, [
+        id
+    ]);
+    return rows[0] ?? null;
+}

package/dist/db/sql.d.ts

@@ -0,0 +1,5 @@
+import type { Executor } from './executor.js';
+/** Quote schema/table/column identifiers; data values still use parameters. */
+export declare const quoteIdentifier: (name: string) => string;
+/** Preserve the schema carried by the request's executor for raw plugin SQL. */
+export declare function qualifiedTable(exec: Executor, name: string): string;

package/dist/db/sql.js

@@ -0,0 +1,5 @@
+/** Quote schema/table/column identifiers; data values still use parameters. */ export const quoteIdentifier = (name)=>`"${name.replaceAll('"', '""')}"`;
+/** Preserve the schema carried by the request's executor for raw plugin SQL. */ export function qualifiedTable(exec, name) {
+    const schemaName = exec.schemaName;
+    return `${schemaName ? `${quoteIdentifier(schemaName)}.` : ''}${quoteIdentifier(name)}`;
+}

package/dist/db/state.d.ts

@@ -0,0 +1,12 @@
+import type { Executor } from './pgExecutor.js';
+import type { Manifest } from '../types/manifest.js';
+/** Always take this lock last: layer → flag point → experiment → state. */
+export declare function bumpRevision(exec: Executor): Promise<number>;
+export declare function writeManifest(exec: Executor, manifest: Manifest): Promise<void>;
+export declare function readState(exec: Executor, options?: {
+    schemaName?: string;
+}): Promise<{
+    revision: number;
+    manifest: Manifest | null;
+    flagDefaults: Manifest['flagDefaults'];
+} | null>;