@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/application/src/runs/bundles/bundle-recording.js

@@ -0,0 +1,288 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { RUN_BUNDLE_EXTENSION, RUN_BUNDLE_KIND, RUN_BUNDLE_SCHEMA_VERSION, RUN_STARTS_KEPT, RunBundle, TEST_KEYS_NOTICE, bundleReproducibility, bundleVerdict, failureMarker, } from "@parity/product-lab/domain";
+import { RECORDING_SCHEMA_VERSION, RecordingNotFoundError } from "@parity/product-lab/domain/recordings";
+import { RestoreFixture } from "../../fixtures/restore-fixture.js";
+import { childrenOf, insideRoot, joinPath, parentOf } from "./bundle-paths.js";
+import { rebuiltFromVersions } from "./start-state.js";
+const MIN_SECRET = 8;
+function walk(files, directory, prefix = "") {
+    const found = [];
+    for (const name of [...(childrenOf(files, joinPath(directory, prefix)) ?? [])].sort()) {
+        const path = prefix ? `${prefix}/${name}` : name;
+        if (childrenOf(files, joinPath(directory, path)) !== undefined)
+            found.push(...walk(files, directory, path));
+        else
+            found.push(path);
+    }
+    return found;
+}
+const REPLAY_HERE = "Replay works here.";
+export class BundleRecording {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async reproducibility(id) {
+        const lab = this.deps.state.lab;
+        if (!lab)
+            throw new Error("No lab is loaded: load the lab whose recording to check");
+        const target = this.deps.stores.current();
+        if ("disabled" in target)
+            throw new RecordingNotFoundError(target.disabled);
+        const recording = await target.store.read(id);
+        if (!recording)
+            throw new RecordingNotFoundError(`No recording ${id}`);
+        const data = recording.data;
+        const where = data.environment.label || data.environment.id;
+        const not = (says, reasons, forward = REPLAY_HERE, more = {}) => ({ recording: id, available: false, says, forward, reasons, ...more });
+        if (data.kind !== "feature" || !data.feature)
+            return not("Only a feature scenario's run can be rebuilt elsewhere, and this one is not.", ["it names no feature file"]);
+        const feature = insideRoot(lab.root, data.feature.uri);
+        if (!feature || !this.deps.files?.exists(joinPath(lab.root, feature)))
+            return not(`Its feature file ${data.feature.uri} is not in this lab any more.`, [`${data.feature.uri} is not a file in the lab (${lab.root})`]);
+        const environment = this.environmentFacts(lab, data);
+        const preOnboarded = this.preOnboarded(lab, data);
+        const secretBacked = data.actors.filter((actor) => preOnboarded.has(actor.name)).map((actor) => actor.name);
+        const fixture = data.feature.fixture;
+        let record;
+        try {
+            record = fixture && fixture.action !== "shared" && this.deps.fixtures ? RestoreFixture.read(this.deps.fixtures, fixture.name) : undefined;
+        }
+        catch (error) {
+            return not(`It started from fixture ${fixture.name}, whose saved record here cannot be read.`, [error instanceof Error ? error.message : String(error)]);
+        }
+        const fixtureSecrets = record ? record.identities.filter((identity) => preOnboarded.has(identity.name)).map((identity) => identity.name) : [];
+        const keys = [...new Set([...secretBacked, ...fixtureSecrets])];
+        const keysSaid = keys.length ? ` ${keys.join(" and ")} sign${keys.length === 1 ? "s" : ""} with keys from your lab's secrets, which a bundle never holds.` : "";
+        const keysReasons = keys.map((name) => `identity ${name}'s key comes from a lab secret`);
+        if (environment.public)
+            return not(`It ran on ${where}, a public network, which keeps what runs wrote.${keysSaid}`, ["the run was on a public network", ...keysReasons]);
+        if (fixture) {
+            if (fixture.action === "shared")
+                return not(`It started from fixture ${fixture.name} after an earlier scenario of its group had changed it.${keysSaid}`, [`fixture ${fixture.name} was restored for an earlier scenario of its @fixture-shared group`, ...keysReasons]);
+            if (!record && fixture.action === "run-start")
+                return not(`Its starting state on ${where} was kept as ${fixture.name}, which has been removed since: the lab keeps the last ${RUN_STARTS_KEPT}.${keysSaid}`, [`its starting state was kept as ${fixture.name}, which has been removed since (the lab keeps the last ${RUN_STARTS_KEPT})`, ...keysReasons]);
+            if (!record || !this.deps.exportFixture)
+                return not(`It started from fixture ${fixture.name}, which is not saved here any more.${keysSaid}`, [`fixture ${fixture.name} is not saved here any more`, ...keysReasons]);
+            if (keys.length)
+                return not(`It started from fixture ${fixture.name}.${keysSaid}`, keysReasons);
+            const from = fixture.action === "run-start" ? `Its starting state on ${where} was kept as ${fixture.name}` : `It started from fixture ${fixture.name}`;
+            return { recording: id, available: true, says: `${from}, which a bundle holds: the run can be rebuilt here or on another machine.`, forward: "Reproduce rebuilds it and runs the scenario again.", reasons: [] };
+        }
+        const rebuilt = rebuiltFromVersions(environment);
+        const offWhen = `"Keep each fork run's starting state" was off when it started`;
+        if (!rebuilt && data.feature.startNotKept)
+            return not(`It started on ${where}, whose starting state was not kept: “Keep each fork run's starting state” was off.${keysSaid}`, [`${environment.stateText ?? "its state"} was not kept: ${offWhen}`, ...keysReasons], "Replay works here; with the setting on, the next run can be reproduced.", { startNotKept: true });
+        if (!rebuilt)
+            return not(`It started on ${where}, whose starting state was not saved with it.${keysSaid}`, [`${environment.stateText ?? "its state"} (${environment.retention ?? "unknown"} retention) was not saved as a fixture`, ...keysReasons]);
+        if (keys.length)
+            return not(`It started on ${where}, rebuilt from its versions alone.${keysSaid}`, keysReasons);
+        return { recording: id, available: true, says: `It started on ${where}, which is rebuilt from its versions alone: the run can be rebuilt here or on another machine.`, forward: "Reproduce rebuilds it and runs the scenario again.", reasons: [] };
+    }
+    async execute(request) {
+        const started = this.deps.clock.now();
+        const { files, ports } = this.deps;
+        if (!files || !ports)
+            throw new Error("This runtime writes no run bundles (it was built without the run bundle archive)");
+        const lab = this.deps.state.lab;
+        if (!lab)
+            throw new Error("No lab is loaded: load the lab whose recording to bundle");
+        const target = this.deps.stores.current();
+        if ("disabled" in target)
+            throw new RecordingNotFoundError(target.disabled);
+        const recording = await target.store.read(request.recording);
+        if (!recording)
+            throw new RecordingNotFoundError(`No recording ${request.recording}`);
+        const data = recording.data;
+        if (data.kind !== "feature" || !data.feature)
+            throw new Error(`Recording ${data.id} is not a feature scenario recorded since 3 October 2026 (it names no feature file), so nothing could rebuild it; only feature scenario recordings are bundled`);
+        const feature = insideRoot(lab.root, data.feature.uri);
+        if (!feature || !files.exists(joinPath(lab.root, feature)))
+            throw new Error(`Recording ${data.id} ran ${data.feature.uri}, which is not a file in the lab (${lab.root})`);
+        const entries = [];
+        const recordingDirectory = joinPath(target.store.location, data.id);
+        for (const path of walk(files, recordingDirectory))
+            entries.push({ path: `recordings/${data.id}/${path}`, source: joinPath(recordingDirectory, path) });
+        entries.push({ path: `scenario/${feature}`, source: joinPath(lab.root, feature) });
+        if (files.exists(joinPath(lab.root, "lab.lock.json")))
+            entries.push({ path: "versions/lab.lock.json", source: joinPath(lab.root, "lab.lock.json") });
+        const environment = this.environmentFacts(lab, data);
+        if (environment.manifest && files.exists(environment.manifest))
+            entries.push({ path: "versions/run-manifest.json", source: environment.manifest });
+        const preOnboarded = this.preOnboarded(lab, data);
+        const withheld = data.actors.filter((actor) => preOnboarded.has(actor.name)).map((actor) => ({ identity: actor.name, reason: `its key comes from the lab secret ${preOnboarded.get(actor.name)}` }));
+        const work = joinPath(lab.root, ".product-lab", "bundles", `.work-${data.id}`);
+        files.remove(work);
+        try {
+            const state = await this.state(data, environment, preOnboarded, withheld, work, entries);
+            this.refuseSecrets(lab, entries);
+            const attempt = { recording: data.id, status: data.status, startedAt: data.startedAt, finishedAt: data.finishedAt, ...this.failure(data) };
+            const checkout = await this.deps.sources.revision(lab.root);
+            const listed = this.appIds(lab, data.environment.id);
+            const apps = await this.deps.sources.apps(lab.root, lab.catalog, "ids" in listed ? listed.ids : []);
+            const read = await this.versions(lab.root);
+            const reproducible = bundleReproducibility({ state, ...(environment.public ? { public: environment.public } : {}), withheld });
+            const versions = "versions" in read ? read.versions : undefined;
+            const notices = [
+                ...("unread" in read ? [`The checkout's versions could not be read (${read.unread}); the bundle records none.`] : []),
+                ...("unknown" in listed ? [listed.unknown] : []),
+                ...(data.frames.some((frame) => frame.status === "captured") ? ["Its frames are unredacted images of the apps as they were shown."] : []),
+                ...(state.kind === "fixture" ? [TEST_KEYS_NOTICE] : []),
+                data.featureRun !== undefined
+                    ? "The run was in process: there are no log files; its steps and errors are in the recording."
+                    : "The run was a Cucumber process (product-lab test): its console log and reports are not bundled; its steps and errors are in the recording.",
+            ];
+            const file = request.out ?? joinPath(lab.root, ".product-lab", "bundles", `${data.id}${RUN_BUNDLE_EXTENSION}`);
+            const index = (bundled) => {
+                const scenarioFile = bundled.find((entry) => entry.path === `scenario/${feature}`);
+                const fields = {
+                    kind: RUN_BUNDLE_KIND,
+                    schemaVersion: RUN_BUNDLE_SCHEMA_VERSION,
+                    id: data.id,
+                    createdAt: this.deps.clock.date().toISOString(),
+                    platform: ports.archives.platform(),
+                    lab: { name: lab.name, config: insideRoot(lab.root, lab.path) ?? lab.path, root: lab.root },
+                    ...("source" in checkout ? { checkout: checkout.source } : {}),
+                    apps,
+                    ...(versions && Object.keys(versions).length ? { versions } : {}),
+                    environment: { id: data.environment.id, provider: data.environment.provider, label: data.environment.label, ...(environment.public ? { public: environment.public } : {}) },
+                    scenario: { feature, sha256: scenarioFile.sha256, name: data.title, ...(data.feature.line !== undefined ? { line: data.feature.line } : {}), tags: [...data.feature.tags] },
+                    attempts: [attempt],
+                    verdict: bundleVerdict([attempt]),
+                    state,
+                    withheld,
+                    reproducible,
+                    notices,
+                    recording: { schemaVersion: RECORDING_SCHEMA_VERSION },
+                    files: [...bundled],
+                };
+                return RunBundle.parse(fields).toJSON();
+            };
+            const written = await ports.archives.write({ file, entries, index, signal: this.deps.state.lifetime.signal });
+            return {
+                file,
+                id: data.id,
+                bytes: written.bytes,
+                sha256: written.sha256,
+                files: written.files.length,
+                verdict: bundleVerdict([attempt]),
+                state,
+                withheld,
+                reproducible,
+                notices,
+                ms: Math.round(this.deps.clock.now() - started),
+            };
+        }
+        finally {
+            files.remove(work);
+        }
+    }
+    failure(data) {
+        const failed = data.steps.find((step) => step.status === "failed");
+        const runner = data.runnerFailure;
+        if (!failed)
+            return runner ? { failure: { ...(runner.featureStep !== undefined ? { featureStep: runner.featureStep } : {}), step: runner.step, error: runner.error, marker: failureMarker(runner.error) } } : {};
+        const error = failed.error ?? data.error ?? "";
+        return { failure: { ...(failed.featureStep !== undefined ? { featureStep: failed.featureStep } : {}), step: failed.title, error, marker: failureMarker(error) } };
+    }
+    environmentFacts(lab, data) {
+        const active = this.deps.state.active;
+        const running = active && active.session === data.environment.session ? active.environment.registry : undefined;
+        let declared = {};
+        try {
+            const registry = lab.catalog?.registry(data.environment.id);
+            const entry = registry?.environments.find((item) => item.id === data.environment.id);
+            declared = {
+                ...(entry?.offer.public ? { public: entry.offer.public } : {}),
+                ...(entry?.retention ? { retention: entry.retention.retention } : {}),
+                ...(entry?.topology ? { stateText: entry.topology.state } : {}),
+            };
+        }
+        catch {
+        }
+        const publicTarget = running?.environment.offer.public ?? declared.public;
+        const retention = running?.environment.retention?.retention ?? declared.retention;
+        const stateText = running?.environment.topology?.state ?? declared.stateText;
+        return {
+            ...(publicTarget ? { public: publicTarget } : {}),
+            ...(running?.environment.manifest ? { manifest: running.environment.manifest } : {}),
+            ...(retention ? { retention } : {}),
+            ...(stateText ? { stateText } : {}),
+        };
+    }
+    preOnboarded(lab, data) {
+        const declared = lab.catalog?.preOnboardedActors?.() ?? [];
+        const names = new Map(declared.map((actor) => [actor.name, actor.secret]));
+        const active = this.deps.state.active;
+        if (active && active.session === data.environment.session)
+            for (const actor of active.environment.preOnboarded?.() ?? [])
+                names.set(actor.name, actor.secretName);
+        return names;
+    }
+    async state(data, environment, preOnboarded, withheld, work, entries) {
+        if (environment.public)
+            return { kind: "unsaved", reason: `${data.environment.id} is a public network; its state cannot be saved` };
+        const fixture = data.feature?.fixture;
+        if (fixture) {
+            if (fixture.action === "shared")
+                return { kind: "unsaved", reason: `fixture ${fixture.name} was restored for an earlier scenario of its @fixture-shared group, which changed it` };
+            const record = this.deps.fixtures ? RestoreFixture.read(this.deps.fixtures, fixture.name) : undefined;
+            if (!record && fixture.action === "run-start")
+                return { kind: "unsaved", reason: `its starting state was kept as ${fixture.name}, which has been removed since (the lab keeps the last ${RUN_STARTS_KEPT})` };
+            if (!record || !this.deps.exportFixture)
+                return { kind: "unsaved", reason: `fixture ${fixture.name} is not saved here any more` };
+            const secretBacked = record.identities.filter((identity) => preOnboarded.has(identity.name));
+            if (secretBacked.length) {
+                for (const identity of secretBacked)
+                    if (!withheld.some((item) => item.identity === identity.name))
+                        withheld.push({ identity: identity.name, reason: `fixture ${fixture.name} holds it, and its key comes from the lab secret ${preOnboarded.get(identity.name)}` });
+                return { kind: "unsaved", reason: `fixture ${fixture.name} holds identities whose keys come from lab secrets (${secretBacked.map((identity) => identity.name).join(", ")}), so it is not bundled` };
+            }
+            const index = joinPath(work, "state", "fixture", `${fixture.name}.json`);
+            const exported = await this.deps.exportFixture({ name: fixture.name, out: index });
+            entries.push({ path: `state/fixture/${fixture.name}.json`, source: exported.index });
+            for (const part of exported.parts)
+                entries.push({ path: `state/fixture/${part.file}`, source: joinPath(parentOf(exported.index), part.file) });
+            return { kind: "fixture", fixture: fixture.name, key: record.key.lineage, index: `state/fixture/${fixture.name}.json` };
+        }
+        const wording = environment.stateText ?? "its state";
+        if (rebuiltFromVersions(environment))
+            return { kind: "fresh", reason: `${wording}: rebuilt from its versions alone` };
+        if (data.feature?.startNotKept)
+            return { kind: "unsaved", reason: `${wording} was not kept: "Keep each fork run's starting state" was off when it started`, keepable: true };
+        return { kind: "unsaved", reason: `${wording} (${environment.retention ?? "unknown"} retention) was not saved as a fixture` };
+    }
+    refuseSecrets(lab, entries) {
+        const secrets = (lab.catalog?.secretValues() ?? []).filter((value) => value.length >= MIN_SECRET);
+        if (!secrets.length)
+            return;
+        for (const entry of entries) {
+            if (!/\.(json|feature|txt|log|md)$/.test(entry.path))
+                continue;
+            const text = this.deps.files.readText(entry.source);
+            if (text !== undefined && secrets.some((secret) => text.includes(secret)))
+                throw new Error(`Refusing to bundle: ${entry.path} holds the value of a lab secret`);
+        }
+    }
+    async versions(labRoot) {
+        if (!this.deps.versions)
+            return {};
+        try {
+            return { versions: await this.deps.versions(labRoot) };
+        }
+        catch (error) {
+            return { unread: error.message.split("\n")[0] };
+        }
+    }
+    appIds(lab, environmentId) {
+        if (!lab.catalog)
+            return { unknown: "The lab declares no catalog: no app source is recorded." };
+        try {
+            return { ids: lab.catalog.registry(environmentId).apps.map((app) => app.app) };
+        }
+        catch (error) {
+            return { unknown: `The lab no longer declares environment ${environmentId} (${error.message.split("\n")[0]}): no app source is recorded.` };
+        }
+    }
+}

