@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/domain/src/conditions/conditioned-traffic.js

@@ -0,0 +1,31 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const PASS = { action: "pass" };
+const FAMILY = { "http:": "http", "ws:": "http", "https:": "https", "wss:": "https" };
+function originKey(url) {
+    if (!URL.canParse(url))
+        return undefined;
+    const parsed = new URL(url);
+    const family = FAMILY[parsed.protocol];
+    if (!family)
+        return undefined;
+    const port = parsed.port || (family === "https" ? "443" : "80");
+    return `${family}://${parsed.hostname}:${port}`;
+}
+export function isLocalLink(url, exempt) {
+    const key = originKey(url);
+    return key !== undefined && exempt.some((origin) => originKey(origin) === key);
+}
+export function transferMs(bytes, kbps) {
+    return bytes === undefined || kbps === undefined ? 0 : Math.ceil((bytes * 8) / kbps);
+}
+export function trafficDecision(condition, piece, exempt) {
+    if (condition.kind === "online" || isLocalLink(piece.url, exempt))
+        return PASS;
+    if (condition.kind === "offline")
+        return { action: "abort", reason: "the identity is offline (a scenario condition)" };
+    const up = piece.kind === "request" || (piece.kind === "message" && piece.direction === "up");
+    const latency = piece.kind === "request" ? condition.latencyMs : piece.kind === "message" ? Math.ceil(condition.latencyMs / 2) : 0;
+    const ms = latency + transferMs(piece.bytes, up ? condition.upKbps : condition.downKbps);
+    return ms > 0 ? { action: "delay", ms } : PASS;
+}

package/core/domain/src/conditions/conditioned-wire.d.ts

@@ -0,0 +1,21 @@
+import type { NetworkCondition } from "./network-condition.js";
+export declare class ConditionedWire<T = unknown> {
+    private readonly direction;
+    /** When the wire has finished sending what it was given. */
+    private free;
+    /** When the latest piece arrives: no later piece arrives before it. */
+    private last;
+    /** What was sent and has not arrived yet, in order (arrival times never decrease). */
+    private readonly queue;
+    constructor(direction: "up" | "down");
+    /** When a piece of `bytes` sent at `now` arrives, in the same clock; undefined while offline (it is lost). */
+    arrival(condition: NetworkCondition, now: number, bytes: number): number | undefined;
+    /** Send `piece` (of `bytes`) at `now`: queued until it arrives, or lost while offline (false). */
+    send(condition: NetworkCondition, now: number, bytes: number, piece: T): boolean;
+    /** What has arrived by `now`, in the order it was sent; taken off the wire. */
+    due(now: number): T[];
+    /** When the next piece arrives; undefined when nothing is in flight. */
+    next(): number | undefined;
+    /** Drop what is in flight (the connection was cut). */
+    clear(): void;
+}

package/core/domain/src/conditions/conditioned-wire.js

@@ -0,0 +1,38 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { transferMs } from "./conditioned-traffic.js";
+export class ConditionedWire {
+    direction;
+    free = 0;
+    last = 0;
+    queue = [];
+    constructor(direction) {
+        this.direction = direction;
+    }
+    arrival(condition, now, bytes) {
+        if (condition.kind === "offline")
+            return undefined;
+        if (condition.kind === "online") {
+            this.free = Math.max(this.free, now);
+            return (this.last = Math.max(this.last, now));
+        }
+        this.free = Math.max(this.free, now) + transferMs(bytes, this.direction === "up" ? condition.upKbps : condition.downKbps);
+        return (this.last = Math.max(this.last, this.free + Math.ceil(condition.latencyMs / 2)));
+    }
+    send(condition, now, bytes, piece) {
+        const at = this.arrival(condition, now, bytes);
+        if (at !== undefined)
+            this.queue.push({ at, piece });
+        return at !== undefined;
+    }
+    due(now) {
+        const count = this.queue.findIndex((item) => item.at > now);
+        return this.queue.splice(0, count === -1 ? this.queue.length : count).map((item) => item.piece);
+    }
+    next() {
+        return this.queue[0]?.at;
+    }
+    clear() {
+        this.queue.length = 0;
+    }
+}

