@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/domain/src/lab/rpc-selection.js

@@ -0,0 +1,95 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { LoopbackUrl } from "../network/loopback-url.js";
+const ORDER = ["default", "lab.config", "remembered", "request"];
+const CHAIN = /^[a-z][a-z0-9-]{0,31}$/;
+const PROTOCOLS = ["ws:", "wss:", "http:", "https:"];
+const KEY_LIKE = /^[A-Za-z0-9_-]{24,}$/;
+export function rpcUrlProblem(url, field, options) {
+    if (typeof url !== "string" || !url.trim())
+        return `${field} must be a URL`;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return `${field} is not a URL`;
+    }
+    if (!PROTOCOLS.includes(parsed.protocol))
+        return `${field} must be a ws, wss, http or https URL`;
+    if (parsed.hash)
+        return `${field} must have no fragment`;
+    if (options.literal && (parsed.username || parsed.password || parsed.search))
+        return `${field} carries credentials (a user, password or query); declare that URL as a secret (fromEnv) instead of writing it`;
+    return undefined;
+}
+export function shownRpcUrl(url, secret = false) {
+    const parsed = new URL(url);
+    const token = secret || !!(parsed.username || parsed.password || parsed.search) || parsed.pathname.split("/").some((segment) => KEY_LIKE.test(segment));
+    return token ? `${parsed.protocol}//${parsed.host}` : url;
+}
+export function rpcLiteralErrors(value, owner) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [`${owner} must map chain ids to URLs`];
+    const errors = [];
+    for (const [chain, url] of Object.entries(value)) {
+        if (!CHAIN.test(chain))
+            errors.push(`${owner}: ${JSON.stringify(chain)} is not a chain id`);
+        const problem = rpcUrlProblem(url, `${owner}.${chain}`, { literal: true });
+        if (problem)
+            errors.push(problem);
+    }
+    return errors;
+}
+export class RpcSelection {
+    choices;
+    reason;
+    constructor(choices, 
+    reason) {
+        this.choices = choices;
+        this.reason = reason;
+        Object.freeze(this);
+    }
+    static empty = new RpcSelection(Object.freeze({}), undefined);
+    with(from, urls, options = {}) {
+        const next = { ...this.choices };
+        for (const [chain, url] of Object.entries(urls)) {
+            const current = next[chain];
+            if (current && ORDER.indexOf(current.from) > ORDER.indexOf(from))
+                continue;
+            next[chain] = { url, from, ...(options.secret?.includes(chain) ? { secret: true } : {}) };
+        }
+        const reason = options.reason?.trim() || this.reason;
+        return new RpcSelection(Object.freeze(next), reason);
+    }
+    get chains() {
+        return Object.keys(this.choices);
+    }
+    choice(chain) {
+        return this.choices[chain];
+    }
+    urls() {
+        return Object.fromEntries(Object.entries(this.choices).map(([chain, choice]) => [chain, choice.url]));
+    }
+    remote() {
+        return Object.entries(this.choices).filter(([, choice]) => !LoopbackUrl.test(choice.url)).map(([chain]) => chain);
+    }
+    problems(environment, declaration, options) {
+        const chosen = this.chains.filter((chain) => this.choices[chain].from !== "default");
+        if (!declaration)
+            return chosen.length ? [`Environment ${environment} takes no RPC of the lab's choice (rpc for ${chosen.join(", ")})`] : [];
+        const problems = chosen
+            .filter((chain) => !declaration.chains.includes(chain))
+            .map((chain) => `Environment ${environment} takes no RPC for ${chain}; it takes one for ${declaration.chains.join(", ")}`);
+        const remote = this.remote().filter((chain) => this.choices[chain].from !== "default");
+        if (declaration.role === "endpoint" && remote.length && !options.publicTarget && !this.reason)
+            problems.push(`Environment ${environment} would use RPC off this machine for ${remote.join(", ")}: give a reason (rpc reason, why the lab may use a public node); the lab never treats a remote RPC as local`);
+        return problems;
+    }
+    view() {
+        return Object.fromEntries(Object.entries(this.choices).map(([chain, choice]) => [
+            chain,
+            { url: shownRpcUrl(choice.url, choice.secret), from: choice.from, remote: !LoopbackUrl.test(choice.url), ...(choice.secret ? { secret: true } : {}) },
+        ]));
+    }
+}

