@sdods/core 0.8.0 → 0.10.0

package/dist/data/user-pool.js

@@ -1,4 +1,5 @@
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, writeSync, } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync, } from 'node:fs';
+import { cpus } from 'node:os';
 import { join } from 'node:path';
 import { SdodsError } from '../errors.js';
 import { Logger } from '../logger.js';
@@ -82,9 +83,46 @@ export class FileLeaseStore {
         return out;
     }
 }
+/** `data.userPool.waitMs` when unset and leases are held per worker. */
+export const DEFAULT_LEASE_WAIT_MS = 30_000;
+const POLL_MS = 500;
+/** A waiter refreshes its ticket every poll; one untouched this long belongs to a waiter that is gone. */
+const TICKET_STALE_MS = 10_000;
+/**
+ * The worker count Playwright will actually use: `--workers` / `SDODS_WORKERS` when set (both land
+ * in `runtime.workers`), else Playwright's own default of half the logical cores.
+ *
+ * Every browser and layer of one `sdods run` shares this pool: the CLI starts ONE `playwright test`
+ * with a `--project` per run target, and Playwright's `workers` caps the whole invocation.
+ */
+export function effectiveWorkers(workers) {
+    return workers ?? Math.max(1, Math.floor(cpus().length / 2));
+}
+/** How long a lease request waits for a free account (see `data.userPool.waitMs`). */
+export function leaseWaitMs(pool) {
+    if (pool.waitMs !== undefined)
+        return pool.waitMs;
+    return pool.leaseScope === 'scenario' ? pool.leaseTtlMs : DEFAULT_LEASE_WAIT_MS;
+}
+/**
+ * With `leaseScope: scenario`, waiting for an account is how one account serialises the scenarios
+ * that need it, so the wait must not count against the scenario's own timeout: a scenario third in
+ * line would otherwise fail having done nothing. The timeout is raised by the longest possible wait
+ * before leasing, then settled to what was actually waited.
+ */
+export function scenarioLeaseClock(pool, testInfo) {
+    const base = testInfo.timeout;
+    if (pool?.leaseScope !== 'scenario' || pool.mode === 'shared' || base <= 0) {
+        return { settle: () => undefined };
+    }
+    const started = Date.now();
+    testInfo.setTimeout(base + leaseWaitMs(pool));
+    return { settle: () => testInfo.setTimeout(base + (Date.now() - started)) };
+}
 /**
  * Pool of accounts from the configured dataset, partitioned by role and capped by env.users.poolSize.
- * Leases are keyed by owner (`runId:shardOffset+parallelIndex`) and released on worker teardown.
+ * Leases are keyed by owner (`runId:shardOffset+parallelIndex`) and released on worker teardown, or
+ * at scenario teardown with `leaseScope: scenario`.
  */
 export class FileUserPool {
     config;
@@ -93,18 +131,28 @@ export class FileUserPool {
     log = new Logger('pool');
     leased = new Map(); // by role
     rows;
-    store;
+    storeInstance;
+    leaseDir;
     constructor(config, data, opts) {
         this.config = config;
         this.data = data;
         this.opts = opts;
-        this.store =
-            opts.store ??
-                new FileLeaseStore(join(config.runtime.artifactsDir, '..', 'leases', config.project.slug, config.env.name));
+        this.leaseDir = join(config.runtime.artifactsDir, '..', 'leases', config.project.slug, config.env.name);
+        this.storeInstance = opts.store;
+    }
+    /**
+     * Created on first use. Every scenario depends on the pool (the scenario-scope release fixture is
+     * automatic), and a project that never leases must not grow a lease directory for it.
+     */
+    get store() {
+        return (this.storeInstance ??= new FileLeaseStore(this.leaseDir));
     }
     static ownerFor(config, parallelIndex) {
         const shard = config.runtime.shard;
-        const offset = shard ? (shard.current - 1) * (config.runtime.workers ?? 1) : 0;
+        // Shards each number their workers from 0, so the offset must span a whole shard's workers.
+        // It used `workers ?? 1`, which let shard 2's worker 0 share an owner with shard 1's worker 1
+        // whenever --workers was left to Playwright's default.
+        const offset = shard ? (shard.current - 1) * effectiveWorkers(config.runtime.workers) : 0;
         return `${config.runtime.runId}:${offset + parallelIndex}`;
     }
     async users() {
@@ -161,42 +209,122 @@ export class FileUserPool {
             return user;
         }
         const ttl = pool.leaseTtlMs;
-        const waitMs = this.opts.waitMs ?? pool.waitMs;
+        const waitMs = this.opts.waitMs ?? leaseWaitMs(pool);
         const started = Date.now();
-        while (true) {
-            for (const { r, index } of candidates) {
-                const id = String(r.id ?? r.username ?? index);
-                if (await this.store.tryAcquire(id, this.opts.owner, ttl)) {
-                    const user = {
-                        id,
-                        username: String(r.username ?? id),
-                        password: String(r.password ?? ''),
-                        role,
-                        index,
-                        extra: r,
-                        leaseKey: id,
-                        owner: this.opts.owner,
-                    };
-                    this.leased.set(role, user);
-                    this.log.debug(`leased ${user.username} (${role}) for ${this.opts.owner}`);
-                    return user;
+        const ticket = this.queueTicket(role, started);
+        try {
+            while (true) {
+                // First come, first served. Without a queue the worker that just released an account won
+                // it straight back: its next scenario asks within milliseconds while every waiter polls
+                // every 500ms, so under `leaseScope: scenario` the same waiters lost round after round and
+                // failed on the timeout while the account changed hands the whole time.
+                if (ticket.ahead() < candidates.length) {
+                    for (const { r, index } of candidates) {
+                        const id = String(r.id ?? r.username ?? index);
+                        if (await this.store.tryAcquire(id, this.opts.owner, ttl)) {
+                            const user = {
+                                id,
+                                username: String(r.username ?? id),
+                                password: String(r.password ?? ''),
+                                role,
+                                index,
+                                extra: r,
+                                leaseKey: id,
+                                owner: this.opts.owner,
+                            };
+                            this.leased.set(role, user);
+                            this.log.debug(`leased ${user.username} (${role}) for ${this.opts.owner}`);
+                            return user;
+                        }
+                    }
                 }
+                if (Date.now() - started > waitMs) {
+                    const owners = await this.store.owners();
+                    throw new SdodsError('USER_POOL_EXHAUSTED', `All ${candidates.length} user(s) with role "${role}" are leased.`, {
+                        hint: `Owners: ${JSON.stringify(owners)}. Waited ${Math.round(waitMs / 1000)}s. ` +
+                            `Four ways out, in the order worth trying: (1) if these scenarios do not ` +
+                            `mutate user-scoped state, set data.userPool.mode: shared — one account ` +
+                            `then serves every worker, which is what a read-only suite needs; ` +
+                            `(2) add more accounts with role "${role}" to dataset "${pool.dataset}"; ` +
+                            `(3) set data.userPool.leaseScope: scenario, so an account is released when ` +
+                            `each scenario ends rather than when its worker exits, or raise ` +
+                            `data.userPool.waitMs (currently ${waitMs}ms); (4) lower --workers. ` +
+                            `Note env.users.poolSize slices the dataset BEFORE role filtering, so a ` +
+                            `small value can starve a role on its own.`,
+                    });
+                }
+                await new Promise((r) => setTimeout(r, POLL_MS));
+                ticket.touch();
             }
-            if (Date.now() - started > waitMs) {
-                const owners = await this.store.owners();
-                throw new SdodsError('USER_POOL_EXHAUSTED', `All ${candidates.length} user(s) with role "${role}" are leased.`, {
-                    hint: `Owners: ${JSON.stringify(owners)}. Waited ${Math.round(waitMs / 1000)}s. ` +
-                        `Four ways out, in the order worth trying: (1) if these scenarios do not ` +
-                        `mutate user-scoped state, set data.userPool.mode: shared — one account ` +
-                        `then serves every worker, which is what a read-only suite needs; ` +
-                        `(2) add more accounts with role "${role}" to dataset "${pool.dataset}"; ` +
-                        `(3) raise data.userPool.waitMs (currently ${waitMs}ms); (4) lower --workers. ` +
-                        `Note env.users.poolSize slices the dataset BEFORE role filtering, so a ` +
-                        `small value can starve a role on its own.`,
-                });
-            }
-            await new Promise((r) => setTimeout(r, 500));
         }
+        finally {
+            ticket.drop();
+        }
+    }
+    /**
+     * A place in line for `role`: an empty file named by arrival time and owner, refreshed while its
+     * waiter polls. `ahead()` counts live tickets that arrived earlier, and a waiter only tries to
+     * acquire while fewer are ahead of it than the role has accounts. A ticket nobody refreshes (its
+     * worker crashed) goes stale and stops holding the line.
+     */
+    queueTicket(role, arrivedAt) {
+        const dir = join(this.opts.queueDir ?? join(this.leaseDir, '.queue'), encodeURIComponent(role));
+        const name = `${String(arrivedAt).padStart(15, '0')}-${encodeURIComponent(this.opts.owner)}`;
+        const file = join(dir, name);
+        const write = () => {
+            try {
+                mkdirSync(dir, { recursive: true });
+                writeFileSync(file, '');
+            }
+            catch {
+                /* a queue that cannot be written degrades to unordered polling */
+            }
+        };
+        write();
+        return {
+            ahead: () => {
+                let names;
+                try {
+                    names = readdirSync(dir);
+                }
+                catch {
+                    return 0;
+                }
+                let ahead = 0;
+                for (const other of names) {
+                    if (other >= name)
+                        continue;
+                    try {
+                        if (Date.now() - statSync(join(dir, other)).mtimeMs > TICKET_STALE_MS) {
+                            unlinkSync(join(dir, other));
+                            continue;
+                        }
+                    }
+                    catch {
+                        continue; // dropped by its owner between readdir and stat
+                    }
+                    ahead++;
+                }
+                return ahead;
+            },
+            touch: () => {
+                try {
+                    const now = new Date();
+                    utimesSync(file, now, now);
+                }
+                catch {
+                    write(); // removed as stale while this worker was blocked: back in, same place
+                }
+            },
+            drop: () => {
+                try {
+                    unlinkSync(file);
+                }
+                catch {
+                    /* already gone */
+                }
+            },
+        };
     }
     async release(user) {
         // A shared user holds no lease (leaseKey is empty). Releasing it would be at
@@ -206,7 +334,9 @@ export class FileUserPool {
         this.leased.delete(user.role);
     }
     async releaseAll() {
-        await this.store.releaseAll(this.opts.owner);
+        // A store that was never created holds nothing to release.
+        if (this.storeInstance)
+            await this.storeInstance.releaseAll(this.opts.owner);
         this.leased.clear();
     }
     async status() {

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 /** Structured errors: every CLI/MCP/server surface renders `{ code, message, hint, docsUrl }`. */
-export type SdodsErrorCode = 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_SECRET_LITERAL' | 'CONFIG_UNRESOLVED_VAR' | 'PROJECT_NOT_FOUND' | 'ENV_NOT_FOUND' | 'DATASET_NOT_FOUND' | 'DATASET_ROW_NOT_FOUND' | 'USER_POOL_EXHAUSTED' | 'HEAL_FAILED' | 'LINT_FAILED' | 'RUN_FAILED' | 'HAR_MISS' | 'DB_REQUIRED' | 'MAIL_REQUIRED' | 'MAIL_NOT_RECEIVED' | 'AUTH_FAILED' | 'NOT_SUPPORTED' | 'INTERNAL';
+export type SdodsErrorCode = 'CONFIG_INVALID' | 'CONFIG_NOT_FOUND' | 'CONFIG_SECRET_LITERAL' | 'CONFIG_UNRESOLVED_VAR' | 'PROJECT_NOT_FOUND' | 'ENV_NOT_FOUND' | 'DATASET_NOT_FOUND' | 'DATASET_ROW_NOT_FOUND' | 'USER_POOL_EXHAUSTED' | 'USER_POOL_TOO_SMALL' | 'HEAL_FAILED' | 'LINT_FAILED' | 'RUN_FAILED' | 'GATE_FAILED' | 'HAR_MISS' | 'DB_REQUIRED' | 'MAIL_REQUIRED' | 'MAIL_NOT_RECEIVED' | 'AUTH_FAILED' | 'NOT_SUPPORTED' | 'INTERNAL';
 export declare const DOCS_BASE_URL = "https://docs.sdods.com";
 export interface SdodsErrorOptions {
     hint?: string;

package/dist/fixtures/auth.js

@@ -233,7 +233,7 @@ export class AuthStateCache {
             catch (e) {
                 if (e.code !== 'EEXIST')
                     throw e;
-                let stale = false;
+                let stale;
                 try {
                     stale = Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS;
                 }

package/dist/fixtures/scenario.d.ts

@@ -17,9 +17,20 @@ export interface ScenarioInit {
 export declare class ScenarioMeta {
     readonly data: ScenarioMetaDto;
     readonly dir: string;
+    /** the run directory the scenario directory lives in */
+    readonly runDir: string;
+    /** root of the SDODS project (`projects/<slug>`) */
+    readonly projectRoot: string;
     readonly suiteTag?: string;
     constructor(init: ScenarioInit);
+    /**
+     * The first failure an after-scenario hook (`@a11y`, `@perf`) raised. Playwright marks the test
+     * failed only once every after-hook has returned, so `sdods:finalize` would otherwise record a
+     * scenario those hooks failed as passed.
+     */
+    hookFailure?: string;
     get fingerprint(): string;
+    noteFailure(message: string): void;
     file(rel: string): string;
     appendJsonl(rel: string, obj: unknown): void;
     write(): void;

package/dist/fixtures/scenario.js

@@ -7,6 +7,10 @@ import { moduleForFeature } from '../config/workspace.js';
 export class ScenarioMeta {
     data;
     dir;
+    /** the run directory the scenario directory lives in */
+    runDir;
+    /** root of the SDODS project (`projects/<slug>`) */
+    projectRoot;
     suiteTag;
     constructor(init) {
         const { config, testInfo, tags } = init;
@@ -21,6 +25,8 @@ export class ScenarioMeta {
             exampleIndex: null,
             layer,
         });
+        this.runDir = config.runtime.runDir;
+        this.projectRoot = config.project.root;
         this.dir = join(config.runtime.runDir, config.project.slug, fp, `r${testInfo.retry}`);
         this.suiteTag = suiteOfTags(tags, config.project.tags.suites.map((s) => `@${s}`));
         this.data = {
@@ -48,9 +54,18 @@ export class ScenarioMeta {
         mkdirSync(this.dir, { recursive: true });
         this.write();
     }
+    /**
+     * The first failure an after-scenario hook (`@a11y`, `@perf`) raised. Playwright marks the test
+     * failed only once every after-hook has returned, so `sdods:finalize` would otherwise record a
+     * scenario those hooks failed as passed.
+     */
+    hookFailure;
     get fingerprint() {
         return this.data.fingerprint;
     }
+    noteFailure(message) {
+        this.hookFailure ??= message;
+    }
     file(rel) {
         const f = join(this.dir, rel);
         const parent = join(f, '..');

package/dist/fixtures/test.js

@@ -6,7 +6,7 @@ import { applyEmulation, emulationFromTags } from '../config/emulation.js';
 import { noopAuth } from '../auth/index.js';
 import { ApiClient, isolatedRequestFactory } from '../api/client.js';
 import { CompositeDataProvider } from '../data/provider.js';
-import { FileUserPool } from '../data/user-pool.js';
+import { FileUserPool, scenarioLeaseClock } from '../data/user-pool.js';
 import { apiHarForScenario } from '../har/hooks.js';
 import { Healer } from '../heal/healer.js';
 import { HealHistory } from '../heal/history.js';
@@ -188,11 +188,32 @@ export const test = base.extend({
     // `$sdodsTagGate` first, and it is not unused: it is here to force the ordering.
     // Leasing an account for a scenario that the tag gate is about to skip burns a
     // pool slot, and on a role with no rows it throws before the skip can happen.
-    user: async ({ $sdodsTagGate, userPool, $tags }, use, testInfo) => {
+    user: async ({ $sdodsTagGate, userPool, config, $tags }, use, testInfo) => {
         void $sdodsTagGate;
         const role = parseTagValue($tags, 'user');
-        await use(role ? await userPool.lease(role, testInfo.parallelIndex) : undefined);
+        if (!role)
+            return use(undefined);
+        const clock = scenarioLeaseClock(config.project.data.userPool, testInfo);
+        const leased = await userPool.lease(role, testInfo.parallelIndex);
+        clock.settle();
+        await use(leased);
     },
+    /**
+     * `data.userPool.leaseScope: scenario` (#153): hand back every account this worker leased once
+     * the scenario is over — the `@user:` lease above and the `I use a leased user …` steps alike.
+     * A worker runs one scenario at a time, so what it holds at teardown is exactly this scenario's.
+     *
+     * Automatic and dependent only on worker fixtures, so it is set up before and torn down after
+     * everything that could still be signed in as the account (page, context, storageState).
+     */
+    $sdodsScenarioLeases: [
+        async ({ config, userPool }, use) => {
+            await use();
+            if (config.project.data.userPool?.leaseScope === 'scenario')
+                await userPool.releaseAll();
+        },
+        { auto: true },
+    ],
     storageState: async ({ user, authCache, auth, sdods, browser, config }, use) => {
         if (!user || sdods.layer === 'api' || !config.project.auth.storageState)
             return use(undefined);

package/dist/fixtures/types.d.ts

@@ -49,6 +49,8 @@ export interface TestFixtures {
     $sdodsAnnotations: void;
     /** auto fixture: applies @env:, @skip:<browser>, @quarantine and @flag: */
     $sdodsTagGate: void;
+    /** auto fixture: releases the scenario's pool leases when `leaseScope: scenario` */
+    $sdodsScenarioLeases: void;
     /** What the scenario's @locale: @timezone: @theme: @viewport: @device: tags ask for. */
     $sdodsEmulation: Emulation;
 }

package/dist/har/api-har.js

@@ -119,7 +119,7 @@ export function snapshotToEntry(snap) {
 }
 export function entryToResponse(entry) {
     const text = entry.response.content.text ?? '';
-    let body = text;
+    let body;
     try {
         body = text.length ? JSON.parse(text) : null;
     }

package/dist/index.d.ts

@@ -18,4 +18,5 @@ export type { TestFixtures, WorkerFixtures, SdodsOption } from './fixtures/types
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './steps/glob.js';
 export { VERSION } from './version.js';
 export * from './matrix/index.js';
+export * from './quality/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -17,4 +17,5 @@ export { HeaderMap } from './fixtures/api-context.js';
 export { coreStepsGlob, coreStepsPatterns, coreStepNames, coreStepsDir } from './steps/glob.js';
 export { VERSION } from './version.js';
 export * from './matrix/index.js';
+export * from './quality/index.js';
 //# sourceMappingURL=index.js.map

package/dist/matrix/index.d.ts

@@ -101,4 +101,17 @@ export declare function checkMatrixRoles(project: ProjectConfig & {
 export declare function poolRolesByEnv(project: ProjectConfig & {
     root: string;
 }): Map<string, Set<string>> | undefined;
+/**
+ * Accounts per role in the user-pool dataset, per available environment. Undefined if not
+ * file-backed (a db or openapi dataset is not knowable without connecting).
+ *
+ * `poolSize` is the env's `users.poolSize`, applied as the lease applies it: the dataset is sliced
+ * BEFORE rows are split by role, so a small value can leave a role with no account at all.
+ */
+export declare function poolAccountsByEnv(project: ProjectConfig & {
+    root: string;
+}, opts?: {
+    envs?: readonly string[];
+    poolSize?: (env: string) => number | undefined;
+}): Map<string, Map<string, number>> | undefined;
 //# sourceMappingURL=index.d.ts.map

package/dist/matrix/index.js

@@ -451,21 +451,34 @@ export function checkMatrixRoles(project, matrices) {
 }
 /** Roles present in the user-pool dataset, per available environment. Undefined if not file-backed. */
 export function poolRolesByEnv(project) {
+    const counts = poolAccountsByEnv(project);
+    if (!counts)
+        return undefined;
+    return new Map([...counts].map(([env, roles]) => [env, new Set(roles.keys())]));
+}
+/**
+ * Accounts per role in the user-pool dataset, per available environment. Undefined if not
+ * file-backed (a db or openapi dataset is not knowable without connecting).
+ *
+ * `poolSize` is the env's `users.poolSize`, applied as the lease applies it: the dataset is sliced
+ * BEFORE rows are split by role, so a small value can leave a role with no account at all.
+ */
+export function poolAccountsByEnv(project, opts = {}) {
     const pool = project.data.userPool;
     const spec = pool ? project.data.sources[pool.dataset] : undefined;
     if (!pool || !spec || !('path' in spec))
         return undefined;
     const out = new Map();
-    for (const env of project.envs.available) {
+    for (const env of opts.envs ?? project.envs.available) {
         let file;
         try {
             file = resolveDataPath(project.root, spec, env);
         }
         catch {
-            out.set(env, new Set());
+            out.set(env, new Map());
             continue;
         }
-        let rows = [];
+        let rows;
         try {
             const text = readFileSync(file, 'utf8');
             if (spec.type === 'csv')
@@ -478,8 +491,16 @@ export function poolRolesByEnv(project) {
         catch {
             rows = [];
         }
+        const size = opts.poolSize?.(env);
+        if (size)
+            rows = rows.slice(0, size);
+        const roles = new Map();
         // Same fallback as the lease: a row without a role column is a "standard" account.
-        out.set(env, new Set(rows.map((r) => String(r[pool.roleColumn] ?? 'standard'))));
+        for (const r of rows) {
+            const role = String(r[pool.roleColumn] ?? 'standard');
+            roles.set(role, (roles.get(role) ?? 0) + 1);
+        }
+        out.set(env, roles);
     }
     return out;
 }

package/dist/perf/vitals.d.ts

@@ -0,0 +1,118 @@
+import type { PerformanceMetrics } from '@sdods/contracts';
+/**
+ * Page vitals, latency percentiles and the budgets they are judged against, shared by the explicit
+ * perf steps (`steps/perf.steps.ts`) and the end-of-scenario check every `@perf` scenario gets
+ * (`quality/hooks.ts`). Outside the step file for the reason `a11y/audit.ts` gives: importing a step
+ * file registers its phrases, and `steps.core.exclude: [perf]` must stay able to switch them off.
+ * The rules these functions keep are written up at the top of `steps/perf.steps.ts`.
+ */
+/** The page vitals SDODS records. Each name is also its key in `perf.budgets`. */
+export declare const VITAL_KEYS: readonly ["pageLoadMs", "lcpMs", "fcpMs", "ttfbMs"];
+export type VitalKey = (typeof VITAL_KEYS)[number];
+/** The `perf.budgets` key a sampled API latency distribution is judged against. */
+export declare const API_P95_BUDGET_KEY = "apiP95Ms";
+type BudgetLayer = {
+    budgets?: Record<string, number | undefined>;
+} | undefined;
+/** The slice of a resolved config these steps read. Nothing here writes config. */
+export interface BudgetConfig {
+    project: {
+        perf?: BudgetLayer;
+    };
+    env: {
+        name?: string;
+        perf?: BudgetLayer;
+    };
+}
+/**
+ * Effective budgets, env overriding project per key.
+ *
+ * `resolveConfig` already deep-merges `env.perf` into `config.project.perf`, so on a resolved
+ * config the project side is the whole answer. Merging the env side again is idempotent and keeps
+ * this correct for a config assembled by hand. Non-numeric values are dropped rather than spread —
+ * an explicit `undefined` in the env layer would otherwise erase a real project budget and turn a
+ * configured assertion into an unconfigured one.
+ */
+export declare function resolvedBudgets(config: BudgetConfig): Record<string, number>;
+/**
+ * The configured budget for one key, or a hard error naming it.
+ *
+ * PROVES the assertion that follows is gated on something real. A missing budget must never
+ * degrade to a skip or to `Infinity`: an unconfigured budget is the single failure mode that lets
+ * an entire perf suite report success while asserting nothing at all.
+ */
+export declare function requireBudget(config: BudgetConfig, key: string): number;
+export declare function requireVitalKey(name: string): VitalKey;
+/** One `When I record the page vitals`. `null` in `vitals` means NOT MEASURED, never "0 ms". */
+export interface VitalsRecording {
+    url: string;
+    vitals: Record<VitalKey, number | null>;
+    /** Why a vital is null, keyed by vital. Surfaced verbatim in the failure message. */
+    unmeasured: Partial<Record<VitalKey, string>>;
+    /** The contract shape written to `sdods/perf/<step>` and ingested into `steps.perf_json`. */
+    metrics: PerformanceMetrics;
+}
+export interface LatencySample {
+    status: number;
+    ms: number;
+}
+export interface LatencySampleSet {
+    method: string;
+    path: string;
+    samples: LatencySample[];
+    p95Ms: number;
+}
+interface PerfStore {
+    recordings: VitalsRecording[];
+    sampleSets: LatencySampleSet[];
+}
+export declare function perfStore(key: object): PerfStore;
+export declare function lastRecording(key: object): VitalsRecording;
+export declare function lastSampleSet(key: object): LatencySampleSet;
+/**
+ * Nearest-rank p95 — deterministic for a given set of samples, with no interpolation to argue
+ * about. Below 20 samples the nearest rank IS the maximum; the sample count travels in the
+ * attachment and in every failure message so a reader can see when "p95" means "slowest of five".
+ *
+ * Throws rather than returning 0 on an empty sample: a p95 of 0 slides under every budget.
+ */
+export declare function p95Of(msValues: readonly number[]): number;
+/**
+ * How long the LCP observer is given to settle. LCP arrives as a stream of ever-larger candidates;
+ * `buffered: true` replays the ones already emitted and this window catches any still in flight.
+ * A fixed constant rather than a computed wait, so two runs of one scenario observe the same
+ * window and a baseline stays comparable.
+ */
+export declare const LCP_SETTLE_MS = 500;
+/** Bounded wait for the load event before reading `loadEventEnd`. */
+export declare const LOAD_WAIT_MS = 5000;
+/** What the page hands back. Every timing is `number | null`; null always means "did not fire". */
+export interface RawVitals {
+    hasNavigationEntry: boolean;
+    navigationStartEpochMs: number | null;
+    pageLoadMs: number | null;
+    ttfbMs: number | null;
+    fcpMs: number | null;
+    lcpMs: number | null;
+    domContentLoadedMs: number | null;
+    totalResources: number;
+    totalResourceSizeKB: number;
+    lcpSupported: boolean;
+    fcpSupported: boolean;
+}
+/**
+ * Runs inside the page. Serialised by Playwright, so it closes over nothing but its argument — the
+ * type aliases above are erased at compile time and are safe to reference; the constants are not,
+ * which is why the settle window is passed in.
+ */
+export declare function collectRawVitals(settleMs: number): Promise<RawVitals>;
+/**
+ * Turns the page's answer into a recording, capturing WHY a vital is null while the browser's
+ * capabilities are still in hand. By the time a `Then` step fails, "lcpMs was not measured" on its
+ * own sends the reader hunting for a bug in a page that is merely running in a browser that does
+ * not implement LCP (WebKit). Support is read from `PerformanceObserver.supportedEntryTypes`, never
+ * assumed from the browser name.
+ */
+export declare function toRecording(raw: RawVitals, url: string, browserName?: string): VitalsRecording;
+export {};
+//# sourceMappingURL=vitals.d.ts.map