package/core/domain/src/conditions/cpu-slowdown.d.ts

@@ -0,0 +1,4 @@
+export declare const CPU_SLOWDOWNS: readonly [1, 2, 4, 6];
+export type CpuSlowdown = (typeof CPU_SLOWDOWNS)[number];
+/** `value` as a slowdown; throws naming the factors there are. */
+export declare function cpuSlowdown(value: unknown): CpuSlowdown;

package/core/domain/src/conditions/cpu-slowdown.js

@@ -0,0 +1,9 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ConditionError } from "./condition-error.js";
+export const CPU_SLOWDOWNS = [1, 2, 4, 6];
+export function cpuSlowdown(value) {
+    if (CPU_SLOWDOWNS.includes(value))
+        return value;
+    throw new ConditionError(`A device can be ${CPU_SLOWDOWNS.filter((factor) => factor > 1).join(", ")} times slower (or 1, full speed), not ${JSON.stringify(value)}`);
+}

package/core/domain/src/conditions/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./condition-error.js";
+export * from "./condition-profiles.js";
+export * from "./condition-step.js";
+export * from "./conditioned-traffic.js";
+export * from "./conditioned-wire.js";
+export * from "./cpu-slowdown.js";
+export * from "./network-condition.js";

package/core/domain/src/conditions/index.js

@@ -0,0 +1,9 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export * from "./condition-error.js";
+export * from "./condition-profiles.js";
+export * from "./condition-step.js";
+export * from "./conditioned-traffic.js";
+export * from "./conditioned-wire.js";
+export * from "./cpu-slowdown.js";
+export * from "./network-condition.js";

package/core/domain/src/conditions/network-condition.d.ts

@@ -0,0 +1,18 @@
+export type NetworkCondition = {
+    readonly kind: "online";
+} | {
+    readonly kind: "offline";
+}
+/** Throughput absent: unlimited. */
+ | {
+    readonly kind: "throttled";
+    readonly latencyMs: number;
+    readonly downKbps?: number;
+    readonly upKbps?: number;
+};
+export declare const ONLINE: NetworkCondition;
+export declare const OFFLINE: NetworkCondition;
+/** A condition as people read it: `online`, `offline`, or `400 ms, 400 kbit/s down, 400 kbit/s up`. */
+export declare function describeNetwork(condition: NetworkCondition): string;
+/** Every problem with a value as a network condition (empty: it is one). */
+export declare function networkConditionProblems(value: unknown): string[];

package/core/domain/src/conditions/network-condition.js

@@ -0,0 +1,25 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const ONLINE = { kind: "online" };
+export const OFFLINE = { kind: "offline" };
+export function describeNetwork(condition) {
+    if (condition.kind !== "throttled")
+        return condition.kind;
+    return [`${condition.latencyMs} ms`, ...(condition.downKbps !== undefined ? [`${condition.downKbps} kbit/s down`] : []), ...(condition.upKbps !== undefined ? [`${condition.upKbps} kbit/s up`] : [])].join(", ");
+}
+export function networkConditionProblems(value) {
+    if (typeof value !== "object" || value === null)
+        return ["a network condition must be an object with a kind"];
+    const condition = value;
+    if (condition.kind === "online" || condition.kind === "offline")
+        return [];
+    if (condition.kind !== "throttled")
+        return [`kind must be online, offline or throttled, not ${JSON.stringify(condition.kind)}`];
+    const problems = [];
+    if (!Number.isInteger(condition.latencyMs) || condition.latencyMs < 0 || condition.latencyMs > 60_000)
+        problems.push("latencyMs must be a whole number of milliseconds from 0 to 60000");
+    for (const field of ["downKbps", "upKbps"])
+        if (condition[field] !== undefined && (!Number.isInteger(condition[field]) || condition[field] < 1))
+            problems.push(`${field} must be a whole number of kbit/s, at least 1 (absent: unlimited)`);
+    return problems;
+}

package/core/domain/src/devices/device-profile.d.ts

