@sdods/core 0.8.0 → 0.10.0

package/dist/a11y/audit.d.ts

@@ -0,0 +1,88 @@
+import type { Page } from '@playwright/test';
+/**
+ * The axe audit itself, shared by the explicit accessibility steps (`steps/a11y.steps.ts`) and the
+ * end-of-scenario audit every `@a11y` scenario gets (`quality/hooks.ts`).
+ *
+ * It lives outside the step file on purpose. A step file registers its phrases when it is imported,
+ * and a project can switch a whole core library off with `steps.core.exclude: [a11y]` because its
+ * own steps already use those phrases. If the tag hook imported the step file, it would register
+ * those phrases again behind the project's back and bring back the collision it had excluded.
+ */
+/**
+ * Structural subset of axe-core's result types. Declared locally rather than imported from
+ * `axe-core`: that package is a transitive dependency of `@axe-core/playwright`, not a direct
+ * dependency of this one, so importing its types would couple the whole step library's
+ * compilation to a package a consumer may not have installed.
+ */
+export interface A11yViolationNode {
+    target: unknown[];
+    html?: string;
+    failureSummary?: string;
+}
+export interface A11yViolation {
+    id: string;
+    impact?: string | null;
+    help?: string;
+    helpUrl?: string;
+    nodes: A11yViolationNode[];
+}
+export interface A11yResults {
+    violations: A11yViolation[];
+    passes: {
+        id: string;
+    }[];
+    incomplete: {
+        id: string;
+    }[];
+    inapplicable: {
+        id: string;
+    }[];
+    url?: string;
+}
+/** axe impact levels, weakest first. `impact: null` is treated as `minor`. */
+export declare const IMPACT_ORDER: readonly ["minor", "moderate", "serious", "critical"];
+/**
+ * WCAG 2.0/2.1/2.2 level A and AA, and deliberately nothing else. axe's `best-practice` tag set
+ * changes between axe releases, so including it would let the same unchanged page pass one week
+ * and fail the next — a step whose verdict moves on its own teaches teams to ignore it.
+ */
+export declare const WCAG_AA_TAGS: string[];
+/** Rank of an axe impact level; an absent impact ranks as `minor` rather than vanishing. */
+export declare function impactRank(impact: string | null | undefined): number;
+/** Rejects an impact level the feature file invented, instead of silently matching nothing. */
+export declare function parseImpactFloor(level: string): number;
+export declare function violationsAtOrAbove(violations: A11yViolation[], floor: number): A11yViolation[];
+/** Human-readable violation list: rule, impact, help text and the first few offending nodes. */
+export declare function describeViolations(violations: A11yViolation[]): string;
+/**
+ * PROVES the audit actually executed. axe reporting zero violations is indistinguishable from
+ * axe never having run: a nonce'd CSP that blocks the injected source, an `about:blank` page, or
+ * an `include` that matched nothing all produce an empty, green-looking result. If no rule landed
+ * in passes, violations or incomplete, then nothing was examined and the verdict means nothing.
+ */
+export declare function assertAxeChecked(results: A11yResults, where: string): void;
+export interface AxeRunOptions {
+    include?: string | string[];
+    exclude?: string[];
+    tags?: string[];
+    rules?: string[];
+}
+/**
+ * Runs axe through `@axe-core/playwright`, which injects the source with `page.evaluate` rather
+ * than `addScriptTag`. That matters: an app serving a nonce'd CSP blocks an injected `<script>`
+ * silently, and the audit would report zero violations because it never ran.
+ *
+ * The import is lazy so a project that never audits does not need the dependency — a top-level
+ * import would fail the load of every step file that reaches this module.
+ */
+export declare function runAxe(page: Page, opts: AxeRunOptions): Promise<A11yResults>;
+/** The file writer and attacher both audits use; the name and path are the caller's. */
+export declare function writeAndAttachJson(testInfo: {
+    attach(name: string, opts: {
+        path: string;
+        contentType: string;
+    }): Promise<void>;
+}, name: string, file: string, body: unknown): Promise<void>;
+export declare function markPageAudited(scenario: object, url: string): void;
+export declare function wasPageAudited(scenario: object, url: string): boolean;
+//# sourceMappingURL=audit.d.ts.map

package/dist/a11y/audit.js