package/core/application/src/runs/bundles/open-run-bundle.d.ts

@@ -0,0 +1,23 @@
+import { RunBundle, type ReproductionHere } from "@parity/product-lab/domain";
+import type { RunBundleOpened, RunBundleOpenRequest } 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";
+import type { RunBundlePorts } from "./run-bundle-ports.js";
+import type { RunBundleSources } from "./run-bundle-sources.js";
+export interface OpenRunBundleDependencies {
+    readonly state: LabState;
+    readonly files: FileSystem | undefined;
+    readonly ports: RunBundlePorts | undefined;
+    readonly sources: RunBundleSources;
+    readonly redactor: Redactor;
+    readonly clock: Clock;
+}
+export declare class OpenRunBundle {
+    private readonly deps;
+    constructor(deps: OpenRunBundleDependencies);
+    execute(request: RunBundleOpenRequest): Promise<RunBundleOpened>;
+    /** What would refuse a reproduction of `bundle` here (its extracted copy in `directory`). */
+    here(bundle: RunBundle, directory: string): Promise<RunBundleOpened["here"]>;
+    /** This machine and checkout as a reproduction of `bundle` would run them. */
+    hereFacts(bundle: RunBundle, directory: string): Promise<ReproductionHere>;
+}

package/core/application/src/runs/bundles/open-run-bundle.js