@@ -0,0 +1,43 @@
+/** One device as a surface emulates it. */
+export interface DeviceProfile {
+    /** "Pixel 7", a lab's own name, or "Desktop". */
+    readonly name: string;
+    /** The CSS viewport, in CSS pixels. */
+    readonly viewport: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Device pixels per CSS pixel (`window.devicePixelRatio`). */
+    readonly deviceScaleFactor: number;
+    /** A mobile browser: the page's `<meta name="viewport">` is honoured. */
+    readonly mobile: boolean;
+    /** Touch events, and `(pointer: coarse)`. */
+    readonly touch: boolean;
+    /** Absent: the browser's own. */
+    readonly userAgent?: string;
+}
+/** What a declaration names: a device by name (resolved against a catalogue), or a profile written out. */
+export type DeviceChoice = string | DeviceProfile;
+/** The desktop window: what a detached identity gets when no device is chosen. */
+export declare const DESKTOP_DEVICE: DeviceProfile;
+/** The largest viewport side and pixel ratio a profile may ask for. */
+export declare const DEVICE_LIMITS: {
+    readonly side: 8192;
+    readonly deviceScaleFactor: 5;
+};
+/** Problems with a profile, each naming its field (empty when it is well formed). `at` prefixes the field names. */
+export declare function deviceProfileProblems(value: unknown, at?: string): string[];
+/** Up to `count` of `known` closest to `name`: case-insensitive equal first, then containing it, then by edit distance. */
+export declare function nearestDeviceNames(name: string, known: readonly string[], count?: number): string[];
+/** A choice resolved: the profile, or why there is none. */
+export type DeviceResolution = {
+    readonly profile: DeviceProfile;
+} | {
+    readonly problem: string;
+};
+/**
+ * Resolve a choice against `catalogue` (the browser's named devices and a lab's own, by name). A name is matched
+ * exactly, then ignoring case; an unknown name is refused with the nearest names, never replaced by another device. A
+ * written-out profile is checked and used as it is.
+ */
+export declare function resolveDevice(choice: DeviceChoice, catalogue: Readonly<Record<string, DeviceProfile>>, at?: string): DeviceResolution;

package/core/domain/src/devices/device-profile.js

@@ -0,0 +1,70 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const DESKTOP_DEVICE = { name: "Desktop", viewport: { width: 1280, height: 800 }, deviceScaleFactor: 1, mobile: false, touch: false };
+export const DEVICE_LIMITS = { side: 8192, deviceScaleFactor: 5 };
+const FIELDS = new Set(["name", "viewport", "deviceScaleFactor", "mobile", "touch", "userAgent"]);
+export function deviceProfileProblems(value, at = "device") {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [`${at} must be a device name or { name, viewport: { width, height }, deviceScaleFactor, mobile, touch, userAgent? }`];
+    const profile = value;
+    const problems = Object.keys(profile)
+        .filter((key) => !FIELDS.has(key))
+        .map((key) => `${at}.${key} is not a device field`);
+    if (typeof profile.name !== "string" || !profile.name.trim())
+        problems.push(`${at}.name must be a non-empty string`);
+    const viewport = profile.viewport;
+    if (!viewport || typeof viewport !== "object" || Array.isArray(viewport))
+        problems.push(`${at}.viewport must be { width, height } in CSS pixels`);
+    else
+        for (const side of ["width", "height"])
+            if (!Number.isInteger(viewport[side]) || viewport[side] < 1 || viewport[side] > DEVICE_LIMITS.side)
+                problems.push(`${at}.viewport.${side} must be a whole number of CSS pixels from 1 to ${DEVICE_LIMITS.side}`);
+    const ratio = profile.deviceScaleFactor;
+    if (typeof ratio !== "number" || !Number.isFinite(ratio) || ratio <= 0 || ratio > DEVICE_LIMITS.deviceScaleFactor)
+        problems.push(`${at}.deviceScaleFactor must be a number above 0 and at most ${DEVICE_LIMITS.deviceScaleFactor}`);
+    for (const flag of ["mobile", "touch"])
+        if (typeof profile[flag] !== "boolean")
+            problems.push(`${at}.${flag} must be true or false`);
+    if (profile.userAgent !== undefined && (typeof profile.userAgent !== "string" || !profile.userAgent.trim()))
+        problems.push(`${at}.userAgent must be a non-empty string when given`);
+    return problems;
+}
+export function nearestDeviceNames(name, known, count = 3) {
+    const wanted = name.trim().toLowerCase();
+    const rank = (candidate) => {
+        const lower = candidate.toLowerCase();
+        if (lower === wanted)
+            return -2;
+        if (wanted && (lower.includes(wanted) || wanted.includes(lower)))
+            return -1;
+        return editDistance(wanted, lower);
+    };
+    return [...new Set(known)]
+        .map((candidate) => ({ candidate, rank: rank(candidate) }))
+        .sort((a, b) => a.rank - b.rank || a.candidate.length - b.candidate.length || a.candidate.localeCompare(b.candidate))
+        .slice(0, Math.max(0, count))
+        .map((item) => item.candidate);
+}
+export function resolveDevice(choice, catalogue, at = "device") {
+    if (typeof choice !== "string") {
+        const problems = deviceProfileProblems(choice, at);
+        return problems.length ? { problem: problems.join("; ") } : { profile: choice };
+    }
+    const names = Object.keys(catalogue);
+    const exact = Object.hasOwn(catalogue, choice) ? choice : names.filter((name) => name.toLowerCase() === choice.trim().toLowerCase());
+    const found = typeof exact === "string" ? exact : exact.length === 1 ? exact[0] : undefined;
+    if (found)
+        return { profile: { ...catalogue[found], name: found } };
+    const nearest = nearestDeviceNames(choice, names);
+    return { problem: `${at} "${choice}" is not a known device${nearest.length ? `; nearest: ${nearest.map((name) => `"${name}"`).join(", ")}` : ""}` };
+}
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++)
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        previous = current;
+    }
+    return previous[b.length];
+}