@@ -0,0 +1,134 @@
+import { writeFileSync } from 'node:fs';
+import { SdodsError } from '../errors.js';
+/** axe impact levels, weakest first. `impact: null` is treated as `minor`. */
+export const IMPACT_ORDER = ['minor', 'moderate', 'serious', 'critical'];
+/**
+ * WCAG 2.0/2.1/2.2 level A and AA, and deliberately nothing else. axe's `best-practice` tag set
+ * changes between axe releases, so including it would let the same unchanged page pass one week
+ * and fail the next — a step whose verdict moves on its own teaches teams to ignore it.
+ */
+export const WCAG_AA_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];
+/* ── pure judges ───────────────────────────────────────────────────────── */
+/** Rank of an axe impact level; an absent impact ranks as `minor` rather than vanishing. */
+export function impactRank(impact) {
+    const i = IMPACT_ORDER.indexOf((impact ?? 'minor'));
+    return i === -1 ? 0 : i;
+}
+/** Rejects an impact level the feature file invented, instead of silently matching nothing. */
+export function parseImpactFloor(level) {
+    const i = IMPACT_ORDER.indexOf(level);
+    if (i === -1)
+        throw new SdodsError('CONFIG_INVALID', `"${level}" is not an axe impact level.`, {
+            hint: `Use one of: ${IMPACT_ORDER.join(', ')}.`,
+        });
+    return i;
+}
+export function violationsAtOrAbove(violations, floor) {
+    return violations.filter((v) => impactRank(v.impact) >= floor);
+}
+/** Human-readable violation list: rule, impact, help text and the first few offending nodes. */
+export function describeViolations(violations) {
+    return violations
+        .map((v) => {
+        const nodes = v.nodes ?? [];
+        const shown = nodes
+            .slice(0, 3)
+            .map((n) => (Array.isArray(n.target) ? n.target.join(' ') : String(n.target)))
+            .join(' | ');
+        const more = nodes.length > 3 ? ` (+${nodes.length - 3} more node(s))` : '';
+        return `${v.id} [${v.impact ?? 'minor'}] ${v.help ?? ''} → ${nodes.length} node(s): ${shown}${more}`;
+    })
+        .join('\n');
+}
+/**
+ * PROVES the audit actually executed. axe reporting zero violations is indistinguishable from
+ * axe never having run: a nonce'd CSP that blocks the injected source, an `about:blank` page, or
+ * an `include` that matched nothing all produce an empty, green-looking result. If no rule landed
+ * in passes, violations or incomplete, then nothing was examined and the verdict means nothing.
+ */
+export function assertAxeChecked(results, where) {
+    const checked = (results.passes?.length ?? 0) +
+        (results.violations?.length ?? 0) +
+        (results.incomplete?.length ?? 0);
+    if (checked === 0)
+        throw new SdodsError('RUN_FAILED', `axe examined nothing ${where}; the audit proves nothing.`, {
+            hint: 'The page may be blank, the scoped selector may match an empty element, or a Content-Security-Policy may have blocked axe from running. Open the attached sdods/a11y JSON to see what axe reported.',
+        });
+}
+/**
+ * Runs axe through `@axe-core/playwright`, which injects the source with `page.evaluate` rather
+ * than `addScriptTag`. That matters: an app serving a nonce'd CSP blocks an injected `<script>`
+ * silently, and the audit would report zero violations because it never ran.
+ *
+ * The import is lazy so a project that never audits does not need the dependency — a top-level
+ * import would fail the load of every step file that reaches this module.
+ */
+export async function runAxe(page, opts) {
+    let AxeBuilder;
+    try {
+        const mod = await import('@axe-core/playwright');
+        // Named export first: the package exports the class as both `AxeBuilder` and `default`, and a
+        // CJS interop path can hand `default` back as the namespace object rather than the class.
+        AxeBuilder = (mod.AxeBuilder ?? mod.default);
+    }
+    catch (cause) {
+        throw new SdodsError('NOT_SUPPORTED', 'Accessibility audits need @axe-core/playwright.', {
+            hint: 'Install it in the project that runs these steps: `npm i -D @axe-core/playwright`.',
+            cause,
+        });
+    }
+    const include = typeof opts.include === 'string' ? [opts.include] : (opts.include ?? []);
+    const builder = new AxeBuilder({ page });
+    for (const sel of include)
+        builder.include(sel);
+    for (const sel of opts.exclude ?? [])
+        builder.exclude(sel);
+    // withTags and withRules are mutually exclusive in axe-core; never set both.
+    if (opts.rules)
+        builder.withRules(opts.rules);
+    else
+        builder.withTags(opts.tags ?? WCAG_AA_TAGS);
+    try {
+        return await builder.analyze();
+    }
+    catch (cause) {
+        // axe raises "unknown rule `x` in options.runOnly" for a rule id that does not exist, and
+        // "No elements found for include in page Context" for a selector that matched nothing. Both
+        // are defects in the step rather than in the page under test, so both are re-raised as such.
+        const message = cause instanceof Error ? cause.message : String(cause);
+        if (/unknown rule/i.test(message))
+            throw new SdodsError('CONFIG_INVALID', `axe rejected the rule id: ${message}`, {
+                hint: 'Check the rule id against https://dequeuniversity.com/rules/axe.',
+                cause,
+            });
+        if (/no elements found for include/i.test(message))
+            throw new SdodsError('RUN_FAILED', `axe found nothing to scan: ${message}`, {
+                hint: `The selector "${include.join(', ')}" matched no element by the time axe ran. Wait for the region to render first, or fix the selector.`,
+                cause,
+            });
+        throw new SdodsError('RUN_FAILED', `axe failed to analyse the page: ${message}`, { cause });
+    }
+}
+/** The file writer and attacher both audits use; the name and path are the caller's. */
+export async function writeAndAttachJson(testInfo, name, file, body) {
+    writeFileSync(file, JSON.stringify(body, null, 2));
+    await testInfo.attach(name, { path: file, contentType: 'application/json' });
+}
+/* ── which URLs a scenario has already audited ─────────────────────────── */
+/**
+ * Whole-page audits an explicit step already ran in this scenario, by URL. The `@a11y` tag audit
+ * skips a URL listed here: the author wrote the step, chose its threshold, and it has already passed
+ * or failed. Scoped (`within …`) and single-rule audits are not recorded, because they did not look
+ * at the whole page. Keyed on the per-test `scenario` object, so nothing leaks between tests.
+ */
+const audited = new WeakMap();
+export function markPageAudited(scenario, url) {
+    let set = audited.get(scenario);
+    if (!set)
+        audited.set(scenario, (set = new Set()));
+    set.add(url);
+}
+export function wasPageAudited(scenario, url) {
+    return audited.get(scenario)?.has(url) ?? false;
+}
+//# sourceMappingURL=audit.js.map

