@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/application/src/suites/run-suite.js

@@ -0,0 +1,367 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { DEVICE_VARIABLE } from "@parity/product-lab/domain/checks";
+import { plainLine, plainOutput } from "@parity/product-lab/domain/features";
+import { judgeSuite, mergeCombinations, planSuite, SuiteConfig } from "@parity/product-lab/domain/suites";
+import { LoadLab } from "../lab/load-lab.js";
+import { OBSERVED_VERSIONS_FILE, OBSERVED_VERSIONS_VARIABLE, ObservedVersionsFile } from "./observed-versions-file.js";
+import { resolutionCombination, sourceCombination } from "./row-combination.js";
+import { HOST_ROUTE_FILE, HOST_ROUTE_VARIABLE, resolvedHostRelease, withHostRoute, writeHostRoute } from "./row-host-route.js";
+import { RUN_TIMINGS_FILE, RUN_TIMINGS_VARIABLE, RunTimingsFile } from "./run-timings-file.js";
+import { StartTogether } from "./start-together.js";
+import { reportedScenarioTime, rowCounts, suiteCounts } from "./suite-metrics.js";
+export class RunSuite {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async plan(request) {
+        const { state, listFeatures, changes } = this.deps;
+        const catalog = LoadLab.declarative(state.lab, "a suite");
+        const lab = state.lab;
+        const config = SuiteConfig.from(catalog.suites(), catalog.modes?.());
+        const suite = request.mode ? config.mode(request.suite) : config.suite(request.suite);
+        let changed;
+        if (suite.affectedOnly) {
+            if (request.changed)
+                changed = { paths: request.changed, source: "the changed paths given" };
+            else if (request.base) {
+                if (!changes)
+                    throw new Error("This runtime has no change source; give the changed paths instead of a base");
+                changed = await changes.changes({ root: lab.root, base: request.base });
+            }
+        }
+        const listing = await listFeatures.execute({ read: true });
+        const selections = await this.selections(request, suite.matrix.length ? suite.matrix.map((row) => row.host) : [undefined], listing.features);
+        const environments = catalog.environmentIds();
+        const cannotStart = Object.fromEntries(environments.map((id) => [id, catalog.declaration(id).problems]).filter(([, problems]) => problems.length).map(([id, problems]) => [id, problems.join("; ")]));
+        const environmentAliases = Object.fromEntries(Object.entries(lab.environmentAliases ?? {}).filter(([, alias]) => !alias.option).map(([id, alias]) => [id, alias.environment]));
+        const devices = suite.matrix.some((row) => row.device) && this.deps.devices ? Object.keys(await this.deps.devices()) : undefined;
+        const plan = planSuite(config, request.suite, {
+            environments,
+            environmentAliases,
+            ...(devices ? { devices } : {}),
+            defaultEnvironment: catalog.defaultEnvironment,
+            cannotStart,
+            hosts: catalog.hostIds(),
+            versionComponents: Object.keys(catalog.versions()?.policy ?? {}),
+            versionSources: [...Object.keys(catalog.versions()?.sources ?? {}), ...Object.keys(catalog.versions()?.npm ?? {})],
+            ...(catalog.versions()?.unsupported ? { unsupportedVersions: catalog.versions().unsupported } : {}),
+            features: listing.features,
+            ...(catalog.scenarioEnvironments ? { scenarioEnvironments: catalog.scenarioEnvironments() } : {}),
+            rowSelection: (row) => selections.get(row.host ?? ""),
+            ...(changed ? { changes: changed } : {}),
+        });
+        if (!request.rows)
+            return plan;
+        const unknown = request.rows.filter((id) => !plan.rows.some((row) => row.id === id));
+        if (unknown.length)
+            throw new Error(`${plan.mode ? "Mode" : "Suite"} ${plan.suite} declares no row ${unknown.join(", ")} (it has ${plan.rows.map((row) => row.id).join(", ") || "none"})`);
+        return { ...plan, rows: plan.rows.filter((row) => request.rows.includes(row.id)) };
+    }
+    async selections(request, hosts, listed) {
+        const { runner, listFeatures, state } = this.deps;
+        const lab = state.lab;
+        const configuration = runner?.configuration(lab.root);
+        const selections = new Map();
+        if (!configuration || !runner?.selection)
+            return selections;
+        const declared = LoadLab.declarative(state.lab, "a suite").featurePatterns()?.length;
+        for (const host of new Set(hosts)) {
+            const key = host ?? "";
+            const env = { ...request.env, ...(host ? { PRODUCT_LAB_HOST: host } : {}) };
+            const selection = await runner.selection({ root: lab.root, configuration, directory: `${lab.root}/.product-lab/suite-selection/${key || "default"}`, env });
+            selections.set(key, {
+                features: declared ? listed : await listFeatures.selected(selection.paths),
+                ...(selection.tags ? { tags: selection.tags } : {}),
+                ...(selection.failFast ? { failFast: true } : {}),
+            });
+        }
+        return selections;
+    }
+    async execute(request) {
+        const { clock, ids, redactor } = this.deps;
+        const startedAt = clock.now();
+        const startedWall = clock.date().getTime();
+        const plan = await this.plan(request);
+        const id = `suite-${plan.suite}-${ids.next().replace(/-/g, "").slice(0, 8)}`;
+        this.deps.evidenceBundles?.begin(request.directory, id);
+        const rows = [];
+        const outcomes = [];
+        const deadline = plan.budgetMs !== undefined ? startedAt + plan.budgetMs : undefined;
+        const lab = this.deps.state.lab;
+        const sourceRevision = plan.rows.some((row) => !row.skip) ? await this.deps.changes?.revision?.({ root: lab.root }).catch(() => undefined) : undefined;
+        const source = sourceCombination(lab.name, sourceRevision);
+        const planned = clock.now() - startedAt;
+        const planMs = Math.round(planned);
+        const workers = Math.min(plan.workers ?? 1, Math.max(1, plan.rows.filter((row) => !row.skip).length));
+        const declared = workers > 1 ? LoadLab.declarative(this.deps.state.lab, "a suite").workers?.() : undefined;
+        if (workers > 1 && !declared)
+            throw new Error(`Mode ${plan.suite} runs ${workers} rows at once, but the lab cannot say how to keep runs apart (defineLab({ workers }))`);
+        if (declared && workers > declared.max)
+            throw new Error(`Mode ${plan.suite} runs ${workers} rows at once; this lab keeps at most ${declared.max} apart (defineLab({ workers: { max } }))`);
+        const results = plan.rows.map(() => undefined);
+        const runOne = async (index, slot, group) => {
+            const row = plan.rows[index];
+            const base = {
+                id: row.id,
+                status: row.skip?.status ?? "failed",
+                tags: row.tags,
+                environment: row.environment,
+                ...(row.host ? { host: row.host } : {}),
+                ...(row.device ? { device: row.device } : {}),
+                candidates: { ...row.candidates },
+                ...(row.skip ? { reason: row.skip.reason } : {}),
+            };
+            if (row.skip) {
+                results[index] = { record: base };
+                return;
+            }
+            if (request.signal?.aborted) {
+                const reason = "interrupted before this row started";
+                results[index] = { record: { ...base, status: "failed", reason }, outcome: { id: row.id, status: "failed", reason } };
+                return;
+            }
+            const began = clock.now();
+            if (deadline !== undefined && began >= deadline) {
+                const reason = `the suite's budget of ${plan.budgetMs} ms was spent before this row started`;
+                results[index] = { record: { ...base, status: "over-budget", reason }, outcome: { id: row.id, status: "over-budget", reason } };
+                return;
+            }
+            const workerEnv = declared ? declared.env({ index: slot, count: workers }) : undefined;
+            const { outcome, record, measured } = await this.runRow(row, request, deadline, base, source, {
+                suiteId: id,
+                source: sourceRevision,
+                ...(workerEnv ? { env: workerEnv } : {}),
+                ...(group ? { start: (run) => group.start(slot, run) } : {}),
+            });
+            const totalMs = clock.now() - began;
+            results[index] = { outcome, record: { ...record, status: outcome.status, ...(outcome.reason ? { reason: outcome.reason } : {}), durationMs: totalMs, timings: { ...measured, totalMs: Math.round(totalMs) } } };
+        };
+        if (workers > 1 && !this.deps.runFeaturesTogether)
+            throw new Error("This runtime cannot start runs together; a mode's workers need it");
+        for (let first = 0; first < plan.rows.length; first += workers) {
+            const wave = plan.rows.slice(first, first + workers).map((_, offset) => first + offset);
+            const group = workers > 1 ? new StartTogether(wave.length, this.deps.runFeaturesTogether) : undefined;
+            await Promise.all(wave.map((index, slot) => runOne(index, slot, group).finally(() => group?.done(slot))));
+        }
+        for (const result of results) {
+            rows.push(result.record);
+            if (result.outcome)
+                outcomes.push(result.outcome);
+        }
+        const verdict = judgeSuite(plan, outcomes);
+        const judged = rows.map((row, index) => {
+            const status = verdict.rows.find((item) => item.id === row.id)?.status ?? row.status;
+            return { ...row, status, counts: rowCounts(plan.rows[index], status, row.run) };
+        });
+        const finishedAt = clock.now();
+        const criticalPathMs = workers > 1 ? Math.round(finishedAt - startedAt) : Math.round(planned + judged.reduce((sum, row) => sum + (row.timings ? (row.durationMs ?? 0) : 0), 0));
+        return redactor.value({
+            id,
+            suite: plan.suite,
+            lab: lab.name,
+            status: verdict.status,
+            reason: verdict.reason,
+            plan,
+            rows: judged,
+            ...(plan.budgetMs !== undefined ? { budgetMs: plan.budgetMs } : {}),
+            counts: suiteCounts(judged),
+            timings: { planMs, criticalPathMs, totalMs: Math.round(finishedAt - startedAt) },
+            startedAt: startedWall,
+            finishedAt: startedWall + (finishedAt - startedAt),
+            directory: request.directory,
+        });
+    }
+    async probe(request) {
+        const plan = await this.plan({ suite: request.suite, rows: [request.row], ...(request.env ? { env: request.env } : {}) });
+        const planned = plan.rows[0];
+        const base = { id: planned.id, status: planned.skip?.status ?? "failed", tags: planned.tags, environment: planned.environment, ...(planned.host ? { host: planned.host } : {}), candidates: { ...request.candidates } };
+        if (planned.skip && planned.skip.status !== "empty")
+            return { ...base, reason: planned.skip.reason };
+        const scenarios = planned.scenarios.filter((scenario) => scenario.feature === request.scenario.uri && scenario.name === request.scenario.name);
+        if (!scenarios.length)
+            return { ...base, status: "unsupported", reason: `row ${planned.id} no longer plans "${request.scenario.name}" (${request.scenario.uri})` };
+        const { skip: _skip, ...runnable } = planned;
+        const row = { ...runnable, candidates: { ...request.candidates }, scenarios };
+        const lab = this.deps.state.lab;
+        const sourceRevision = await this.deps.changes?.revision?.({ root: lab.root }).catch(() => undefined);
+        const run = { suite: request.suite, directory: request.directory, ...(request.env ? { env: request.env } : {}), ...(request.signal ? { signal: request.signal } : {}), ...(request.onOutput ? { onOutput: request.onOutput } : {}) };
+        const { outcome, record } = await this.runRow(row, run, undefined, base, sourceCombination(lab.name, sourceRevision), { suiteId: `probe-${this.deps.ids.next().slice(0, 8)}`, source: sourceRevision }, request.scenario.name);
+        return { ...record, status: outcome.status, ...(outcome.reason ? { reason: outcome.reason } : {}) };
+    }
+    async runRow(row, request, deadline, record, source, execution, 
+    scenarioName) {
+        const { clock, state, files } = this.deps;
+        const directory = `${request.directory.replace(/\/+$/, "")}/${row.id}`;
+        const observed = `${directory}/${OBSERVED_VERSIONS_FILE}`;
+        const timingsFile = `${directory}/${RUN_TIMINGS_FILE}`;
+        const measured = {};
+        const measuredStarts = () => {
+            const starts = files ? RunTimingsFile.read(files, timingsFile) : [];
+            if (starts.length)
+                measured.environmentStarts = starts;
+        };
+        let resolved = {};
+        let routing;
+        let captured;
+        const combined = (entry) => {
+            const combination = mergeCombinations(resolved, source, files ? ObservedVersionsFile.read(files, observed) : {});
+            return { ...entry, combination: routing ? withHostRoute(combination, routing) : combination };
+        };
+        try {
+            const env = { ...request.env, ...execution.env };
+            if (row.host)
+                env.PRODUCT_LAB_HOST = row.host;
+            if (row.device)
+                env[DEVICE_VARIABLE] = row.device;
+            if (files) {
+                files.remove(observed);
+                env[OBSERVED_VERSIONS_VARIABLE] = observed;
+                files.remove(timingsFile);
+                env[RUN_TIMINGS_VARIABLE] = timingsFile;
+                files.remove(`${directory}/${HOST_ROUTE_FILE}`);
+            }
+            const catalog = LoadLab.declarative(state.lab, "a suite");
+            const declared = Object.keys(catalog.versions()?.policy ?? {}).length > 0;
+            if (Object.keys(row.candidates).length || declared) {
+                if (!this.deps.resolveVersions)
+                    throw new Error("This runtime has no versions ports; the row's versions cannot be resolved");
+                const resolving = clock.now();
+                let report;
+                try {
+                    report = await this.deps.resolveVersions({ environment: row.environment, candidates: row.candidates });
+                }
+                finally {
+                    measured.resolveMs = Math.round(clock.now() - resolving);
+                }
+                resolved = resolutionCombination(report.resolution);
+                const kind = row.host ? catalog.hostChecks?.().find((check) => check.id === row.host)?.kind : undefined;
+                const release = kind ? resolvedHostRelease(report.resolution, kind) : undefined;
+                if (release && catalog.routeHostRelease) {
+                    const routeStart = clock.now();
+                    try {
+                        routing = await catalog.routeHostRelease(row.host, { ...release, ...(request.dryRun ? { decideOnly: true } : {}) }, {
+                            log: (line) => request.onOutput?.(`[${row.id}] ${line}\n`),
+                            signal: request.signal ?? new AbortController().signal,
+                            ...this.deps.hostTools,
+                        });
+                    }
+                    finally {
+                        measured.hostRouteMs = Math.round(clock.now() - routeStart);
+                    }
+                    if (routing) {
+                        record = { ...record, hostRoute: { ...routing.route, ...(routing.patchset ? { patchset: routing.patchset } : {}) } };
+                        if (routing.route.route === "unsupported")
+                            return { outcome: { id: row.id, status: "unsupported", reason: routing.route.reason }, record: combined(record), measured };
+                        if (!request.dryRun) {
+                            if (!files)
+                                throw new Error(`The row's host runs ${routing.route.route} ${release.release.tag}, but this runtime cannot hand the route to the run (no file system)`);
+                            env[HOST_ROUTE_VARIABLE] = writeHostRoute(files, `${directory}/${HOST_ROUTE_FILE}`, row.host, routing);
+                        }
+                    }
+                }
+                if (report.manifest) {
+                    env.PRODUCT_LAB_VERSIONS_RESOLUTION = report.manifest;
+                    record = { ...record, versionsManifest: report.manifest };
+                    captured = this.deps.evidenceBundles?.capture(request.directory, execution.suiteId, row.id, report.manifest, report.resolution);
+                }
+            }
+            const running = clock.now();
+            if (plainOutput(env))
+                request.onOutput?.(plainLine(`Row ${row.id}: ${row.scenarios.length} scenario(s) on ${row.environment}${row.host ? `, host ${row.host}` : ""}`));
+            const paths = row.paths?.length ? [...row.paths] : catalog.featurePatterns()?.length ? [...new Set(row.scenarios.map((scenario) => scenario.feature))] : [];
+            const handle = await (execution.start ?? ((run) => this.deps.runFeatures(run)))({
+                tags: row.tags,
+                ...(paths.length ? { paths } : {}),
+                ...(scenarioName ? { name: `^${scenarioName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$` } : {}),
+                environment: row.environment,
+                directory,
+                report: `${directory}/product-lab-test.json`,
+                requireScenarios: true,
+                label: `suite-${row.id}`,
+                ...(request.dryRun ? { dryRun: true } : {}),
+                ...(request.fixtures ? { fixtures: request.fixtures } : {}),
+                ...(Object.keys(env).length ? { env } : {}),
+            });
+            const off = request.onOutput ? handle.onOutput(request.onOutput) : undefined;
+            let stopFailure;
+            const stopRun = (why, options) => {
+                handle.stop(options).catch((error) => {
+                    stopFailure ??= `stopping the run (${why}) failed: ${error instanceof Error ? error.message : String(error)}`;
+                });
+            };
+            const interrupt = () => stopRun("interrupted", { signal: "SIGINT", graceMs: 180_000 });
+            request.signal?.addEventListener("abort", interrupt, { once: true });
+            let overBudget = false;
+            const remaining = deadline !== undefined ? Math.max(0, deadline - clock.now()) : undefined;
+            const budget = new AbortController();
+            if (remaining !== undefined)
+                clock.sleep(remaining, budget.signal).then(() => {
+                    overBudget = true;
+                    stopRun("over budget", { signal: "SIGINT", graceMs: 60_000 });
+                }, 
+                () => undefined);
+            let run;
+            try {
+                run = await handle.completion;
+            }
+            finally {
+                budget.abort();
+                request.signal?.removeEventListener("abort", interrupt);
+                off?.();
+            }
+            measured.runMs = Math.round(clock.now() - running);
+            measuredStarts();
+            const scenariosMs = reportedScenarioTime(run);
+            if (scenariosMs !== undefined)
+                measured.scenariosMs = scenariosMs;
+            const stoppedBy = overBudget ? "not run: the suite's budget ran out during the row" : request.signal?.aborted ? "not run: the suite was interrupted" : undefined;
+            const unreported = unreportedScenarios(row, run, stoppedBy);
+            record = combined({ ...record, run, ...(unreported.length ? { unreported } : {}) });
+            const unexplained = unreported.filter((scenario) => !scenario.reason);
+            const lastError = () => (run.scenarios.length ? undefined : handle.tail(200, "Error: ").lines.at(-1)?.trim());
+            const failure = () => run.error ?? `the feature run ${run.id} ${run.status}${lastError() ? `; its output's last error: ${lastError()}` : ""}`;
+            let unsealed;
+            if (captured && record.versionsManifest && this.deps.evidenceBundles) {
+                const sourceAfter = await this.deps.changes?.revision?.({ root: state.lab.root }).catch(() => undefined);
+                try {
+                    record.execution = this.deps.evidenceBundles.seal(request.directory, {
+                        kind: "product-lab-suite-execution", schemaVersion: 1,
+                        suiteId: execution.suiteId, rowId: row.id, lab: state.lab.name,
+                        environment: row.environment, ...(row.host ? { host: row.host } : {}),
+                        tags: row.tags, candidates: { ...row.candidates }, dryRun: request.dryRun === true,
+                        ...(execution.source ? { source: execution.source } : {}), ...(sourceAfter ? { sourceAfter } : {}),
+                        resolution: captured, run,
+                    }, record.versionsManifest);
+                }
+                catch (error) {
+                    unsealed = `no execution receipt: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
+            const missing = unexplained.length && run.status === "passed"
+                ? `${unexplained.length} planned scenario(s) were not reported by the run: ${unexplained.map((scenario) => `"${scenario.name}" (${scenario.feature})`).join(", ")}`
+                : undefined;
+            const notes = [unsealed, stopFailure, missing].filter((note) => note !== undefined);
+            const noted = notes.length ? ` (${notes.join("; ")})` : "";
+            if (overBudget)
+                return { outcome: { id: row.id, status: "over-budget", reason: `stopped: the suite's budget ran out during this row${noted}` }, record, measured };
+            if (run.status === "passed")
+                return { outcome: notes.length ? { id: row.id, status: "failed", reason: `the run passed, but ${notes.join("; ")}` } : { id: row.id, status: "passed" }, record, measured };
+            return { outcome: { id: row.id, status: "failed", reason: `${failure()}${noted}` }, record, measured };
+        }
+        catch (error) {
+            measuredStarts();
+            return { outcome: { id: row.id, status: "failed", reason: error instanceof Error ? error.message : String(error) }, record: combined(record), measured };
+        }
+    }
+}
+export function unreportedScenarios(row, run, stoppedBy) {
+    const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const reported = (planned) => {
+        const name = new RegExp(`^${escape(planned.name).replace(/<[^>]+>/g, ".*")}$`);
+        return run.scenarios.some((scenario) => scenario.uri === planned.feature && name.test(scenario.name));
+    };
+    const reason = stoppedBy ?? (row.failFast === true && run.scenarios.some((scenario) => scenario.status === "failed") ? "not run: stopped after the first failure" : undefined);
+    return row.scenarios.filter((planned) => !reported(planned)).map((planned) => ({ ...planned, ...(reason ? { reason } : {}) }));
+}

package/core/application/src/suites/run-timings-file.d.ts

@@ -0,0 +1,21 @@
+import type { EnvironmentStartMeasurement } from "@parity/product-lab/ports/lab";
+import type { FileSystem } from "@parity/product-lab/ports/system";
+/** The variable naming the file a run records its environment starts in. */
+export declare const RUN_TIMINGS_VARIABLE = "PRODUCT_LAB_RUN_TIMINGS";
+/** The file's name in a row's directory. */
+export declare const RUN_TIMINGS_FILE = "run-timings.json";
+/** The file's content. */
+export interface RunTimingsData {
+    readonly kind: "product-lab-run-timings";
+    readonly schemaVersion: 1;
+    readonly environmentStarts: readonly EnvironmentStartMeasurement[];
+}
+/** Appends measurements to one file (read, extended and rewritten atomically, 0600), so several runtimes of one run add to the same record. */
+export declare class RunTimingsFile {
+    private readonly files;
+    readonly path: string;
+    constructor(files: FileSystem, path: string);
+    readonly record: (measurement: EnvironmentStartMeasurement) => void;
+    /** What a run recorded in `path`; absent or unsupported-schema files are empty, while read errors propagate. Invalid entries are dropped. */
+    static read(files: FileSystem, path: string): EnvironmentStartMeasurement[];
+}

package/core/application/src/suites/run-timings-file.js

@@ -0,0 +1,39 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const RUN_TIMINGS_VARIABLE = "PRODUCT_LAB_RUN_TIMINGS";
+export const RUN_TIMINGS_FILE = "run-timings.json";
+const STATES = new Set(["cold", "warm", "attached"]);
+function valid(entry) {
+    const item = entry;
+    if (!item || typeof item.environment !== "string" || typeof item.durationMs !== "number" || !Number.isFinite(item.durationMs) || item.durationMs < 0)
+        return false;
+    if (item.endpoints !== undefined && (!item.endpoints || typeof item.endpoints !== "object" || Object.values(item.endpoints).some((url) => typeof url !== "string")))
+        return false;
+    if (item.startup === undefined)
+        return true;
+    return typeof item.startup === "object" && STATES.has(item.startup.state) && (item.startup.detail === undefined || typeof item.startup.detail === "string");
+}
+export class RunTimingsFile {
+    files;
+    path;
+    constructor(files, path) {
+        this.files = files;
+        this.path = path;
+    }
+    record = (measurement) => {
+        const entry = {
+            environment: measurement.environment,
+            durationMs: Math.round(measurement.durationMs),
+            ...(measurement.startup ? { startup: { state: measurement.startup.state, ...(measurement.startup.detail ? { detail: measurement.startup.detail } : {}) } } : {}),
+            ...(measurement.endpoints ? { endpoints: { ...measurement.endpoints } } : {}),
+        };
+        const data = { kind: "product-lab-run-timings", schemaVersion: 1, environmentStarts: [...RunTimingsFile.read(this.files, this.path), entry] };
+        this.files.writePrivateJson(this.path, data);
+    };
+    static read(files, path) {
+        const data = files.readJson(path);
+        if (!data || data.kind !== "product-lab-run-timings" || data.schemaVersion !== 1 || !Array.isArray(data.environmentStarts))
+            return [];
+        return data.environmentStarts.filter(valid).map((item) => structuredClone(item));
+    }
+}

package/core/application/src/suites/run-workers.d.ts

@@ -0,0 +1,19 @@
+import type { FeatureRunHandle, RunFeaturesRequest, RunWorkersRequest, WorkersRunRecord } from "@parity/product-lab/ports/driving";
+import type { Clock, FileSystem, Redactor } from "@parity/product-lab/ports/system";
+import type { LabState } from "../lab/lab-state.js";
+/** The variable naming a worker's place among its peers (`<index>/<count>`), for a lab's own hooks to read. */
+export declare const WORKER_VARIABLE = "PRODUCT_LAB_WORKER";
+/** The parallel run's record in its directory. */
+export declare const WORKERS_RUN_FILE = "product-lab-workers.json";
+export interface RunWorkersDeps {
+    state: LabState;
+    executeTogether(requests: readonly RunFeaturesRequest[]): Promise<FeatureRunHandle[]>;
+    files: FileSystem;
+    clock: Clock;
+    redactor: Redactor;
+}
+export declare class RunWorkers {
+    private readonly deps;
+    constructor(deps: RunWorkersDeps);
+    execute(request: RunWorkersRequest): Promise<WorkersRunRecord>;
+}

package/core/application/src/suites/run-workers.js

@@ -0,0 +1,118 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { planWorkers, sharedWorkerEndpoints, workerEnvProblems, workersOverlapMs } from "@parity/product-lab/domain";
+import { LoadLab } from "../lab/load-lab.js";
+import { RUN_TIMINGS_FILE, RUN_TIMINGS_VARIABLE, RunTimingsFile } from "./run-timings-file.js";
+export const WORKER_VARIABLE = "PRODUCT_LAB_WORKER";
+export const WORKERS_RUN_FILE = "product-lab-workers.json";
+export class RunWorkers {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(request) {
+        const { state, files, clock, redactor } = this.deps;
+        const catalog = LoadLab.declarative(state.lab, "parallel workers");
+        const declared = catalog.workers?.();
+        if (!declared)
+            throw new Error("This lab declares no workers (defineLab({ workers })), so it cannot say how to keep runs apart; --workers is refused");
+        if (!Number.isInteger(request.count) || request.count < 2)
+            throw new Error(`--workers needs a whole number of at least 2, not ${request.count}`);
+        if (request.count > declared.max)
+            throw new Error(`This lab keeps at most ${declared.max} workers apart (defineLab({ workers: { max } })), not ${request.count}`);
+        if (!request.paths.length)
+            throw new Error("--workers needs the feature files to share out: a lab's listing may hold negative controls");
+        const plan = planWorkers(request.paths, request.count);
+        if (plan.length < 2)
+            throw new Error("One feature file cannot be shared out among workers; give at least two");
+        const envs = plan.map((worker) => declared.env({ index: worker.index, count: plan.length }));
+        const problems = workerEnvProblems(envs);
+        if (problems.length)
+            throw new Error(problems.join("; "));
+        const root = request.directory.replace(/\/+$/, "");
+        const directoryOf = (index) => `${root}/worker-${index}`;
+        const timingsOf = (index) => `${directoryOf(index)}/${RUN_TIMINGS_FILE}`;
+        for (const worker of plan)
+            files.remove(timingsOf(worker.index));
+        const startedAt = clock.now();
+        const startedDate = clock.date().getTime();
+        const wall = (at) => new Date(startedDate + (at - startedAt)).toISOString();
+        const handles = await this.deps.executeTogether(plan.map((worker) => ({
+            paths: worker.features,
+            ...(request.tags ? { tags: request.tags } : {}),
+            ...(request.name ? { name: request.name } : {}),
+            ...(request.environment ? { environment: request.environment } : {}),
+            ...(request.configuration ? { configuration: request.configuration } : {}),
+            directory: directoryOf(worker.index),
+            report: `${directoryOf(worker.index)}/product-lab-test.json`,
+            requireScenarios: true,
+            label: `worker-${worker.index}`,
+            ...(request.dryRun ? { dryRun: true } : {}),
+            ...(request.fixtures ? { fixtures: request.fixtures } : {}),
+            env: { ...request.env, ...envs[worker.index], [WORKER_VARIABLE]: `${worker.index}/${plan.length}`, [RUN_TIMINGS_VARIABLE]: timingsOf(worker.index) },
+        })));
+        const offs = request.onOutput ? handles.map((handle, index) => handle.onOutput((text) => request.onOutput(index, text))) : [];
+        const stopFailures = [];
+        const stopAll = () => {
+            for (const [index, handle] of handles.entries())
+                handle.stop({ signal: "SIGINT", graceMs: 180_000 }).catch((error) => {
+                    stopFailures.push(`stopping worker ${index} failed: ${error instanceof Error ? error.message : String(error)}`);
+                });
+        };
+        request.signal?.addEventListener("abort", stopAll, { once: true });
+        if (request.signal?.aborted)
+            stopAll();
+        const ended = [];
+        let records;
+        try {
+            records = await Promise.all(handles.map((handle, index) => handle.completion.then((record) => ((ended[index] = clock.now()), record))));
+        }
+        finally {
+            for (const off of offs)
+                off();
+            request.signal?.removeEventListener("abort", stopAll);
+        }
+        const workers = plan.map((worker, index) => {
+            const record = records[index];
+            const starts = RunTimingsFile.read(files, timingsOf(worker.index));
+            const endpoints = Object.assign({}, ...starts.map((start) => start.endpoints ?? {}));
+            const passed = record.status === "passed";
+            return {
+                index: worker.index,
+                features: worker.features,
+                status: passed ? "passed" : "failed",
+                ...(passed ? {} : { reason: `${record.status}${record.error ? `: ${record.error}` : ""}` }),
+                run: { id: record.id, status: record.status, report: record.report, directory: record.directory, ...(record.error ? { error: record.error } : {}) },
+                startedAt: wall(startedAt),
+                endedAt: wall(ended[index] ?? clock.now()),
+                durationMs: Math.round((ended[index] ?? clock.now()) - startedAt),
+                endpoints,
+            };
+        });
+        const shared = sharedWorkerEndpoints(workers.map((worker) => ({ index: worker.index, endpoints: worker.endpoints })));
+        const overlapMs = Math.round(workersOverlapMs(workers.map((_worker, index) => ({ startedAt, endedAt: ended[index] ?? startedAt }))));
+        const failed = workers.filter((worker) => worker.status === "failed");
+        const reasons = [
+            ...failed.map((worker) => `worker ${worker.index} ${worker.reason}`),
+            ...shared.map((item) => `not isolated: workers ${item.workers.join(" and ")} reached ${item.address}`),
+            ...(request.dryRun ? [] : workers.filter((worker) => !Object.keys(worker.endpoints).length).map((worker) => `worker ${worker.index} recorded no environment start, so its isolation is unknown`)),
+            ...stopFailures,
+        ];
+        const status = reasons.length ? "failed" : "passed";
+        const report = `${root}/${WORKERS_RUN_FILE}`;
+        const result = {
+            kind: "product-lab-workers-run",
+            schemaVersion: 1,
+            status,
+            reason: reasons.join("; ") || `${workers.length} workers passed, each on its own addresses, ${(overlapMs / 1000).toFixed(1)} s at the same time`,
+            workers,
+            overlapMs,
+            sharedEndpoints: shared,
+            directory: root,
+            report,
+        };
+        const redacted = redactor.value(result);
+        files.writePrivateJson(report, redacted);
+        return redacted;
+    }
+}

package/core/application/src/suites/start-together.d.ts

@@ -0,0 +1,15 @@
+import type { FeatureRunHandle, RunFeaturesRequest } from "@parity/product-lab/ports/driving";
+/**
+ * One wave of a mode's workers: each row asks to start its run (`start`) or ends without one (`done`); once every row
+ * has, the runs asked for start together as one group. A refused group fails every row that asked.
+ */
+export declare class StartTogether {
+    private readonly size;
+    private readonly together;
+    private readonly asked;
+    private readonly settled;
+    constructor(size: number, together: (requests: readonly RunFeaturesRequest[]) => Promise<FeatureRunHandle[]>);
+    start(slot: number, request: RunFeaturesRequest): Promise<FeatureRunHandle>;
+    done(slot: number): void;
+    private settle;
+}

package/core/application/src/suites/start-together.js

@@ -0,0 +1,30 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class StartTogether {
+    size;
+    together;
+    asked = new Map();
+    settled = new Set();
+    constructor(size, together) {
+        this.size = size;
+        this.together = together;
+    }
+    start(slot, request) {
+        return new Promise((resolve, reject) => {
+            this.asked.set(slot, { request, resolve, reject });
+            this.settle(slot);
+        });
+    }
+    done(slot) {
+        this.settle(slot);
+    }
+    settle(slot) {
+        if (this.settled.has(slot))
+            return;
+        this.settled.add(slot);
+        if (this.settled.size < this.size || !this.asked.size)
+            return;
+        const asked = [...this.asked.values()];
+        this.together(asked.map((entry) => entry.request)).then((handles) => asked.forEach((entry, index) => entry.resolve(handles[index])), (error) => asked.forEach((entry) => entry.reject(error)));
+    }
+}

package/core/application/src/suites/suite-metrics.d.ts

@@ -0,0 +1,8 @@
+import type { SuitePlanRow, SuiteRowStatus } from "@parity/product-lab/domain/suites";
+import type { FeatureRunRecord, SuiteCounts, SuiteRowRecord, SuiteScenarioCounts } from "@parity/product-lab/ports/driving";
+/** One row's scenario and checkpoint counts: `planned` from the plan, the rest from what its run reported. */
+export declare function rowCounts(row: Pick<SuitePlanRow, "scenarios">, status: SuiteRowStatus, run: FeatureRunRecord | undefined): SuiteScenarioCounts;
+/** The sum of the step and hook durations a run reported; undefined when it reported nothing or any step has no duration. */
+export declare function reportedScenarioTime(run: FeatureRunRecord | undefined): number | undefined;
+/** The suite's counts: rows by (judged) status, and every row's scenario counts added up. */
+export declare function suiteCounts(rows: readonly Pick<SuiteRowRecord, "status" | "counts">[]): SuiteCounts;