package/core/domain/src/devices/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./device-profile.js";
+export * from "./synthetic-media.js";

package/core/domain/src/devices/index.js

@@ -0,0 +1,4 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export * from "./device-profile.js";
+export * from "./synthetic-media.js";

package/core/domain/src/devices/synthetic-media.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Chromium's synthetic camera and microphone, with its media prompts accepted. Every browser the lab launches runs
+ * them, so no page in a lab run can prompt for the machine's camera or microphone or take them: Chromium's synthetic
+ * capture never asks the operating system for a device. A real camera may be held by another app, such as the
+ * operator's call (22 October 2026: an app played on camera showed "Your camera is busy" on every person's page). The
+ * Playwright adapter applies them to every launch, and `tools/architecture/tests/synthetic-media.test.ts` holds every
+ * direct launch in the repository to them.
+ */
+export declare const SYNTHETIC_MEDIA_ARGS: readonly ["--use-fake-ui-for-media-stream", "--use-fake-device-for-media-stream"];
+/** `options` with the synthetic media arguments first, and its own arguments after them. */
+export declare function withSyntheticMedia<T extends object = Record<never, never>>(options?: T & {
+    readonly args?: readonly string[] | undefined;
+}): T & {
+    args: string[];
+};

package/core/domain/src/devices/synthetic-media.js

@@ -0,0 +1,7 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const SYNTHETIC_MEDIA_ARGS = ["--use-fake-ui-for-media-stream", "--use-fake-device-for-media-stream"];
+export function withSyntheticMedia(options = {}) {
+    const own = (options.args ?? []).filter((arg) => !SYNTHETIC_MEDIA_ARGS.includes(arg));
+    return { ...options, args: [...SYNTHETIC_MEDIA_ARGS, ...own] };
+}

package/core/domain/src/explore/exploration-alphabet.d.ts