package/dist/api/template.js

@@ -59,7 +59,7 @@ export function renderJson(template, ...scopes) {
         return JSON.parse(text);
     }
     catch (e) {
-        throw new Error(`Body is not valid JSON after rendering templates: ${e.message}\n${text}`);
+        throw new Error(`Body is not valid JSON after rendering templates: ${e.message}\n${text}`, { cause: e });
     }
 }
 //# sourceMappingURL=template.js.map

package/dist/config/defaults.js

@@ -11,6 +11,8 @@ export const FRAMEWORK_DEFAULTS = {
         },
         fullPage: false,
         mask: [],
+        maxDiffPixelRatio: 0.01,
+        baselines: {},
         viewport: { width: 1280, height: 720 },
         onlyOnFailure: false,
     },

package/dist/config/resolve.js

@@ -93,7 +93,7 @@ export function resolveConfig(opts) {
     markAll(envYaml, prov, 'envYaml', 'env');
     // env-level overrides of project sections
     let projectMerged = project;
-    for (const section of ['screenshots', 'heal', 'timeouts', 'perf', 'evidence']) {
+    for (const section of ['screenshots', 'heal', 'timeouts', 'perf', 'a11y', 'evidence']) {
         const patch = envYaml[section];
         if (patch) {
             projectMerged = {

package/dist/data/index.d.ts

@@ -4,4 +4,5 @@ export * from './loaders.js';
 export * from './provider.js';
 export * from './user-pool.js';
 export * from './factories.js';
+export * from './pool-capacity.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/data/index.js

@@ -4,4 +4,5 @@ export * from './loaders.js';
 export * from './provider.js';
 export * from './user-pool.js';
 export * from './factories.js';
+export * from './pool-capacity.js';
 //# sourceMappingURL=index.js.map

package/dist/data/pool-capacity.d.ts

@@ -0,0 +1,58 @@
+import type { BrowserName, Layer, UserPoolConfig } from '@sdods/contracts';
+import type { ResolvedConfig } from '../config/resolve.js';
+import { SdodsError } from '../errors.js';
+export interface PoolDemandOptions {
+    /** Selected layers; `recorded` has no Gherkin and takes no `@user:` lease. */
+    layers: readonly Layer[];
+    /** Selected browsers (each is its own run target for ui/hybrid). */
+    browsers: readonly BrowserName[];
+    /** `--tags`, already normalised. */
+    tags?: string;
+    /** The setup tier's tags: those scenarios run before the targets they gate, not beside them. */
+    setupTags?: string;
+    /** Feature flags the env declares (`env.vars.features`); undefined gates nothing. */
+    flags?: readonly string[];
+    quarantine?: 'run' | 'skip';
+    fullyParallel: boolean;
+    /** Keep a feature, given its path relative to the project root. */
+    includeFeature?: (projectRelativePath: string) => boolean;
+    /** Keep a scenario by name (`--scenario` / `--grep`, matched on the scenario name only). */
+    includeScenario?: (name: string) => boolean;
+    repeatEach?: number;
+    shardTotal?: number;
+}
+/**
+ * For each `@user:<role>`, how many units of work that lease it could run at once: one per
+ * scenario per run target, or one per feature file per target where the file runs serially
+ * (`fullyParallel: false`, `@mode:serial`, `@mode:default`).
+ */
+export declare function poolDemandByRole(project: {
+    root: string;
+}, env: string, o: PoolDemandOptions): Map<string, number>;
+export interface PoolShortfall {
+    role: string;
+    /** Accounts with this role after `env.users.poolSize`. */
+    accounts: number;
+    /** Scenarios (or serial files) with this role that the workers could run at once. */
+    concurrent: number;
+}
+/**
+ * Roles whose exclusive, worker-held leases cannot cover the workers that will ask for them.
+ *
+ * Empty whenever contention cannot starve a worker: `mode: shared` takes no lease,
+ * `leaseScope: scenario` queues instead of starving, and a dataset that is not file-backed has no
+ * count to compare. A role with no account at all is not a capacity problem — it fails at any
+ * worker count, and the lease names the roles that do exist.
+ */
+export declare function checkPoolCapacity(opts: {
+    pool: UserPoolConfig | undefined;
+    accounts: ReadonlyMap<string, number> | undefined;
+    demand: ReadonlyMap<string, number>;
+    workers: number;
+}): PoolShortfall[];
+/** Accounts per role for the resolved env, after `env.users.poolSize`. Undefined if not file-backed. */
+export declare function poolAccountsFor(config: ResolvedConfig): Map<string, number> | undefined;
+/** How the worker count was arrived at, for messages. */
+export declare function describeWorkers(workers: number | undefined): string;
+export declare function poolTooSmallError(config: ResolvedConfig, shortfalls: readonly PoolShortfall[], runtimeWorkers: number | undefined): SdodsError;
+//# sourceMappingURL=pool-capacity.d.ts.map

package/dist/data/pool-capacity.js

@@ -0,0 +1,138 @@
+import { cpus } from 'node:os';
+import { relative } from 'node:path';
+import { combineTagExpr, parseTagExpr, parseTagValue, scenarioSkipReason } from '../config/tags.js';
+import { SdodsError } from '../errors.js';
+import { parseFeatureFile } from '../lint/gherkin.js';
+import { listFeatureFiles } from '../lint/index.js';
+import { poolAccountsByEnv } from '../matrix/index.js';
+import { effectiveWorkers, leaseWaitMs } from './user-pool.js';
+/**
+ * #153: an exclusive lease is held for a worker's whole life, so a role with fewer accounts than
+ * the workers that reach its scenarios starves every other worker. Each one waits `waitMs` and
+ * fails the scenario with USER_POOL_EXHAUSTED, once per scenario, 30s into it. Measured on a real
+ * suite: 55 passed / 335 failed at --workers 4 with one `member` account. This decides that before
+ * any spec is generated.
+ *
+ * It must never cry wolf, so every estimate below errs towards FEWER concurrent leases: a scenario
+ * the tag gate would skip, a filter only approximated here, or a shard's share all count low.
+ */
+/** Playwright's `browserName` for an SDODS browser: what the runtime tag gate compares `@skip:` with. */
+const ENGINE = {
+    chromium: 'chromium',
+    edge: 'chromium',
+    firefox: 'firefox',
+    webkit: 'webkit',
+    'mobile-chrome': 'chromium',
+    'mobile-safari': 'webkit',
+};
+/**
+ * For each `@user:<role>`, how many units of work that lease it could run at once: one per
+ * scenario per run target, or one per feature file per target where the file runs serially
+ * (`fullyParallel: false`, `@mode:serial`, `@mode:default`).
+ */
+export function poolDemandByRole(project, env, o) {
+    const setup = o.setupTags ? parseTagExpr(o.setupTags) : undefined;
+    const layers = o.layers
+        .filter((l) => l !== 'recorded')
+        .map((layer) => ({ layer, expr: parseTagExpr(combineTagExpr(`@${layer}`, o.tags)) }));
+    const units = new Map();
+    for (const file of listFeatureFiles(project.root)) {
+        const rel = relative(project.root, file).replace(/\\/g, '/');
+        if (o.includeFeature && !o.includeFeature(rel))
+            continue;
+        const parsed = parseFeatureFile(file);
+        for (const pickle of parsed.pickles) {
+            const tags = pickle.tags.map((t) => t.name);
+            const role = parseTagValue(tags, 'user');
+            if (!role || setup?.evaluate(tags))
+                continue;
+            if (o.includeScenario && !o.includeScenario(pickle.name))
+                continue;
+            const serial = tags.includes('@mode:serial') ||
+                tags.includes('@mode:default') ||
+                (!o.fullyParallel && !tags.includes('@mode:parallel'));
+            for (const { layer, expr } of layers) {
+                if (!expr.evaluate(tags))
+                    continue;
+                const targets = layer === 'api' ? [undefined] : o.browsers;
+                for (const browser of targets) {
+                    const gate = { env, flags: o.flags, quarantine: o.quarantine };
+                    // The runtime gate sees Playwright's engine name; lint accepts the SDODS name. Skipped
+                    // under either reading counts as skipped, which can only lower the estimate.
+                    if (scenarioSkipReason(tags, gate) ||
+                        (browser &&
+                            (scenarioSkipReason(tags, { ...gate, browser }) ||
+                                scenarioSkipReason(tags, { ...gate, browser: ENGINE[browser] }))))
+                        continue;
+                    const key = `${layer}|${browser ?? ''}|${rel}${serial ? '' : `|${pickle.id}`}`;
+                    let set = units.get(role);
+                    if (!set)
+                        units.set(role, (set = new Set()));
+                    set.add(key);
+                }
+            }
+        }
+    }
+    const out = new Map();
+    for (const [role, set] of units) {
+        let n = set.size * Math.max(1, o.repeatEach ?? 1);
+        // A shard runs some share of the tests; the smallest guaranteed share is the honest estimate.
+        if (o.shardTotal && o.shardTotal > 1)
+            n = Math.floor(n / o.shardTotal);
+        out.set(role, n);
+    }
+    return out;
+}
+/**
+ * Roles whose exclusive, worker-held leases cannot cover the workers that will ask for them.
+ *
+ * Empty whenever contention cannot starve a worker: `mode: shared` takes no lease,
+ * `leaseScope: scenario` queues instead of starving, and a dataset that is not file-backed has no
+ * count to compare. A role with no account at all is not a capacity problem — it fails at any
+ * worker count, and the lease names the roles that do exist.
+ */
+export function checkPoolCapacity(opts) {
+    const { pool, accounts } = opts;
+    if (!pool || pool.mode === 'shared' || pool.leaseScope === 'scenario' || !accounts)
+        return [];
+    const out = [];
+    for (const [role, units] of opts.demand) {
+        const have = accounts.get(role) ?? 0;
+        const concurrent = Math.min(opts.workers, units);
+        if (have > 0 && have < concurrent)
+            out.push({ role, accounts: have, concurrent });
+    }
+    return out.sort((a, b) => a.role.localeCompare(b.role));
+}
+/** Accounts per role for the resolved env, after `env.users.poolSize`. Undefined if not file-backed. */
+export function poolAccountsFor(config) {
+    return poolAccountsByEnv(config.project, {
+        envs: [config.env.name],
+        poolSize: () => config.env.users.poolSize,
+    })?.get(config.env.name);
+}
+/** How the worker count was arrived at, for messages. */
+export function describeWorkers(workers) {
+    return workers !== undefined
+        ? `${workers} worker(s)`
+        : `${effectiveWorkers()} worker(s) (Playwright's default: half of ${cpus().length} cores)`;
+}
+export function poolTooSmallError(config, shortfalls, runtimeWorkers) {
+    const pool = config.project.data.userPool;
+    const lines = shortfalls.map((s) => `role "${s.role}" has ${s.accounts} account(s) but ${s.concurrent} of its scenarios can run at once`);
+    return new SdodsError('USER_POOL_TOO_SMALL', `User pool too small for ${describeWorkers(runtimeWorkers)} in env ${config.env.name}: ${lines.join('; ')}. ` +
+        `Leases are held per worker, so every worker past the account count would wait ` +
+        `${pool ? Math.round(leaseWaitMs(pool) / 1000) : 30}s and fail each of those scenarios with USER_POOL_EXHAUSTED.`, {
+        hint: `Any one of: set data.userPool.leaseScope: scenario to release an account when each ` +
+            `scenario ends (scenarios then queue for it); add accounts with ` +
+            `${shortfalls.map((s) => `role "${s.role}"`).join(', ')} to dataset "${pool?.dataset}"` +
+            `${config.env.users.poolSize ? ` (env.users.poolSize ${config.env.users.poolSize} caps the dataset before roles are split)` : ''}; ` +
+            `set data.userPool.mode: shared if these scenarios do not mutate user-scoped state; ` +
+            `run with --workers ${Math.max(1, Math.min(...shortfalls.map((s) => s.accounts)))}; ` +
+            `or pass --allow-pool-contention to run anyway.`,
+        docsPath: '/docs/guides/test-data-and-user-pools',
+        details: { env: config.env.name, shortfalls },
+        exitCode: 2,
+    });
+}
+//# sourceMappingURL=pool-capacity.js.map

package/dist/data/user-pool.d.ts

@@ -1,3 +1,4 @@
+import type { UserPoolConfig } from '@sdods/contracts';
 import type { ResolvedConfig } from '../config/resolve.js';
 import type { DataProvider, LeaseStore, LeasedUser, UserPool } from './types.js';
 /** O_EXCL lock files with TTL; safe across workers on one machine. */
@@ -14,10 +15,37 @@ export interface UserPoolOptions {
     owner: string;
     store?: LeaseStore;
     waitMs?: number;
+    /** Where waiters take their place in line. Default: `.queue` beside the lease files. */
+    queueDir?: string;
 }
+/** `data.userPool.waitMs` when unset and leases are held per worker. */
+export declare const DEFAULT_LEASE_WAIT_MS = 30000;
+/**
+ * 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 declare function effectiveWorkers(workers?: number): number;
+/** How long a lease request waits for a free account (see `data.userPool.waitMs`). */
+export declare function leaseWaitMs(pool: Pick<UserPoolConfig, 'waitMs' | 'leaseScope' | 'leaseTtlMs'>): number;
+/**
+ * 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 declare function scenarioLeaseClock(pool: UserPoolConfig | undefined, testInfo: {
+    timeout: number;
+    setTimeout(ms: number): void;
+}): {
+    settle(): void;
+};
 /**
  * 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 declare class FileUserPool implements UserPool {
     private readonly config;
@@ -26,11 +54,24 @@ export declare class FileUserPool implements UserPool {
     private readonly log;
     private readonly leased;
     private rows?;
-    private readonly store;
+    private storeInstance?;
+    private readonly leaseDir;
     constructor(config: ResolvedConfig, data: DataProvider, opts: UserPoolOptions);
+    /**
+     * 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.
+     */
+    private get store();
     static ownerFor(config: ResolvedConfig, parallelIndex: number): string;
     private users;
     lease(role: string, _parallelIndex: number): Promise<LeasedUser>;
+    /**
+     * 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.
+     */
+    private queueTicket;
     release(user: LeasedUser): Promise<void>;
     releaseAll(): Promise<void>;
     status(): Promise<{