@@ -0,0 +1,50 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { RunBundle, RunBundleReproduction } from "@parity/product-lab/domain";
+import { RecordingNotFoundError } from "@parity/product-lab/domain/recordings";
+import { recordingView } from "../../recordings/open-recording.js";
+import { joinPath } from "./bundle-paths.js";
+export class OpenRunBundle {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(request) {
+        const { files, ports } = this.deps;
+        if (!files || !ports)
+            throw new Error("This runtime opens no run bundles (it was built without the run bundle archive)");
+        const lab = this.deps.state.lab;
+        if (!lab)
+            throw new Error("No lab is loaded: open a bundle with the lab it was made in, so it can be compared with this checkout");
+        const bundle = RunBundle.parse(await ports.archives.readIndex(request.file));
+        const directory = request.directory ?? joinPath(lab.root, ".product-lab", "bundles", "opened", `${bundle.id}-${this.deps.clock.date().getTime()}`);
+        await ports.archives.extract({ file: request.file, files: bundle.data.files, target: directory, signal: this.deps.state.lifetime.signal });
+        const store = ports.recordingsAt(joinPath(directory, "recordings"));
+        const recordings = [];
+        for (const attempt of bundle.data.attempts) {
+            const recording = await store.read(attempt.recording);
+            if (!recording)
+                throw new RecordingNotFoundError(`Run bundle ${bundle.id} lists recording ${attempt.recording}, which it does not hold`);
+            recordings.push(recordingView(recording, this.deps.redactor));
+        }
+        const here = await this.here(bundle, directory);
+        return this.deps.redactor.value({ file: request.file, directory, bundle: bundle.toJSON(), recordings, here });
+    }
+    async here(bundle, directory) {
+        return RunBundleReproduction.problems(bundle, await this.hereFacts(bundle, directory));
+    }
+    async hereFacts(bundle, directory) {
+        const lab = this.deps.state.lab;
+        const files = this.deps.files;
+        const checkout = await this.deps.sources.revision(lab.root);
+        const apps = await this.deps.sources.appsHere(lab.root, lab.catalog, bundle.data.apps.map((app) => app.id));
+        const ours = files.readText(joinPath(lab.root, bundle.data.scenario.feature));
+        const bundled = files.readText(joinPath(directory, "scenario", bundle.data.scenario.feature));
+        return {
+            platform: this.deps.ports.archives.platform(),
+            ...("source" in checkout ? { checkout: checkout.source } : {}),
+            apps,
+            ...(ours !== undefined ? { featureChanged: ours !== bundled } : {}),
+        };
+    }
+}