@@ -0,0 +1,30 @@
+import type { PaletteBlock } from "../builder/builder-palette.js";
+import type { SeededRandom } from "./seeded-random.js";
+/** One generated step: a palette block's pattern and the value of each of its parameters, as written. */
+export interface ExploreStep {
+    readonly pattern: string;
+    readonly values: readonly string[];
+}
+export declare class ExplorationAlphabet {
+    /** The block that introduces a new actor (`{actor} is a new actor`). */
+    readonly identity: PaletteBlock;
+    /** The actions an exploration may pick. */
+    readonly actions: readonly PaletteBlock[];
+    private constructor();
+    /**
+     * The alphabet of `blocks`: the identity block that introduces one actor by its only parameter, and every action
+     * that can run here, does not opt out (`explore: false`), takes no table and whose every parameter can be filled.
+     */
+    static from(blocks: readonly PaletteBlock[]): ExplorationAlphabet;
+    /** One sample: `actors[0]` introduced, then `steps` actions; the other actors are introduced along the way. */
+    sample(random: SeededRandom, options: {
+        readonly steps: number;
+        readonly actors: readonly string[];
+    }): ExploreStep[];
+    /** The step that introduces `actor`. */
+    introduce(actor: string): ExploreStep;
+    /** The actors `steps` introduce, in order. */
+    actorsOf(steps: readonly ExploreStep[]): string[];
+    /** Simpler forms of `step`, each changing one value to its default or to a smaller bound (for shrinking). */
+    simpler(step: ExploreStep): ExploreStep[];
+}

package/core/domain/src/explore/exploration-alphabet.js

@@ -0,0 +1,88 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const INTRODUCE = 0.25;
+const FILLABLE = new Set(["actor", "string", "int", "count", "word", "app", "route"]);
+export class ExplorationAlphabet {
+    identity;
+    actions;
+    constructor(
+    identity, 
+    actions) {
+        this.identity = identity;
+        this.actions = actions;
+    }
+    static from(blocks) {
+        const identity = blocks.find((block) => block.kind === "identity" && block.pattern === "{actor} is a new actor") ??
+            blocks.find((block) => block.kind === "identity" && block.introduces?.parameter === 0 && block.fields.length === 1);
+        if (!identity)
+            throw new Error('An exploration needs a block that introduces a new actor ("{actor} is a new actor")');
+        const actions = blocks.filter((block) => block.kind === "action" && block.available && block.explore !== false && !block.table && block.fields.every((field) => fillable(field)));
+        if (!actions.length)
+            throw new Error("An exploration needs at least one action that can run here and does not opt out (explore: false)");
+        return new ExplorationAlphabet(identity, actions);
+    }
+    sample(random, options) {
+        if (!options.actors.length)
+            throw new RangeError("A sample needs at least one actor name");
+        const scope = [options.actors[0]];
+        const steps = [this.introduce(scope[0])];
+        for (let index = 0; index < options.steps; index++) {
+            if (scope.length < options.actors.length && random.next() < INTRODUCE) {
+                const actor = options.actors[scope.length];
+                scope.push(actor);
+                steps.push(this.introduce(actor));
+            }
+            const block = random.pick(this.actions);
+            steps.push({ pattern: block.pattern, values: block.fields.map((field) => value(field, scope, random)) });
+        }
+        return steps;
+    }
+    introduce(actor) {
+        return { pattern: this.identity.pattern, values: [actor] };
+    }
+    actorsOf(steps) {
+        return steps.filter((step) => step.pattern === this.identity.pattern).map((step) => step.values[0]);
+    }
+    simpler(step) {
+        const block = this.actions.find((item) => item.pattern === step.pattern);
+        if (!block)
+            return [];
+        const variants = [];
+        block.fields.forEach((field, index) => {
+            const current = step.values[index];
+            for (const candidate of simplerValues(field, current))
+                variants.push({ pattern: step.pattern, values: step.values.map((item, at) => (at === index ? candidate : item)) });
+        });
+        return variants;
+    }
+}
+function fillable(field) {
+    if (!FILLABLE.has(field.kind))
+        return false;
+    if ((field.kind === "app" || field.kind === "route") && !field.options?.length && field.default === undefined)
+        return false;
+    return true;
+}
+function value(field, scope, random) {
+    if (field.kind === "actor")
+        return random.pick(scope);
+    if (field.options?.length)
+        return random.pick(field.options);
+    if (field.kind === "int" || field.kind === "count") {
+        const low = field.min ?? (field.kind === "count" ? 1 : 0);
+        const high = field.max ?? Math.max(low, typeof field.default === "number" ? field.default : low + 2);
+        return String(random.pick([low, high, Math.floor((low + high) / 2), ...(typeof field.default === "number" ? [field.default] : [])]));
+    }
+    const base = field.default !== undefined && String(field.default) !== "" ? String(field.default) : "explored";
+    return random.pick([base, `${base} ${random.int(1, 999)}`]);
+}
+function simplerValues(field, current) {
+    if (field.kind === "actor")
+        return [];
+    const candidates = [];
+    if (field.default !== undefined && String(field.default) !== current && String(field.default) !== "")
+        candidates.push(String(field.default));
+    if ((field.kind === "int" || field.kind === "count") && field.min !== undefined && String(field.min) !== current && !candidates.includes(String(field.min)))
+        candidates.push(String(field.min));
+    return candidates;
+}

