@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/application/src/orchestration/lab/environment-registry.js

@@ -0,0 +1,124 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { topologyLabel } from "@parity/product-lab/domain";
+const METHODS = ["accepts", "profile", "withFlags", "resolve", "describe", "create"];
+function isFactory(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.kind === "string" &&
+        candidate.kind.length > 0 &&
+        Array.isArray(candidate.flags) &&
+        Array.isArray(candidate.profiles) &&
+        METHODS.every((method) => typeof candidate[method] === "function"));
+}
+export class EnvironmentRegistry {
+    #factories = new Map();
+    #deps;
+    errors;
+    constructor(factories = [], deps = {}) {
+        this.#deps = deps;
+        const errors = [];
+        const flags = new Map();
+        factories.forEach((factory, index) => {
+            if (!isFactory(factory)) {
+                errors.push(`environmentFactories[${index}] must be a topology adapter factory ({ kind, flags, profiles, ${METHODS.join(", ")} })`);
+                return;
+            }
+            if (this.#factories.has(factory.kind)) {
+                errors.push(`environmentFactories has two factories for ${factory.kind}`);
+                return;
+            }
+            for (const flag of factory.flags) {
+                const owner = flags.get(flag.name);
+                if (owner)
+                    errors.push(`--${flag.name} is claimed by both ${owner} and ${factory.kind}`);
+                else
+                    flags.set(flag.name, factory.kind);
+            }
+            this.#factories.set(factory.kind, factory);
+        });
+        this.errors = errors;
+    }
+    get kinds() {
+        return [...this.#factories.keys()];
+    }
+    get(kind) {
+        return this.#factories.get(kind);
+    }
+    #registered() {
+        return this.kinds.join(", ") || "none";
+    }
+    select(options) {
+        if (typeof options.provider === "string") {
+            const named = this.#factories.get(options.provider);
+            if (!named)
+                throw new Error(`No environment adapter serves ${options.provider} topologies (registered: ${this.#registered()}); select it in defineLab({ environmentAdapters }) or register its factory in defineLab({ environmentFactories })`);
+            return named;
+        }
+        const factories = [...this.#factories.values()];
+        const sectioned = factories.filter((factory) => factory.section !== undefined && options[factory.section] !== undefined);
+        if (sectioned.length > 1)
+            throw new Error(`These topology options carry sections for several adapters (${sectioned.map((factory) => factory.section).join(", ")}); keep one, or name the adapter with provider`);
+        if (sectioned.length === 1)
+            return sectioned[0];
+        const accepting = factories.filter((factory) => factory.accepts(options));
+        if (accepting.length === 1)
+            return accepting[0];
+        if (accepting.length > 1)
+            throw new Error(`Several environment adapters accept these topology options (${accepting.map((factory) => factory.kind).join(", ")}); name one with provider`);
+        throw new Error(`No registered environment adapter accepts these topology options (registered: ${this.#registered()}); select one in defineLab({ environmentAdapters }) or register its factory in defineLab({ environmentFactories }), or name one with provider`);
+    }
+    resolve(options) {
+        return this.select(options).resolve(options);
+    }
+    get profiles() {
+        return [...this.#factories.values()].flatMap((factory) => factory.profiles.map((profile) => ({ kind: factory.kind, profile })));
+    }
+    profile(name, options) {
+        const owners = [...this.#factories.values()].filter((factory) => factory.profiles.some((profile) => profile.name === name));
+        if (owners.length !== 1) {
+            const known = this.profiles.map((item) => item.profile.name).join(", ") || "none";
+            throw new Error(owners.length ? `Profile ${name} is offered by several adapters (${owners.map((factory) => factory.kind).join(", ")})` : `Unknown profile ${name} (registered adapters offer: ${known})`);
+        }
+        return { ...owners[0].profile(name, options), provider: owners[0].kind };
+    }
+    get flags() {
+        return [...this.#factories.values()].flatMap((factory) => factory.flags.map((flag) => ({ kind: factory.kind, flag })));
+    }
+    withFlags(values, options) {
+        let next = options;
+        for (const factory of this.#factories.values()) {
+            const given = factory.flags.filter((flag) => {
+                const value = values[flag.name];
+                return value !== undefined && value !== false && !(Array.isArray(value) && value.length === 0);
+            });
+            if (given.length)
+                next = factory.withFlags(values, next);
+        }
+        return next;
+    }
+    problems(t) {
+        return this.#factories.get(t.provider)?.problems?.(t) ?? [];
+    }
+    unserved(t) {
+        if (this.#factories.has(t.provider))
+            return undefined;
+        return `no environment adapter serves ${t.provider} topologies: select it in defineLab({ environmentAdapters: { ${t.provider}: {…} } }) or register its factory in defineLab({ environmentFactories }) (registered: ${this.#registered()})`;
+    }
+    environment(t) {
+        const factory = this.#factories.get(t.provider);
+        if (!factory)
+            return undefined;
+        const described = factory.describe(t);
+        const deps = this.#deps;
+        return {
+            label: described.label || topologyLabel(t),
+            ...(described.description ? { description: described.description } : {}),
+            ...(described.keeps ? { keeps: described.keeps } : {}),
+            topology: t,
+            offer: t.offer,
+            start: (context) => factory.create(t, deps).start(context),
+        };
+    }
+}

package/core/application/src/orchestration/lab/environment-view.d.ts

@@ -0,0 +1,12 @@
+import { type RetentionView } from "@parity/product-lab/domain";
+import type { TopologyView } from "@parity/product-lab/ports/driving";
+import { type Topology } from "../topology.js";
+import type { ResolvedEnvironment } from "./environments.js";
+export type { Retention, RetentionView } from "@parity/product-lab/domain";
+export type { TopologyView } from "@parity/product-lab/ports/driving";
+/** The state line: the adapter's wording, else derived from the state origin. */
+export declare function stateText(t: Topology): string;
+/** What stopping this topology's environment does to its state (the adapter's decision). */
+export declare function topologyRetention(t: Topology): RetentionView;
+export declare function topologyDetails(t: Topology): TopologyView;
+export declare function environmentRetention(environment: ResolvedEnvironment): RetentionView;

package/core/application/src/orchestration/lab/environment-view.js

@@ -0,0 +1,73 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { describeState } from "@parity/product-lab/domain";
+import { CAPABILITIES } from "../capabilities.js";
+import { capabilityReason } from "../topology.js";
+const MAX_VALUE = 160;
+const SUMMARISED = /^genesisEdits(\.|$)/;
+function show(value) {
+    const text = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
+    return text.length > MAX_VALUE ? `${text.slice(0, MAX_VALUE - 1)}…` : text;
+}
+function runtimeText(value) {
+    if (value === undefined)
+        return "bundle (default)";
+    if (typeof value === "string")
+        return value;
+    const source = value;
+    if (source.wasm)
+        return `wasm ${source.wasm}`;
+    if (source.spec)
+        return `spec ${source.spec}`;
+    if (source.release)
+        return `release ${source.release}`;
+    return show(value);
+}
+export function stateText(t) {
+    return t.presentation.state ?? describeState(t.state);
+}
+export function topologyRetention(t) {
+    return t.retention;
+}
+export function topologyDetails(t) {
+    return {
+        profile: t.profile,
+        label: t.label,
+        provider: t.provider,
+        network: t.network,
+        chains: [...t.chains],
+        relay: t.presentation.relay,
+        state: stateText(t),
+        chainDetails: t.chains.map((id) => ({
+            id,
+            ...(t.endpoints.chains[id]?.ws ? { ws: t.endpoints.chains[id].ws } : {}),
+            runtime: runtimeText(t.runtimes[id]),
+            ...(t.blockTime[id] ? { blockTime: t.blockTime[id] } : {}),
+            ...(t.nodeArgs[id]?.length ? { nodeArgs: [...t.nodeArgs[id]] } : {}),
+            ...(t.genesisEdits[id] ? { genesisEdits: Object.keys(t.genesisEdits[id]) } : {}),
+        })),
+        services: Object.entries(t.endpoints.services)
+            .filter((entry) => typeof entry[1] === "string")
+            .map(([id, url]) => ({ id, url })),
+        ports: Object.fromEntries(Object.entries(t.ports).filter((entry) => typeof entry[1] === "number")),
+        binaries: Object.entries(t.binaries).map(([name, source]) => `${name} ${show(source)}`),
+        noBinaries: t.presentation.binaries,
+        capabilities: CAPABILITIES.map((id) => {
+            const reason = capabilityReason(t, id);
+            return { id, available: t.capabilities[id], ...(reason ? { reason } : {}) };
+        }),
+        customizations: t.customizations.map((item) => item.option),
+        customizationValues: t.customizations.map((item) => ({
+            option: item.option,
+            value: item.sensitive || SUMMARISED.test(item.option)
+                ? `set (${item.value && typeof item.value === "object" ? Object.keys(item.value).join(", ") : "value"})`
+                : show(item.value),
+        })),
+        issues: t.issues.map((issue) => ({ ...issue })),
+    };
+}
+export function environmentRetention(environment) {
+    if (environment.topology)
+        return topologyRetention(environment.topology);
+    return { retention: "unknown", reason: "decided by the provider when it starts" };
+}

package/core/application/src/orchestration/lab/environments.d.ts

@@ -0,0 +1,74 @@
+import { type EnvironmentOption, type Topology, type TopologyIssue } from "@parity/product-lab/domain";
+import type { EnvironmentKind } from "@parity/product-lab/ports/driving";
+import type { EnvironmentOffer } from "../capabilities.js";
+import type { EnvironmentProvider, LabDefinition } from "./define.js";
+import { EnvironmentRegistry, type TopologyEnvironment } from "./environment-registry.js";
+import { type OptionsEnvironment } from "./environment-options.js";
+export { EnvironmentRegistry, type EnvironmentFactory, type TopologyEnvironment } from "./environment-registry.js";
+export { isTopology, topologyLabel } from "@parity/product-lab/domain";
+/** What `defineLab({ environments })` accepts per id: one environment, or its options (backlog 184). */
+export type LabEnvironmentEntry = EnvironmentProvider | Topology | OptionsEnvironment;
+export declare function isTopologyEnvironment(value: unknown): value is TopologyEnvironment;
+/** A lab environment entry resolved for reporting and starting. */
+export interface ResolvedEnvironment {
+    id: string;
+    label: string;
+    description?: string;
+    /** What kind of chain it is (`environmentKind`); undefined when neither declared nor readable. */
+    kind?: EnvironmentKind;
+    /** Declared offer: the provider's, or the topology's. */
+    offer: EnvironmentOffer;
+    /** Present for topology entries and for providers that serve a topology. */
+    topology?: Topology;
+    /** Undefined when the entry is a topology no registered adapter serves. */
+    provider?: EnvironmentProvider;
+    /** Why it cannot start (topology `error` issues, a missing adapter). Empty when startable. */
+    problems: string[];
+    /** Topology issues (errors, losses, notes); empty for plain providers. */
+    issues: TopologyIssue[];
+    /** Backlog 184: an environment with options, the ways it can run; `option` is the one resolved here. */
+    options?: EnvironmentOption[];
+    option?: string;
+}
+/** The lab's environment registry: the factories it registers and the system ports they get. */
+export declare function environmentRegistry(definition: LabDefinition): EnvironmentRegistry;
+/** The words a lab gives an environment of its own (`nameEnvironment`): what the chain picker and the banner say. */
+export interface EnvironmentWords {
+    /** Its plain name, for example "Fast local chain" or "Local copy of Paseo". */
+    readonly title?: string;
+    /** One line: what it is and why to choose it. */
+    readonly summary?: string;
+    /**
+     * What kind of chain it is, for an environment whose adapter does not say (a lab's own provider). Not `kind`: a
+     * topology's `kind` marks it as one.
+     */
+    readonly chainKind?: EnvironmentKind;
+}
+/**
+ * What kind of chain an environment is: the lab's word for it (`nameEnvironment`), else the live network for a public
+ * offer, else what its topology's adapter makes.
+ */
+export declare function environmentKind(words: EnvironmentWords, offer: EnvironmentOffer, topology: Topology | undefined): EnvironmentKind | undefined;
+/**
+ * Name an environment in the lab's own words (docs/feature-map.md, "Chains"): a topology or a provider keeps what it
+ * is and does, and the chain picker, the bottom bar and the environment card say `label` and `description` instead of
+ * the adapter's ("Relay-less people, bulletin"); the adapter's own description follows the lab's line. Returns the same
+ * entry, named.
+ */
+export declare function nameEnvironment<T extends object>(entry: T, words: {
+    label: string;
+    description?: string;
+    kind?: EnvironmentKind;
+}): T;
+/**
+ * Resolve one `environments` entry. Starts nothing. A topology entry gets its
+ * provider from the registered factory of its `provider` kind; a topology with
+ * `error` issues or without a factory is reported with `problems` and refuses
+ * to start (the returned provider, if any, still exists for reporting).
+ */
+export declare function resolveEnvironment(definition: LabDefinition, id: string, registry?: EnvironmentRegistry, option?: string): ResolvedEnvironment;
+export declare function resolveEnvironments(definition: LabDefinition): ResolvedEnvironment[];
+/** The topology's own explanation for a missing capability, when there is one. */
+export declare function missingCapabilityReason(environment: Pick<ResolvedEnvironment, "topology">, capability: string): string | undefined;
+/** Refuse before anything starts, naming every reason. */
+export declare function assertEnvironmentStartable(environment: ResolvedEnvironment): EnvironmentProvider;

package/core/application/src/orchestration/lab/environments.js

@@ -0,0 +1,98 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { isTopology, topologyLabel } from "@parity/product-lab/domain";
+import { capabilityReason } from "../topology.js";
+import { EnvironmentRegistry } from "./environment-registry.js";
+import { isOptionsEnvironment, optionOf, optionWords } from "./environment-options.js";
+export { EnvironmentRegistry } from "./environment-registry.js";
+export { isTopology, topologyLabel } from "@parity/product-lab/domain";
+export function isTopologyEnvironment(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        typeof value.start === "function" &&
+        isTopology(value.topology));
+}
+export function environmentRegistry(definition) {
+    return new EnvironmentRegistry(definition.environmentFactories ?? [], definition.system ?? {});
+}
+const TOPOLOGY_KINDS = { relayless: "fast-local", engine: "network-copy", chopsticks: "chain-copy" };
+export function environmentKind(words, offer, topology) {
+    return words.chainKind ?? (offer.public ? "live" : topology ? TOPOLOGY_KINDS[topology.provider] : undefined);
+}
+const joinWords = (lab, adapter) => [lab, adapter].filter(Boolean).join(". ") || undefined;
+export function nameEnvironment(entry, words) {
+    return Object.assign(entry, { title: words.label, ...(words.description ? { summary: words.description } : {}), ...(words.kind ? { chainKind: words.kind } : {}) });
+}
+export function resolveEnvironment(definition, id, registry = environmentRegistry(definition), option) {
+    const entry = definition.environments[id];
+    if (!entry)
+        throw new Error(`Unknown environment ${id}. Configured: ${Object.keys(definition.environments).join(", ") || "none"}`);
+    if (!isOptionsEnvironment(entry))
+        return resolveEntry(id, entry, registry);
+    const chosen = optionOf(id, entry, option);
+    const resolved = resolveEntry(id, chosen.environment, registry);
+    const words = entry;
+    const description = joinWords(joinWords(words.summary, chosen.description), resolved.description);
+    return {
+        ...resolved,
+        ...(words.title ? { label: words.title } : {}),
+        ...(description ? { description } : {}),
+        ...(words.chainKind ? { kind: words.chainKind } : {}),
+        options: optionWords(entry),
+        option: chosen.id,
+    };
+}
+function resolveEntry(id, entry, registry) {
+    if (isTopology(entry)) {
+        const problems = entry.issues.filter((issue) => issue.severity === "error").map((issue) => issue.message);
+        const unserved = registry.unserved(entry);
+        if (unserved)
+            problems.push(unserved);
+        problems.push(...registry.problems(entry));
+        const provider = registry.environment(entry);
+        const words = entry;
+        const description = joinWords(words.summary, provider?.description);
+        const kind = environmentKind(words, entry.offer, entry);
+        return {
+            id,
+            label: words.title ?? provider?.label ?? topologyLabel(entry),
+            ...(description ? { description } : {}),
+            ...(kind ? { kind } : {}),
+            offer: entry.offer,
+            topology: entry,
+            ...(provider ? { provider } : {}),
+            problems,
+            issues: entry.issues,
+        };
+    }
+    const topology = isTopologyEnvironment(entry) ? entry.topology : undefined;
+    const words = entry;
+    const description = joinWords(words.summary, entry.description);
+    const kind = environmentKind(words, entry.offer, topology);
+    return {
+        id,
+        label: words.title ?? entry.label ?? (topology ? topologyLabel(topology) : id),
+        ...(description ? { description } : {}),
+        ...(kind ? { kind } : {}),
+        offer: entry.offer,
+        ...(topology ? { topology } : {}),
+        provider: entry,
+        problems: topology ? [...topology.issues.filter((issue) => issue.severity === "error").map((issue) => issue.message), ...registry.problems(topology)] : [],
+        issues: topology?.issues ?? [],
+    };
+}
+export function resolveEnvironments(definition) {
+    const registry = environmentRegistry(definition);
+    return Object.keys(definition.environments).map((id) => resolveEnvironment(definition, id, registry));
+}
+export function missingCapabilityReason(environment, capability) {
+    const t = environment.topology;
+    if (!t || !(capability in t.capabilities))
+        return undefined;
+    return capabilityReason(t, capability);
+}
+export function assertEnvironmentStartable(environment) {
+    if (environment.problems.length || !environment.provider)
+        throw new Error(`Environment ${environment.id} cannot start:\n- ${environment.problems.join("\n- ")}`);
+    return environment.provider;
+}

package/core/application/src/orchestration/lab/holding-browsers.d.ts

@@ -0,0 +1,16 @@
+import { PreOnboardedActor, type WorkerHold } from "@parity/product-lab/domain";
+import type { BrowserLauncher } from "@parity/product-lab/ports/browser";
+import type { LabCatalog } from "@parity/product-lab/ports/lab";
+import type { LabDefinition } from "./define.js";
+/**
+ * Whether a lab's browsers hold each new worker while an environment runs (`workerHoldPolicy`): the lab config's
+ * switch, the environment's public network (its name, when it is one), its declared pre-onboarded identities and hosts.
+ */
+export declare function labWorkerHold(definition: Pick<LabDefinition, "workerHold" | "actors" | "hosts">, publicNetwork: string | undefined, preOnboarded?: readonly PreOnboardedActor[]): WorkerHold;
+/** What `catalog` says of holding worker starts while `environment` runs; off when there is no declared lab to ask. */
+export declare function workerHoldOf(catalog: Pick<LabCatalog, "workerHold"> | undefined, environment: string | undefined): WorkerHold;
+/**
+ * `launcher`, with the session's decision on holding each new worker (`workerHoldPolicy`) on every launch. Off wins:
+ * a launch can never open the debugging port the session decided against.
+ */
+export declare function holdingBrowsers(launcher: BrowserLauncher, hold: WorkerHold): BrowserLauncher;

package/core/application/src/orchestration/lab/holding-browsers.js

@@ -0,0 +1,18 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { PreOnboardedActor, workerHoldPolicy } from "@parity/product-lab/domain";
+export function labWorkerHold(definition, publicNetwork, 
+preOnboarded = definition.actors ? PreOnboardedActor.parseAll(definition.actors) : []) {
+    return workerHoldPolicy({
+        switchedOff: definition.workerHold === false,
+        ...(publicNetwork !== undefined ? { publicNetwork } : {}),
+        preOnboarded: preOnboarded.map((actor) => actor.name),
+        hostKinds: Object.values(definition.hosts ?? {}).flatMap((host) => (typeof host === "object" && host && "kind" in host && typeof host.kind === "string" ? [host.kind] : [])),
+    });
+}
+export function workerHoldOf(catalog, environment) {
+    return environment !== undefined && catalog?.workerHold ? catalog.workerHold(environment) : { off: "the lab declares no environments to decide by" };
+}
+export function holdingBrowsers(launcher, hold) {
+    return { ...(launcher.prerequisites ? { prerequisites: () => launcher.prerequisites() } : {}), launch: (options = {}) => launcher.launch({ ...options, holdWorkers: hold === true ? (options.holdWorkers ?? true) : hold }) };
+}

package/core/application/src/orchestration/lab/integration-availability.d.ts

@@ -0,0 +1,39 @@
+import { type IntegrationFailure, type IntegrationStatus } from "@parity/product-lab/domain";
+import type { EnvironmentOffer } from "../capabilities.js";
+import type { IntegrationRegistry } from "../integrations/integration-registry.js";
+import type { Topology } from "../topology.js";
+import type { LabDefinition } from "./define.js";
+export type { IntegrationFailure, IntegrationStatus } from "@parity/product-lab/domain";
+export interface IntegrationAvailability {
+    readonly integration: string;
+    readonly available: boolean;
+    readonly status: IntegrationStatus;
+    /** Empty when available (`idle` carries a note); otherwise names the missing requirement, unusable secret, failure or blocking dependency. */
+    readonly reason: string;
+    /** Error class of a failed service (`AuthorityError` for a rejected operator). */
+    readonly error?: string;
+    /** This integration's own missing requirements (dependencies report theirs). */
+    readonly missing: {
+        chains: string[];
+        services: string[];
+        capabilities: string[];
+    };
+    /** Direct dependencies that are not available. */
+    readonly blockedBy: string[];
+    /** Apps that use it (directly or through dependencies). */
+    readonly usedBy: string[];
+}
+export declare function integrationAvailability(definition: LabDefinition, environment: {
+    id: string;
+    offer: EnvironmentOffer;
+    topology?: Topology;
+}, options: {
+    registry?: IntegrationRegistry;
+    env: NodeJS.ProcessEnv;
+    /** Integrations whose environment services failed, with the error. */
+    failures?: ReadonlyMap<string, IntegrationFailure>;
+    /** Integrations the lab started in this generation. Omit for a static check. */
+    started?: ReadonlySet<string>;
+}): IntegrationAvailability[];
+/** Integrations an app uses that are not available, dependencies first. */
+export declare function blockingIntegrations(registry: IntegrationRegistry, integration: string | undefined, availability: readonly IntegrationAvailability[]): string[];

package/core/application/src/orchestration/lab/integration-availability.js

@@ -0,0 +1,51 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { IntegrationReadiness } from "@parity/product-lab/domain";
+import { SecretResolver } from "../secrets/secret-resolver.js";
+import { environmentRequirementCheck, labIntegrations, privilegedSecretProblems } from "./validate.js";
+export function integrationAvailability(definition, environment, options) {
+    const registry = options.registry ?? labIntegrations(definition);
+    const secrets = new SecretResolver(definition.secrets ?? {}, { id: environment.id, local: environment.offer.local }, options.env);
+    const usedBy = new Map();
+    for (const [app, config] of Object.entries(definition.apps ?? {})) {
+        const id = config?.integration?.id;
+        if (!id)
+            continue;
+        for (const member of registry.closure([id]))
+            usedBy.set(member, [...(usedBy.get(member) ?? []), app]);
+    }
+    const results = new Map();
+    const readiness = new Map();
+    const requirementCheck = environmentRequirementCheck(environment);
+    for (const id of registry.closure([...registry.integrations.keys()])) {
+        const integration = registry.integrations.get(id);
+        const check = requirementCheck.check(integration.requires ?? {}, environment.offer);
+        const problems = check.reason ? [check.reason] : [];
+        problems.push(...privilegedSecretProblems(registry, secrets, id));
+        const blockedBy = (integration.dependsOn ?? []).filter((dependency) => readiness.get(dependency)?.available === false);
+        const decided = new IntegrationReadiness({
+            problems,
+            blockedBy: blockedBy.map((dependency) => ({ integration: dependency, readiness: readiness.get(dependency) })),
+            ...(options.failures?.get(id) ? { failure: options.failures.get(id) } : {}),
+            ...(options.started ? { started: options.started.has(id) } : {}),
+        });
+        readiness.set(id, decided);
+        results.set(id, {
+            integration: id,
+            available: decided.available,
+            status: decided.status,
+            reason: decided.reason,
+            ...(decided.error ? { error: decided.error } : {}),
+            missing: { chains: [...check.missing.chains], services: [...check.missing.services], capabilities: [...check.missing.capabilities] },
+            blockedBy,
+            usedBy: usedBy.get(id) ?? [],
+        });
+    }
+    return [...registry.integrations.keys()].map((id) => results.get(id));
+}
+export function blockingIntegrations(registry, integration, availability) {
+    if (!integration)
+        return [];
+    const unavailable = new Set(availability.filter((item) => !item.available).map((item) => item.integration));
+    return registry.closure([integration]).filter((id) => unavailable.has(id));
+}

package/core/application/src/orchestration/lab/kept-placements.d.ts

@@ -0,0 +1,11 @@
+import type { SessionPlacements } from "@parity/product-lab/ports/host";
+import type { LabEnvironment } from "../types.js";
+export interface KeptPlacements {
+    /** The environment's `placeSessions`: kept, then given to the current session. */
+    place(next: SessionPlacements | undefined): Promise<void>;
+    /** A session just opened under the environment, given the kept placements when the window gave any. */
+    placed(opened: LabEnvironment): Promise<LabEnvironment>;
+    /** Whether the window placed the people now (ScenarioConditionContext.placed); set before the session moves them. */
+    isPlaced(): boolean;
+}
+export declare function keptPlacements(current: () => LabEnvironment): KeptPlacements;

package/core/application/src/orchestration/lab/kept-placements.js

@@ -0,0 +1,17 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function keptPlacements(current) {
+    let placements;
+    return {
+        async place(next) {
+            placements = next;
+            await current().placeSessions?.(next);
+        },
+        async placed(opened) {
+            if (placements)
+                await opened.placeSessions?.(placements);
+            return opened;
+        },
+        isPlaced: () => placements !== undefined,
+    };
+}

package/core/application/src/orchestration/lab/lab-rpc.d.ts

@@ -0,0 +1,30 @@
+import { RpcSelection } from "@parity/product-lab/domain";
+import type { EnvironmentRpcRequest, EnvironmentRpcView } from "@parity/product-lab/ports/driving";
+import type { EnvironmentProvider } from "@parity/product-lab/ports/environment";
+import type { RememberedRpc } from "@parity/product-lab/ports/storage";
+import type { LabDefinition } from "./define.js";
+/** Why `defineLab({ rpc })` is invalid; empty when valid. */
+export declare function labRpcErrors(definition: LabDefinition): string[];
+/**
+ * The selection a start of `environment` uses: lab.config's, the remembered one, then the requested one, checked
+ * against the provider's declaration. Undefined when nothing is chosen and the provider takes none. Throws naming every
+ * problem (never a secret's value) before anything starts.
+ */
+export declare function startRpc(definition: LabDefinition, environment: string, provider: EnvironmentProvider, choices: {
+    remembered?: RememberedRpc;
+    request?: EnvironmentRpcRequest;
+}, env: NodeJS.ProcessEnv): RpcSelection | undefined;
+/**
+ * Check a choice the lab window remembers for `environment`: plain URLs, chains its provider lists, and a reason (given
+ * now or in lab.config) when an `endpoint` RPC is off this machine and the environment is not a public target.
+ */
+export declare function rememberedRpcProblems(definition: LabDefinition, environment: string, request: EnvironmentRpcRequest): string[];
+/** What the lab window shows of `environment`'s RPC before a start (no secret value, no token). */
+export declare function rpcView(definition: LabDefinition, environment: string, remembered: RememberedRpc | undefined, env: NodeJS.ProcessEnv): EnvironmentRpcView | undefined;
+/**
+ * Every value of the lab's secret RPC URLs (`rpc.<environment>.chains.<chain>: fromEnv(…)`) that output never shows: the
+ * redactor removes them, so an endpoint, a provenance or a message naming such a URL keeps no token.
+ */
+export declare function rpcSecretValues(definition: Pick<LabDefinition, "rpc">, env: NodeJS.ProcessEnv): string[];
+/** `value` with every one of `secrets` (longest first, `rpcSecretValues`) replaced, in every string it holds (keys too). */
+export declare function withoutRpcSecrets<T>(value: T, secrets: readonly string[]): T;