package/core/application/src/runs/bundles/reproduce-run.d.ts

@@ -0,0 +1,44 @@
+import { type ControlStep } from "@parity/product-lab/domain";
+import { RunRecording } from "@parity/product-lab/domain/recordings";
+import type { FeatureRunHandle, ReproduceReport, ReproduceRequest, RunFeaturesRequest } from "@parity/product-lab/ports/driving";
+import type { Clock, FileSystem } from "@parity/product-lab/ports/system";
+import type { LabState } from "../../lab/lab-state.js";
+import type { RecordingStores } from "../../recordings/recording-stores.js";
+import type { OpenRunBundle } from "./open-run-bundle.js";
+import type { RunBundlePorts } from "./run-bundle-ports.js";
+export interface ReproduceRunDependencies {
+    readonly state: LabState;
+    readonly files: FileSystem | undefined;
+    readonly ports: RunBundlePorts | undefined;
+    readonly stores: RecordingStores;
+    readonly clock: Clock;
+    readonly open: OpenRunBundle;
+    start(environment: string): Promise<void>;
+    reset(confirmation: string): Promise<void>;
+    importFixture(index: string, confirmation: string | undefined): Promise<void>;
+    runFeatures(request: RunFeaturesRequest): Promise<FeatureRunHandle>;
+}
+/**
+ * A recording's steps as the negative-control rule reads them: steps that never ran count as skipped, and a failure
+ * its runner reported outside the lab's runs (a custom step, a hook) is the last step, failed.
+ */
+export declare function controlSteps(recording: RunRecording): ControlStep[];
+export declare class ReproduceRun {
+    private readonly deps;
+    constructor(deps: ReproduceRunDependencies);
+    execute(request: ReproduceRequest): Promise<ReproduceReport>;
+    /** The bundled scenario once more, in process, judged against the bundled failure. */
+    private rerun;
+    /** The race the original ran with (backlog 32): its scenario's own seed, applied as it is, so it waits the same again. */
+    private bundledRace;
+    private view;
+    /**
+     * The state the scenario started on: the bundle's fixture imported, else the environment started or reset. A later
+     * rerun rebuilds it again on the environment this reproduction runs, with that environment's own confirmation.
+     */
+    private rebuildState;
+    /** The rerun's recording: the recorder writes it once the feature run completes. */
+    private recordingOf;
+    /** A bundle with every run beside the original: the original's files and each rerun's recording. */
+    private writeEvidence;
+}