package/core/domain/src/explore/failure-signature.d.ts

@@ -0,0 +1,13 @@
+export interface ExploreFailure {
+    /** `invariant`: an invariant check failed; `error`: a generated step itself failed. */
+    readonly kind: "invariant" | "error";
+    /** The invariant's pattern, for `invariant`. */
+    readonly invariant?: string;
+    /** The pattern of the step that failed. */
+    readonly step: string;
+    readonly error: string;
+}
+/** The error's first line with what varies between runs replaced. */
+export declare function errorShape(message: string): string;
+/** The signature two failures share when they are the same failure. */
+export declare function failureSignature(failure: ExploreFailure): string;

package/core/domain/src/explore/failure-signature.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function errorShape(message) {
+    return (message.split("\n")[0] ?? "")
+        .replace(/"[^"]*"/g, "<text>")
+        .replace(/0x[0-9a-fA-F]+/g, "<hex>")
+        .replace(/\d(?:[\d,._]*\d)?/g, "<n>")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 200);
+}
+export function failureSignature(failure) {
+    return [failure.kind, failure.invariant ?? "", failure.step, errorShape(failure.error)].join(" | ");
+}

package/core/domain/src/explore/index.d.ts

@@ -0,0 +1,6 @@
+export { SeededRandom } from "./seeded-random.js";
+export { ExplorationAlphabet, type ExploreStep } from "./exploration-alphabet.js";
+export { shrinkSteps, type ShrinkResult } from "./shrink-steps.js";
+export { errorShape, failureSignature, type ExploreFailure } from "./failure-signature.js";
+export { whatIfDifferences, whatIfPlan, type WhatIfBranch, type WhatIfOutcome, type WhatIfPlan } from "./what-if-branches.js";
+export { WhatIfPlanError } from "./what-if-plan-error.js";

package/core/domain/src/explore/index.js

@@ -0,0 +1,8 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { SeededRandom } from "./seeded-random.js";
+export { ExplorationAlphabet } from "./exploration-alphabet.js";
+export { shrinkSteps } from "./shrink-steps.js";
+export { errorShape, failureSignature } from "./failure-signature.js";
+export { whatIfDifferences, whatIfPlan } from "./what-if-branches.js";
+export { WhatIfPlanError } from "./what-if-plan-error.js";

package/core/domain/src/explore/seeded-random.d.ts

@@ -0,0 +1,11 @@
+export declare class SeededRandom {
+    readonly seed: number;
+    private state;
+    constructor(seed: number);
+    /** The next number in [0, 1). */
+    next(): number;
+    /** A whole number from `min` to `max`, both included. */
+    int(min: number, max: number): number;
+    /** One of `items` (not empty). */
+    pick<T>(items: readonly T[]): T;
+}

package/core/domain/src/explore/seeded-random.js

@@ -0,0 +1,27 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class SeededRandom {
+    seed;
+    state;
+    constructor(seed) {
+        this.seed = seed;
+        if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)
+            throw new RangeError(`A seed is a whole number from 0 to 4294967295, not ${seed}`);
+        this.state = seed;
+    }
+    next() {
+        this.state = (this.state + 0x6d2b79f5) >>> 0;
+        let value = this.state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+    }
+    int(min, max) {
+        return min + Math.floor(this.next() * (max - min + 1));
+    }
+    pick(items) {
+        if (!items.length)
+            throw new RangeError("Nothing to pick from");
+        return items[this.int(0, items.length - 1)];
+    }
+}