package/core/domain/src/lab/run-manifest.d.ts

@@ -0,0 +1,36 @@
+import type { ForkSnapshot } from "../versions/fork-snapshot.js";
+import type { Topology } from "./topology.js";
+/** Data recorded for a run, with sensitive topology options already redacted. */
+export interface RunManifest {
+    kind: "product-lab-run-manifest";
+    schemaVersion: 1;
+    createdAt: string;
+    runId?: string;
+    environment?: string;
+    forkSnapshot?: ForkSnapshot;
+    profile: string;
+    label: "standard" | "custom";
+    customizations: Topology["customizations"];
+    topology: Topology;
+    /** Provider-resolved launch plan (commands, arguments, files), when known. */
+    plan?: unknown;
+    extra?: Record<string, unknown>;
+}
+/** What a run manifest records besides the topology. */
+export interface RunManifestOptions {
+    runId?: string;
+    environment?: string;
+    forkSnapshot?: ForkSnapshot;
+    plan?: unknown;
+    extra?: Record<string, unknown>;
+}
+/** Build a manifest from caller-owned time; the domain never reads the clock. */
+export declare function createRunManifest(topology: Topology, createdAt: string, options?: RunManifestOptions): RunManifest;
+/**
+ * `createRunManifest` with the time as a `Date` (`clock.date()`): the `@parity/product-lab` compatibility name.
+ * Every customization is recorded so a customized run is never mistaken for a standard one; sensitive values are
+ * redacted. `now` is required: the domain never reads the clock.
+ */
+export declare function runManifest(topology: Topology, options: RunManifestOptions & {
+    now: Date;
+}): RunManifest;

package/core/domain/src/lab/run-manifest.js

@@ -0,0 +1,24 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { redactedTopology } from "./topology-functions.js";
+export function createRunManifest(topology, createdAt, options = {}) {
+    const shown = redactedTopology(topology);
+    return {
+        kind: "product-lab-run-manifest",
+        schemaVersion: 1,
+        createdAt,
+        ...(options.runId ? { runId: options.runId } : {}),
+        ...(options.environment ? { environment: options.environment } : {}),
+        ...(options.forkSnapshot ? { forkSnapshot: options.forkSnapshot } : {}),
+        profile: topology.profile,
+        label: topology.label,
+        customizations: shown.customizations,
+        topology: shown,
+        ...(options.plan !== undefined ? { plan: options.plan } : {}),
+        ...(options.extra ? { extra: options.extra } : {}),
+    };
+}
+export function runManifest(topology, options) {
+    const { now, ...rest } = options;
+    return createRunManifest(topology, now.toISOString(), rest);
+}

package/core/domain/src/lab/running-lab.d.ts

@@ -0,0 +1,6 @@
+/** Why a start beside the lab another process runs in this folder is refused, naming its window and what to do. */
+export declare function besideRunningLab(running: {
+    readonly window: string;
+    readonly lab: string;
+    readonly pid?: number;
+}): string;

package/core/domain/src/lab/running-lab.js

@@ -0,0 +1,5 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function besideRunningLab(running) {
+    return `The lab window at ${running.window} is already running this lab (${running.lab}${running.pid !== undefined ? `, process ${running.pid}` : ""}): starting here would start a second lab on the same kept chain and ports. Use that window, or stop it (Ctrl-C in its terminal) and start again.`;
+}