package/core/application/src/runs/bundles/reproduce-run.js

@@ -0,0 +1,173 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { RunBundle, RunBundleRefusedError, RunBundleReproduction, bundleVerdict, failureMarker, } from "@parity/product-lab/domain";
+import { RunRecording } from "@parity/product-lab/domain/recordings";
+import { childrenOf, joinPath, parentOf } from "./bundle-paths.js";
+const RECORDING_WAIT_MS = 30_000;
+const MAX_RERUNS = 20;
+export function controlSteps(recording) {
+    const steps = recording.data.steps.map((step) => ({
+        index: step.index,
+        title: step.title,
+        status: step.status === "complete" ? "passed" : step.status === "failed" ? "failed" : "skipped",
+        ...(step.error !== undefined ? { error: step.error } : {}),
+    }));
+    const runner = recording.data.runnerFailure;
+    return runner ? [...steps, { index: steps.length, title: runner.step, status: "failed", error: runner.error }] : steps;
+}
+export class ReproduceRun {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(request) {
+        const started = this.deps.clock.now();
+        const { files, ports } = this.deps;
+        if (!files || !ports)
+            throw new Error("This runtime reproduces no run bundles (it was built without the run bundle archive)");
+        const times = request.reruns ?? 1;
+        if (!Number.isInteger(times) || times < 1 || times > MAX_RERUNS)
+            throw new Error(`reruns must be a whole number from 1 to ${MAX_RERUNS}, not ${times}`);
+        const opened = await this.deps.open.execute({ file: request.file });
+        const bundle = RunBundle.parse(opened.bundle);
+        const { refusals, rechecks } = RunBundleReproduction.problems(bundle, await this.deps.open.hereFacts(bundle, opened.directory), { againstCurrent: request.againstCurrent === true });
+        if (refusals.length)
+            throw new RunBundleRefusedError(bundle.id, refusals);
+        const failure = bundle.failure;
+        const race = this.bundledRace(bundle, opened.directory);
+        const reruns = [];
+        for (let attempt = 0; attempt < times; attempt++) {
+            await this.rebuildState(bundle, opened.directory, attempt === 0 ? request.confirmation : undefined, attempt > 0);
+            const rerun = await this.rerun(bundle, failure, race);
+            reruns.push(rerun);
+            if (rerun.record.status === "passed")
+                break;
+        }
+        const verdict = bundleVerdict([bundle.data.attempts[0], ...reruns.map((rerun) => ({ status: rerun.record.status === "passed" ? "passed" : "failed" }))]);
+        const evidence = await this.writeEvidence(bundle, opened.directory, reruns);
+        const decisive = reruns.find((rerun) => rerun.judged.outcome !== "reproduced") ?? reruns.at(-1);
+        const outcome = rechecks.length && decisive.judged.outcome === "reproduced" ? "rechecked-same-failure" : decisive.judged.outcome;
+        const views = reruns.map((rerun) => this.view(rerun));
+        const last = views.at(-1);
+        const counted = times > 1 ? `; ${verdict === "flaky" ? `flaky: it did not fail on rerun ${reruns.length} of up to ${times}` : `it failed on all ${reruns.length} reruns`}` : "";
+        return {
+            bundle: request.file,
+            outcome,
+            reason: `${rechecks.length ? `${decisive.judged.reason}; a recheck against this code (${rechecks.map((problem) => problem.code).join(", ")}), not a reproduction` : decisive.judged.reason}${counted}`,
+            rechecks,
+            expected: RunBundleReproduction.expectation(failure),
+            rerun: { featureRun: last.featureRun, ...(last.recording ? { recording: last.recording } : {}), status: last.status, ...(last.error ? { error: last.error } : {}) },
+            reruns: views,
+            verdict,
+            evidence,
+            ...(race ? { race: { scenarioSeed: race.seed, maxMs: race.maxMs } } : {}),
+            ms: Math.round(this.deps.clock.now() - started),
+        };
+    }
+    async rerun(bundle, failure, race) {
+        const feature = bundle.data.scenario.feature;
+        const handle = await this.deps.runFeatures({
+            paths: [bundle.data.scenario.line !== undefined ? `${feature}:${bundle.data.scenario.line}` : feature],
+            environment: bundle.data.environment.id,
+            requireScenarios: true,
+            label: "reproduce",
+            ...(race ? { race } : {}),
+            runsDirectory: joinPath(this.deps.state.lab.root, ".product-lab", "reproduce"),
+            inProcess: {},
+        });
+        const record = await handle.completion;
+        const recording = await this.recordingOf(record);
+        const steps = recording ? controlSteps(recording) : record.steps.map((step) => ({ ...step }));
+        return { record, recording, judged: RunBundleReproduction.judge(failure, { exitCode: record.status === "passed" ? 0 : 1, steps }) };
+    }
+    bundledRace(bundle, directory) {
+        const text = this.deps.files.readText(joinPath(directory, "recordings", bundle.data.attempts[0].recording, "recording.json"));
+        const race = text === undefined ? undefined : RunRecording.from(JSON.parse(text)).data.race;
+        return race ? { seed: race.scenarioSeed, maxMs: race.maxMs, exact: true } : undefined;
+    }
+    view({ record, recording, judged }) {
+        const failed = recording?.data.steps.find((step) => step.status === "failed");
+        const error = failed?.error ?? recording?.data.runnerFailure?.error ?? record.error;
+        return { featureRun: record.id, ...(recording ? { recording: recording.data.id } : {}), status: record.status, ...(error ? { error } : {}), outcome: judged.outcome, reason: judged.reason };
+    }
+    async rebuildState(bundle, directory, confirmation, again) {
+        const environment = bundle.data.environment.id;
+        const active = this.deps.state.active;
+        if (active && active.environment.registry?.environment.id !== environment && active.selected !== environment)
+            throw new RunBundleRefusedError(bundle.id, [{ code: "state", message: `environment ${active.selected ?? active.environment.name} is running; the bundle ran on ${environment}: stop it first, or switch to ${environment}` }]);
+        const startedHere = !active;
+        if (startedHere)
+            await this.deps.start(environment);
+        const running = this.deps.state.requireActive();
+        const state = bundle.data.state;
+        if (state.kind === "fixture") {
+            await this.deps.importFixture(joinPath(directory, state.index), startedHere || again ? running.confirmations.restoreFixture : confirmation);
+            return;
+        }
+        if (startedHere)
+            return;
+        if (again)
+            return this.deps.reset(running.confirmations.reset);
+        if (!confirmation)
+            throw new RunBundleRefusedError(bundle.id, [{ code: "state", message: `reproducing resets the running ${environment}: pass its reset confirmation (snapshot().confirmations.reset)` }]);
+        await this.deps.reset(confirmation);
+    }
+    async recordingOf(record) {
+        const target = this.deps.stores.current();
+        if ("disabled" in target)
+            return undefined;
+        const deadline = this.deps.clock.now() + RECORDING_WAIT_MS;
+        for (;;) {
+            const listing = await target.store.list();
+            for (const summary of listing.recordings) {
+                const recording = await target.store.read(summary.id);
+                if (recording?.data.featureRun === record.id)
+                    return recording;
+            }
+            if (this.deps.clock.now() >= deadline)
+                return undefined;
+            await this.deps.clock.sleep(250, this.deps.state.lifetime.signal);
+        }
+    }
+    async writeEvidence(bundle, directory, reruns) {
+        const files = this.deps.files;
+        const entries = bundle.data.files.map((file) => ({ path: file.path, source: joinPath(directory, file.path) }));
+        const attempts = [...bundle.data.attempts];
+        const target = this.deps.stores.current();
+        for (const { recording, judged } of reruns) {
+            if (!recording)
+                continue;
+            const location = "store" in target ? joinPath(target.store.location, recording.data.id) : undefined;
+            const walk = (prefix) => (childrenOf(files, joinPath(location, prefix)) ?? []).sort().flatMap((name) => {
+                const path = prefix ? `${prefix}/${name}` : name;
+                return childrenOf(files, joinPath(location, path)) !== undefined ? walk(path) : [path];
+            });
+            if (location)
+                for (const path of walk(""))
+                    entries.push({ path: `recordings/${recording.data.id}/${path}`, source: joinPath(location, path) });
+            const failed = recording.data.steps.find((step) => step.status === "failed");
+            attempts.push({
+                recording: recording.data.id,
+                status: recording.data.status,
+                startedAt: recording.data.startedAt,
+                finishedAt: recording.data.finishedAt,
+                ...(failed
+                    ? { failure: { ...(failed.featureStep !== undefined ? { featureStep: failed.featureStep } : {}), step: failed.title, error: failed.error ?? "", marker: failureMarker(failed.error ?? "") } }
+                    : recording.data.runnerFailure
+                        ? { failure: { ...(recording.data.runnerFailure.featureStep !== undefined ? { featureStep: recording.data.runnerFailure.featureStep } : {}), step: recording.data.runnerFailure.step, error: recording.data.runnerFailure.error, marker: failureMarker(recording.data.runnerFailure.error) } }
+                        : {}),
+                comparison: { verdict: judged.verdict, reason: judged.reason },
+            });
+        }
+        const file = joinPath(parentOf(directory), `${bundle.id}.reproduced-${this.deps.clock.date().getTime()}.plbundle`);
+        await this.deps.ports.archives.write({
+            file,
+            entries,
+            index: (written) => {
+                const data = { ...bundle.data, createdAt: this.deps.clock.date().toISOString(), attempts, verdict: bundleVerdict(attempts), files: [...written] };
+                return RunBundle.parse(data).toJSON();
+            },
+        });
+        return file;
+    }
+}