package/core/domain/src/explore/shrink-steps.d.ts

@@ -0,0 +1,15 @@
+export interface ShrinkResult<T> {
+    readonly steps: readonly T[];
+    /** Candidates tried (each a run, unless it did not plan). */
+    readonly tries: number;
+    /** True when the try limit stopped the shrinking before it was done. */
+    readonly limited: boolean;
+}
+/**
+ * The smallest list of `steps` that `fails`, found by removing chunks and then simplifying single steps (`simpler`).
+ * `steps` itself must fail. At most `limit` candidates are tried.
+ */
+export declare function shrinkSteps<T>(steps: readonly T[], fails: (candidate: readonly T[]) => Promise<boolean>, options?: {
+    readonly simpler?: (step: T) => readonly T[];
+    readonly limit?: number;
+}): Promise<ShrinkResult<T>>;

package/core/domain/src/explore/shrink-steps.js

@@ -0,0 +1,42 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export async function shrinkSteps(steps, fails, options = {}) {
+    const limit = options.limit ?? 200;
+    let tries = 0;
+    const attempt = async (candidate) => {
+        tries++;
+        return fails(candidate);
+    };
+    let current = [...steps];
+    let chunks = 2;
+    while (current.length >= 2 && tries < limit) {
+        const size = Math.ceil(current.length / chunks);
+        let reduced = false;
+        for (let start = 0; start < current.length && tries < limit; start += size) {
+            const candidate = [...current.slice(0, start), ...current.slice(start + size)];
+            if (candidate.length && (await attempt(candidate))) {
+                current = candidate;
+                chunks = Math.max(chunks - 1, 2);
+                reduced = true;
+                break;
+            }
+        }
+        if (reduced)
+            continue;
+        if (size === 1)
+            break;
+        chunks = Math.min(current.length, chunks * 2);
+    }
+    for (let index = 0; index < current.length && tries < limit; index++) {
+        for (const variant of options.simpler?.(current[index]) ?? []) {
+            if (tries >= limit)
+                break;
+            const candidate = current.map((step, at) => (at === index ? variant : step));
+            if (await attempt(candidate)) {
+                current = candidate;
+                break;
+            }
+        }
+    }
+    return { steps: current, tries, limited: tries >= limit };
+}

package/core/domain/src/explore/what-if-branches.d.ts

@@ -0,0 +1,34 @@
+import type { FeatureFile, FeatureStep } from "../features/feature-file.js";
+/** One branch: a scenario, or one Examples row of an outline with the row's values kept. */
+export interface WhatIfBranch {
+    readonly name: string;
+    readonly line: number;
+    /** The Examples row's values by its header (outlines only). */
+    readonly example?: Readonly<Record<string, string>>;
+    /** The steps as they run (placeholders filled in). */
+    readonly steps: readonly FeatureStep[];
+    /** The steps as written (an outline's template), so one outline's rows compare step for step. */
+    readonly written: readonly string[];
+    /** Its effective tags without the trunk's fixture and without isolation tags (the comparison isolates it). */
+    readonly tags: readonly string[];
+}
+export interface WhatIfPlan {
+    readonly trunk: {
+        readonly steps: readonly FeatureStep[];
+        readonly tags: readonly string[];
+        readonly line: number;
+    };
+    readonly branches: readonly WhatIfBranch[];
+}
+/** The trunk and branches of `feature`: every scenario, or those named in `only` (by scenario name). */
+export declare function whatIfPlan(feature: FeatureFile, only?: readonly string[]): WhatIfPlan;
+/** What a branch's comparison is made of: its result and each end check, as text the branches share. */
+export interface WhatIfOutcome {
+    readonly branch: string;
+    /** `passed`, or the failure's signature, or why it did not run. */
+    readonly result: string;
+    /** Each end check (an invariant for an actor, or a probe) and what it found: `holds`, `fails: <error shape>`, `not applicable`. */
+    readonly checks: Readonly<Record<string, string>>;
+}
+/** The results and checks that are not the same in every branch, each with what every branch found. */
+export declare function whatIfDifferences(outcomes: readonly WhatIfOutcome[]): string[];