package/core/domain/src/lab/runtime-wire.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The lab's live calls an attached process makes on the window's runtime, by LabRuntime method name: what reads or
+ * changes the running environment, its people and its runs. Anything else (the declarations, the lab's files) the
+ * attached process reads itself from the same lab folder. Runs started here are kept by the window, which shows them.
+ */
+export declare const ATTACHED_RUNTIME_CALLS: readonly ["environmentState", "snapshot", "registry", "startEnvironment", "stopEnvironment", "switchEnvironment", "resetEnvironment", "allowRootCalls", "chooseEnvironmentOption", "observe", "createActor", "openPreOnboarded", "manageActor", "pause", "continue", "cancel", "inspectPause", "checkTransactions", "checkTransaction", "evidence", "stepEvidence", "explainFailure", "chainConsole", "recordings", "recording", "runStepHealth", "fixtures"];
+export type AttachedRuntimeCall = (typeof ATTACHED_RUNTIME_CALLS)[number];
+/** JSON for the wire: a bigint (balances, block values) crosses as `{ "$bigint": "<digits>" }` and comes back a bigint. */
+export declare function toWire(value: unknown): string;
+/** The value `toWire` sent. */
+export declare function fromWire<T = unknown>(text: string): T;
+/** A runtime error as it crosses: its class name, its words and its own fields. */
+export interface WireError {
+    readonly name: string;
+    readonly message: string;
+    readonly fields?: Readonly<Record<string, unknown>>;
+}
+/** An error thrown by the window's runtime, for the attached process. */
+export declare function encodeRuntimeError(error: unknown): WireError;
+/** The error the window's runtime threw, as its own class when it is one callers branch on, else a plain Error. */
+export declare function decodeRuntimeError(wire: WireError): Error;

package/core/domain/src/lab/runtime-wire.js

@@ -0,0 +1,87 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { FixtureImportIncompleteError } from "../fixtures/fixture-import-incomplete-error.js";
+import { DemoRefusedError } from "../recordings/demo-refused-error.js";
+import { RecordingNotFoundError } from "../recordings/recording-not-found-error.js";
+import { RunBundleRefusedError } from "../runs/run-bundle-refused-error.js";
+import { ScenarioInputError } from "../runs/scenario-input-error.js";
+import { PendingCheckError } from "../shared/pending-check-error.js";
+import { UnsupportedCapabilityError } from "../shared/unsupported-capability-error.js";
+import { ConfirmationRequiredError } from "./confirmation-required-error.js";
+import { EnvironmentRequestError } from "./environment-request-error.js";
+import { LabConfigurationError } from "./lab-configuration-error.js";
+export const ATTACHED_RUNTIME_CALLS = [
+    "environmentState",
+    "snapshot",
+    "registry",
+    "startEnvironment",
+    "stopEnvironment",
+    "switchEnvironment",
+    "resetEnvironment",
+    "allowRootCalls",
+    "chooseEnvironmentOption",
+    "observe",
+    "createActor",
+    "openPreOnboarded",
+    "manageActor",
+    "pause",
+    "continue",
+    "cancel",
+    "inspectPause",
+    "checkTransactions",
+    "checkTransaction",
+    "evidence",
+    "stepEvidence",
+    "explainFailure",
+    "chainConsole",
+    "recordings",
+    "recording",
+    "runStepHealth",
+    "fixtures",
+];
+export function toWire(value) {
+    return JSON.stringify(value, (_, item) => (typeof item === "bigint" ? { $bigint: item.toString() } : item));
+}
+export function fromWire(text) {
+    return JSON.parse(text, (_, item) => (item && typeof item === "object" && Object.keys(item).length === 1 && typeof item.$bigint === "string" ? BigInt(item.$bigint) : item));
+}
+export function encodeRuntimeError(error) {
+    if (!(error instanceof Error))
+        return { name: "Error", message: String(error) };
+    const fields = Object.fromEntries(Object.entries(error).filter(([key, value]) => key !== "name" && key !== "message" && key !== "stack" && key !== "cause" && isPlain(value)));
+    return { name: error.name, message: error.message, ...(Object.keys(fields).length ? { fields } : {}) };
+}
+export function decodeRuntimeError(wire) {
+    const field = (key) => wire.fields?.[key];
+    switch (wire.name) {
+        case "EnvironmentRequestError":
+            return new EnvironmentRequestError(wire.message);
+        case "ConfirmationRequiredError":
+            return new ConfirmationRequiredError(field("action"), wire.message);
+        case "ScenarioInputError":
+            return new ScenarioInputError(field("code"), wire.message, field("input"));
+        case "PendingCheckError":
+            return new PendingCheckError(wire.message, field("identity"));
+        case "RecordingNotFoundError":
+            return new RecordingNotFoundError(wire.message);
+        case "UnsupportedCapabilityError":
+            return new UnsupportedCapabilityError(field("capability"));
+        case "DemoRefusedError":
+            return new DemoRefusedError(wire.message, field("code"));
+        case "RunBundleRefusedError":
+            return new RunBundleRefusedError(field("bundle"), field("problems") ?? []);
+        case "FixtureImportIncompleteError":
+            return Object.assign(new FixtureImportIncompleteError(field("fixture"), undefined), { message: wire.message });
+        case "LabConfigurationError":
+            return new LabConfigurationError(field("problems") ?? []);
+        default:
+            return Object.assign(new Error(wire.message), { name: wire.name });
+    }
+}
+function isPlain(value) {
+    if (value === null || ["string", "number", "boolean"].includes(typeof value))
+        return true;
+    if (Array.isArray(value))
+        return value.every(isPlain);
+    return typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype && Object.values(value).every(isPlain);
+}

package/core/domain/src/lab/topology-error.d.ts

@@ -0,0 +1,5 @@
+import type { TopologyIssue } from "./topology.js";
+export declare class TopologyError extends Error {
+    readonly issues: TopologyIssue[];
+    constructor(issues: TopologyIssue[]);
+}

package/core/domain/src/lab/topology-error.js

@@ -0,0 +1,10 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class TopologyError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Topology cannot start:\n${issues.map((issue) => `- ${issue.message}`).join("\n")}`);
+        this.issues = issues;
+        this.name = "TopologyError";
+    }
+}

package/core/domain/src/lab/topology-functions.d.ts

@@ -0,0 +1,66 @@
+import { type Capability } from "./capability.js";
+import { CapabilityPolicy } from "./capability-policy.js";
+import type { AppRequirements } from "./requirements.js";
+import { type Topology, type TopologyChain, type TopologyEndpoints, type TopologyOffer } from "./topology.js";
+import { EnvironmentEndpoints } from "../network/environment-endpoints.js";
+/** Why a capability is absent when the adapter adds nothing: which chain or service it needs. */
+export declare function defaultCapabilityReason(capability: Capability, chains: readonly TopologyChain[]): string;
+/** A reason for every absent capability: the adapter's own, else the default. */
+export declare function capabilityReasons(capabilities: Readonly<Record<Capability, boolean>>, chains: readonly TopologyChain[], own?: (capability: Capability) => string | undefined): Partial<Record<Capability, string>>;
+/** Why a capability is absent, naming the chain, service or mode that removes it (the adapter's reason). */
+export declare function capabilityReason(t: Topology, capability: Capability): string | undefined;
+/** A local topology's offer: its chains and services, and the capabilities it has. */
+export declare function topologyOffer(chains: TopologyChain[], services: string[], capabilities: Readonly<Record<Capability, boolean>>): TopologyOffer;
+/** What an app requires (the domain's `AppRequirements`). */
+export type AppRequirementsInput = AppRequirements;
+/** Whether an app can run on this topology, with a reason per missing item (the domain's RequirementCheck, worded for `env show`). */
+export declare function topologyAvailability(t: Topology, requires: AppRequirementsInput): {
+    available: boolean;
+    reasons: string[];
+};
+/** Topology issues plus one `unavailable` entry per app whose requirements it misses. */
+export declare function validateTopology(t: Topology, apps?: readonly {
+    name: string;
+    requires?: AppRequirementsInput;
+}[]): {
+    startable: boolean;
+    issues: import("@parity/product-lab").TopologyIssue[];
+    unavailable: {
+        app: string;
+        reasons: string[];
+    }[];
+};
+/** Throw before starting anything when the topology has an `error` issue. */
+export declare function assertStartable<T extends Topology>(t: T): T;
+/** What a manifest shows in place of a value an adapter marked `sensitive`. */
+export declare const REDACTED = "[redacted]";
+/**
+ * The topology as reports may carry it: every customization its adapter marked
+ * `sensitive` has its values replaced (keys kept), in `customizations` and at the
+ * same option path in the topology and in its `options`. Run manifests, `env show --json`, MCP
+ * `env_show` and files written with `--manifest` all go through this.
+ */
+export declare function redactedTopology(t: Topology): Topology;
+/** The endpoints a running (or planned) environment exposes, guarded by its capabilities (the domain's `EnvironmentEndpoints`). */
+export type EnvironmentAccess = EnvironmentEndpoints<TopologyChain>;
+export declare function environmentAccess(source: {
+    capabilities: Record<Capability, boolean> | CapabilityPolicy;
+    endpoints: TopologyEndpoints;
+    reason?: (capability: Capability) => string | undefined;
+}): EnvironmentAccess;
+/** Planned endpoints and capabilities of a resolved topology. */
+export declare function topologyAccess(t: Topology): EnvironmentAccess;
+/** Human-readable resolution for `product-lab env show`. */
+export declare function describeTopology(t: Topology, options?: {
+    name?: string;
+    apps?: readonly {
+        name: string;
+        requires?: AppRequirementsInput;
+    }[];
+}): string;
+/**
+ * The same topology with `withheld` capabilities taken away (backlog A6): to rehearse, on a local environment, a target
+ * that lacks them (a public network gives no `devAuthority`). Work that needs one is then refused up front, as it would
+ * be there. The offer, the capability reasons, the customizations and a note say so; nothing else changes.
+ */
+export declare function withholdCapabilities(t: Topology, withheld: readonly Capability[], reason: string): Topology;

package/core/domain/src/lab/topology-functions.js

@@ -0,0 +1,159 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { CAPABILITIES, isCapability } from "./capability.js";
+import { CapabilityPolicy } from "./capability-policy.js";
+import { RequirementCheck } from "./requirement-check.js";
+import { describeState } from "./topology.js";
+import { TopologyError } from "./topology-error.js";
+import { EnvironmentEndpoints } from "../network/environment-endpoints.js";
+export function defaultCapabilityReason(capability, chains) {
+    const hub = chains.includes("asset-hub");
+    switch (capability) {
+        case "contracts":
+            return "needs asset-hub (pallet-revive)";
+        case "evm":
+            return hub ? "needs the eth-rpc service (services.ethRpc)" : "needs asset-hub and the eth-rpc service";
+        case "dotns":
+            return "needs asset-hub with DotNS contracts";
+        case "bulletin":
+            return "needs the bulletin chain";
+        case "statementStore":
+            return chains.includes("people") ? "People runs without --enable-statement-store (statementStore: false)" : "needs people with the statement store";
+        case "devAuthority":
+            return "no development authority in this environment";
+    }
+}
+export function capabilityReasons(capabilities, chains, own = () => undefined) {
+    const reasons = {};
+    for (const capability of CAPABILITIES)
+        if (!capabilities[capability])
+            reasons[capability] = own(capability) ?? defaultCapabilityReason(capability, chains);
+    return reasons;
+}
+export function capabilityReason(t, capability) {
+    if (t.capabilities[capability])
+        return undefined;
+    return t.capabilityReasons?.[capability] ?? defaultCapabilityReason(capability, t.chains);
+}
+export function topologyOffer(chains, services, capabilities) {
+    return { chains, services, capabilities: CapabilityPolicy.fromRecord(capabilities, { local: true }).offered(), local: true };
+}
+export function topologyAvailability(t, requires) {
+    const missing = new RequirementCheck().missing(requires, t.offer);
+    const reasons = [
+        ...missing.chains.map((id) => `chain ${id} is not in this topology`),
+        ...missing.services.map((name) => `service ${name} is not running`),
+        ...missing.capabilities.map((capability) => `capability ${capability}: ${isCapability(capability) ? capabilityReason(t, capability) : `unknown capability (known: ${CAPABILITIES.join(", ")})`}`),
+    ];
+    return { available: reasons.length === 0, reasons };
+}
+export function validateTopology(t, apps = []) {
+    const unavailable = apps.flatMap((app) => {
+        const result = topologyAvailability(t, app.requires ?? {});
+        return result.available ? [] : [{ app: app.name, reasons: result.reasons }];
+    });
+    return {
+        startable: !t.issues.some((issue) => issue.severity === "error"),
+        issues: t.issues,
+        unavailable,
+    };
+}
+export function assertStartable(t) {
+    const errors = t.issues.filter((issue) => issue.severity === "error");
+    if (errors.length)
+        throw new TopologyError(errors);
+    return t;
+}
+export const REDACTED = "[redacted]";
+function redactValue(value) {
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, redactValue(inner)]));
+    return REDACTED;
+}
+function redactPath(target, path) {
+    if (!path.length || !target || typeof target !== "object" || Array.isArray(target))
+        return target;
+    const [head, ...rest] = path;
+    if (!(head in target))
+        return target;
+    const inner = target[head];
+    return { ...target, [head]: rest.length ? redactPath(inner, rest) : redactValue(inner) };
+}
+export function redactedTopology(t) {
+    let copy = { ...t, customizations: t.customizations.map((item) => (item.sensitive ? { ...item, value: redactValue(item.value) } : item)) };
+    for (const item of t.customizations)
+        if (item.sensitive) {
+            const path = item.option.split(".");
+            copy = redactPath(copy, path);
+            copy = { ...copy, options: redactPath(copy.options, path) };
+        }
+    return copy;
+}
+export function environmentAccess(source) {
+    return new EnvironmentEndpoints(source);
+}
+export function topologyAccess(t) {
+    return environmentAccess({
+        capabilities: t.capabilities,
+        endpoints: t.endpoints,
+        reason: (capability) => capabilityReason(t, capability),
+    });
+}
+export function describeTopology(t, options = {}) {
+    const lines = [];
+    const line = (label, value) => lines.push(`  ${label.padEnd(12)} ${value}`);
+    lines.push(`${options.name ? `${options.name}: ` : ""}${t.profile} (${t.label}) via ${t.provider}`);
+    line("network", t.network);
+    line("relay", t.presentation.relay);
+    line("state", t.presentation.state ?? describeState(t.state));
+    for (const detail of t.presentation.details ?? [])
+        line(detail.label, detail.value);
+    for (const id of t.chains) {
+        const endpoint = t.endpoints.chains[id];
+        const extras = [
+            t.runtimes[id] !== undefined ? `runtime ${JSON.stringify(t.runtimes[id])}` : undefined,
+            t.blockTime[id] ? `block ${t.blockTime[id]} ms` : undefined,
+            t.nodeArgs[id] ? `args ${t.nodeArgs[id].join(" ")}` : undefined,
+            t.genesisEdits[id] ? `genesis edits ${JSON.stringify(t.genesisEdits[id])}` : undefined,
+        ].filter(Boolean);
+        line("chain", `${id.padEnd(13)} ${endpoint.ws}${extras.length ? `  ${extras.join(", ")}` : ""}`);
+    }
+    line("services", Object.entries(t.endpoints.services).map(([name, url]) => `${name} ${url}`).join(", ") || "none");
+    line("binaries", Object.entries(t.binaries).map(([name, source]) => `${name} ${JSON.stringify(source)}`).join(", ") || t.presentation.binaries);
+    line("capabilities", CAPABILITIES.map((item) => `${t.capabilities[item] ? "+" : "-"}${item}`).join(" "));
+    for (const capability of CAPABILITIES) {
+        const reason = capabilityReason(t, capability);
+        if (reason)
+            lines.push(`    -${capability}: ${reason}`);
+    }
+    line("customized", t.customizations.length ? t.customizations.map((item) => item.option).join(", ") : "nothing (standard profile)");
+    const validation = validateTopology(t, options.apps);
+    for (const issue of validation.issues)
+        line(issue.severity, issue.message);
+    for (const app of validation.unavailable)
+        line("unavailable", `${app.app}: ${app.reasons.join("; ")}`);
+    line("startable", validation.startable ? "yes" : "no");
+    return lines.join("\n");
+}
+export function withholdCapabilities(t, withheld, reason) {
+    const unknown = withheld.filter((capability) => !isCapability(capability));
+    if (unknown.length)
+        throw new Error(`Cannot withhold unknown capabilities: ${unknown.join(", ")}`);
+    if (!reason.trim())
+        throw new Error("Withholding capabilities needs a reason");
+    const capabilities = { ...t.capabilities };
+    const capabilityReasons = { ...t.capabilityReasons };
+    for (const capability of withheld) {
+        capabilities[capability] = false;
+        capabilityReasons[capability] = `withheld by the lab: ${reason.trim()}`;
+    }
+    return {
+        ...t,
+        label: "custom",
+        capabilities,
+        capabilityReasons,
+        offer: { ...t.offer, capabilities: t.offer.capabilities?.filter((capability) => !withheld.includes(capability)) ?? [] },
+        customizations: [...t.customizations, { option: "withheld", value: [...withheld] }],
+        issues: [...t.issues, { severity: "note", code: "capabilities-withheld", message: `Withheld ${withheld.join(", ")}: ${reason.trim()}` }],
+    };
+}

package/core/domain/src/lab/topology-issues.d.ts

@@ -0,0 +1,16 @@
+import { type TopologyChain, type TopologyIssue, type TopologyNetwork, type TopologyOptions } from "./topology.js";
+export declare class TopologyIssues {
+    #private;
+    error(code: string, message: string): void;
+    loss(code: string, message: string): void;
+    note(code: string, message: string): void;
+    get list(): TopologyIssue[];
+    /** Every chain must be one the network declares. */
+    chainsInNetwork(network: TopologyNetwork, chains: readonly TopologyChain[]): void;
+    /** Services and the statement store need their chains. */
+    serviceChains(input: Pick<TopologyOptions, "services" | "statementStore">, chains: readonly TopologyChain[]): void;
+    /** The statement store is People's. */
+    statementStoreChains(input: Pick<TopologyOptions, "statementStore">, chains: readonly TopologyChain[]): void;
+    /** Two uses of one port (`uses`: port and what uses it, in order). */
+    portConflicts(uses: Iterable<readonly [number, string]>): void;
+}

package/core/domain/src/lab/topology-issues.js

@@ -0,0 +1,45 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { NETWORK_CHAINS } from "./topology.js";
+export class TopologyIssues {
+    #issues = [];
+    error(code, message) {
+        this.#issues.push({ severity: "error", code, message });
+    }
+    loss(code, message) {
+        this.#issues.push({ severity: "loss", code, message });
+    }
+    note(code, message) {
+        this.#issues.push({ severity: "note", code, message });
+    }
+    get list() {
+        return [...this.#issues];
+    }
+    chainsInNetwork(network, chains) {
+        const declared = NETWORK_CHAINS[network];
+        for (const id of chains)
+            if (!declared.includes(id))
+                this.error("chain-not-in-network", `${network} has no ${id} parachain (it declares ${declared.join(", ")})`);
+    }
+    serviceChains(input, chains) {
+        const has = (id) => chains.includes(id);
+        if (input.services?.identityBackend && !(has("people") && has("asset-hub")))
+            this.error("identity-backend-chains", "the identity backend needs people and asset-hub");
+        if (input.services?.ethRpc && !has("asset-hub"))
+            this.error("eth-rpc-chains", "eth-rpc needs asset-hub");
+        this.statementStoreChains(input, chains);
+    }
+    statementStoreChains(input, chains) {
+        if (input.statementStore && !chains.includes("people"))
+            this.error("statement-store-chains", "statementStore needs people");
+    }
+    portConflicts(uses) {
+        const bound = new Map();
+        for (const [port, label] of uses) {
+            const other = bound.get(port);
+            if (other)
+                this.error("port-conflict", `port ${port} is used by both ${other} and ${label}`);
+            bound.set(port, label);
+        }
+    }
+}