package/core/application/src/runs/bundles/run-bundle-ports.d.ts

@@ -0,0 +1,7 @@
+import type { RecordingStore } from "@parity/product-lab/ports/recording";
+import type { RunBundleArchives } from "@parity/product-lab/ports/storage";
+export interface RunBundlePorts {
+    readonly archives: RunBundleArchives;
+    /** A recording store on `directory` (its recordings are `<directory>/<id>/`). */
+    recordingsAt(directory: string): RecordingStore;
+}

package/core/application/src/runs/bundles/run-bundle-ports.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/core/application/src/runs/bundles/run-bundle-sources.d.ts

@@ -0,0 +1,18 @@
+import type { RunBundleApp, SourceRevisionData } from "@parity/product-lab/domain";
+import type { LabCatalog } from "@parity/product-lab/ports/lab";
+import type { ChangeSource, FileSystem } from "@parity/product-lab/ports/system";
+export declare class RunBundleSources {
+    private readonly changes;
+    private readonly files;
+    constructor(changes: ChangeSource | undefined, files: FileSystem | undefined);
+    /** The revision of `directory`, or why there is none. */
+    revision(directory: string): Promise<{
+        source: SourceRevisionData;
+    } | {
+        unknown: string;
+    }>;
+    /** Every listed app with its source revision, or why it has none. */
+    apps(labRoot: string, catalog: LabCatalog | undefined, appIds: readonly string[]): Promise<RunBundleApp[]>;
+    /** Each app's revision here, by id (undefined: none could be read). */
+    appsHere(labRoot: string, catalog: LabCatalog | undefined, appIds: readonly string[]): Promise<Record<string, SourceRevisionData | undefined>>;
+}