@parity/product-lab 0.0.1-placeholder → 0.1.0

package/composition/src/deployed-app-server.d.ts

@@ -0,0 +1,36 @@
+import { AppDeployedSource, AppDevServer, type AppDevServerDeclaration } from "@parity/product-lab/domain/apps";
+export interface DeployedAppPlan {
+    readonly source: AppDeployedSource;
+    /** The app server: the gateway program, as `serveApp` starts a dev server. */
+    readonly server: AppDevServer;
+    /** The same as a declaration (`apps.<id>.devServer`'s shape), for a lab's own sessions that serve apps themselves. */
+    readonly declaration: AppDevServerDeclaration;
+    /** The product id the deployed bundle carries: its name. */
+    readonly productId: string;
+    /** The IPFS gateway it may fall back to (`url`), and why or why not. */
+    readonly ipfsGateway: {
+        readonly url?: string;
+        readonly reason: string;
+    };
+    /** Where the gateway writes what it served (`GatewayReport`: CID, source, every file's digest). */
+    readonly report: string;
+    /** What the session says as it starts the app's server. */
+    readonly starting: string;
+    /** What the session says once it serves: the CID, the source that answered and the file count, from the report. */
+    served(url: string): string;
+}
+/**
+ * Plan app `app`'s deployed source on an environment: its chains' addresses (`endpoints`), and the public network it is
+ * on, when it is one. Throws naming what is missing.
+ */
+export declare function deployedAppServer(app: string, declared: unknown, environment: {
+    readonly id: string;
+    readonly endpoints?: Readonly<Record<string, string>>;
+    readonly public?: {
+        readonly network?: string;
+    };
+}, report: string): DeployedAppPlan;
+/** The launches the lab's default session does (`app.launch`); deployed-local builds with Vite (deployed-local-app.ts, backlog 200). */
+export declare const DEFAULT_SESSION_LAUNCHES: readonly ["dev", "deployed-local", "deployed"];
+/** A launch the default session cannot do, refused by name before anything starts: never served from the dev server instead. */
+export declare function refuseLaunches(apps: readonly (readonly [string, unknown])[]): void;

package/composition/src/deployed-app-server.js

@@ -0,0 +1,62 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readFileSync } from "node:fs";
+import { gatewayCommand } from "@parity/product-lab/deploy-bulletin";
+import { AppDeployedSource, AppDevServer } from "@parity/product-lab/domain/apps";
+import { siblingModule } from "@parity/product-lab/domain/shared";
+const GATEWAY = siblingModule("./gateway-program.ts", import.meta.url).pathname;
+const DEPLOYED_START_TIMEOUT_MS = 180_000;
+export function deployedAppServer(app, declared, environment, report) {
+    const source = AppDeployedSource.parse(app, declared);
+    const endpoints = environment.endpoints ?? {};
+    const has = Object.keys(endpoints).join(", ") || "none";
+    const assetHub = endpoints["asset-hub"];
+    const bulletin = endpoints.bulletin;
+    if (!assetHub && !source.resolveOn)
+        throw new Error(`apps.${app}.deployed resolves ${source.name} on the environment's Asset Hub, and environment ${environment.id} has none (its chains: ${has})`);
+    if (!bulletin)
+        throw new Error(`apps.${app}.deployed reads ${source.name}'s content from the environment's Bulletin, and environment ${environment.id} has none (its chains: ${has})`);
+    const network = environment.public?.network;
+    const elsewhere = source.networkProblem(network);
+    if (elsewhere)
+        throw new Error(`apps.${app}.deployed: ${elsewhere}`);
+    const ipfsGateway = source.ipfsGateway({ ...(network ? { network } : {}), public: environment.public !== undefined });
+    const { args } = gatewayCommand({
+        script: GATEWAY,
+        node: "node",
+        bulletin,
+        ...(assetHub ? { assetHub } : {}),
+        name: source.name,
+        ...(source.cid ? { cid: source.cid } : {}),
+        report,
+        ...(environment.public ? { allowPublic: true } : {}),
+        ...(ipfsGateway.url ? { ipfsGateway: ipfsGateway.url } : {}),
+        ...(source.resolveOn ? { resolveAssetHub: source.resolveOn, allowPublicResolve: true } : {}),
+    })("{port}");
+    const declaration = { command: "node", args, readyPath: "/.product-lab/gateway.json", startTimeoutMs: DEPLOYED_START_TIMEOUT_MS, updates: "none" };
+    const server = AppDevServer.parse(app, declaration);
+    const resolvedOn = source.resolveOn ? `${source.resolveOn} (apps.${app}.deployed.resolveOn: read-only, public contact)` : assetHub;
+    const fallback = ipfsGateway.url ? `, else ${ipfsGateway.url} (${ipfsGateway.reason})` : ` (IPFS gateway: ${ipfsGateway.reason})`;
+    return {
+        source,
+        server,
+        declaration,
+        productId: source.name,
+        ipfsGateway,
+        report,
+        starting: `Serving ${app} from ${source.name}${source.cid ? ` pinned to ${source.cid}` : ""}: resolved as hosts do (app.${source.name}, else ${source.name}) on ${resolvedOn}, read from ${bulletin}${fallback}`,
+        served: (url) => {
+            const read = JSON.parse(readFileSync(report, "utf8"));
+            const from = read.source ? `${read.source.endpoint}${read.source.fallbackReason ? ` (Bulletin did not answer: ${read.source.fallbackReason})` : ""}` : bulletin;
+            const resolved = read.name && read.name !== source.name ? `${read.name}, the app of ${source.name}` : source.name;
+            const where = read.publicRead ? `, resolved on ${read.publicRead.endpoint} at #${read.publicRead.block.number ?? "?"} ${read.publicRead.block.hash}${read.publicRead.pin ? ", the pin matched" : ""}` : "";
+            return `Serving ${app} on ${url}: ${Object.keys(read.files).length} files of ${read.cid} (${resolved}, contenthash ${read.contenthash ?? "none"}${where}) read from ${from}; digests in ${report}`;
+        },
+    };
+}
+export const DEFAULT_SESSION_LAUNCHES = ["dev", "deployed-local", "deployed"];
+export function refuseLaunches(apps) {
+    for (const [id, launch] of apps)
+        if (launch !== undefined && !DEFAULT_SESSION_LAUNCHES.includes(launch))
+            throw new Error(`${id} launches ${String(launch)} (app: { launch: "${String(launch)}" } in lab.config.ts), which the lab's default session cannot do yet: it does ${DEFAULT_SESSION_LAUNCHES.join(" and ")}. Give it a session of the lab's own (advanced.sessions), or write app: { launch: "dev" }`);
+}

package/composition/src/deployed-local-app.d.ts

@@ -0,0 +1,30 @@
+import type { AppDevServer, AppDevServerInputs } from "@parity/product-lab/domain";
+import type { Clock, CommandRunner, EnvironmentVariables, FileSystem, IdGenerator, JsonRpcClient, ProcessRunner } from "@parity/product-lab/ports/system";
+/** Refuse, by name, a deployed-local app the default session cannot build: its dev server is not Vite. */
+export declare function refuseUnbuildable(app: string, devServer: AppDevServer): void;
+export interface DeployLocalAppRequest {
+    readonly app: string;
+    readonly devServer: AppDevServer;
+    /** The lab's directory (a relative dev server command and cwd are relative to it). */
+    readonly root: string;
+    readonly runDir: string;
+    /** The environment's chain addresses (People, Asset Hub, Bulletin and DotNS come from here). */
+    readonly endpoints: Readonly<Record<string, string>>;
+    /** Each chain's genesis, as the dev server's settings name it. */
+    readonly chains: AppDevServerInputs["chains"];
+    readonly system: {
+        processes: ProcessRunner;
+        commands: CommandRunner;
+        files: FileSystem;
+        clock: Clock;
+        ids: IdGenerator;
+        environment: EnvironmentVariables;
+        rpc: JsonRpcClient;
+    };
+    readonly signal?: AbortSignal;
+}
+/** Build, deploy and read back `request.app` on the environment; returns the name it was deployed under and its CID. */
+export declare function deployLocalApp(request: DeployLocalAppRequest): Promise<{
+    name: string;
+    cid: string;
+}>;

package/composition/src/deployed-local-app.js

@@ -0,0 +1,48 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { join } from "node:path";
+import { BulletinDeployer, DeployedLocalLauncher, platformEndpoints } from "@parity/product-lab/deploy-bulletin";
+import { siblingModule } from "@parity/product-lab/domain/shared";
+import { LsofConnectionMonitor, WebSocketJsonRpcClient } from "@parity/product-lab/system-node";
+const GATEWAY = siblingModule("./gateway-program.ts", import.meta.url).pathname;
+const BUILD_TIMEOUT_MS = 300_000;
+export function refuseUnbuildable(app, devServer) {
+    if (devServer.command.split("/").pop() !== "vite")
+        throw new Error(`${app} launches deployed-local, which the lab's default session builds with Vite (vite build), and its dev server is ${devServer.command}. Use the dev launch (app: { launch: "dev" }), or a session of the lab's own (advanced.sessions) that builds it`);
+}
+export async function deployLocalApp(request) {
+    const { app, system } = request;
+    refuseUnbuildable(app, request.devServer);
+    const endpoints = platformEndpoints(request.endpoints);
+    const deployer = new BulletinDeployer(endpoints, {
+        processes: system.processes,
+        files: system.files,
+        clock: system.clock,
+        environment: system.environment,
+        rpc: system.rpc,
+        contentRpc: new WebSocketJsonRpcClient(),
+        connections: new LsofConnectionMonitor(),
+    });
+    const launcher = new DeployedLocalLauncher(deployer, endpoints, { clock: system.clock, ids: system.ids }, { gatewayScript: GATEWAY });
+    const deployment = await launcher.prepare({
+        runDir: join(request.runDir, `deployed-local-${app}`),
+        labelPrefix: `lab${app.toLowerCase().replace(/[^a-z0-9]/g, "")}`.slice(0, 20),
+        build: async (outDir, productId) => {
+            const plan = request.devServer.plan({ port: 0, productId, chains: request.chains, endpoints: request.endpoints });
+            const result = await system.commands.run({
+                command: plan.command.includes("/") ? join(request.root, plan.command) : plan.command,
+                args: ["build", "--outDir", outDir, "--emptyOutDir", "--base", "./", "--logLevel", "warn"],
+                cwd: plan.cwd ? join(request.root, plan.cwd) : request.root,
+                env: plan.env,
+                timeoutMs: BUILD_TIMEOUT_MS,
+                ...(request.signal ? { signal: request.signal } : {}),
+            });
+            if (result.code !== 0) {
+                const output = (result.stderr.trim() || result.stdout.trim()).split("\n").slice(-20).join("\n");
+                throw new Error(`${app}'s build for deployed-local (vite build) exited ${result.code}${output ? `:\n${output}` : ""}`);
+            }
+        },
+        ...(request.signal ? { signal: request.signal } : {}),
+    });
+    return { name: deployment.deployed.name, cid: deployment.deployed.cid };
+}

package/composition/src/device-browsers.d.ts

@@ -0,0 +1,6 @@
+import type { BrowserLauncher } from "@parity/product-lab/ports/browser";
+import { type DeviceProfile } from "@parity/product-lab/domain/devices";
+/** The device `name` names among the browser adapter's devices; throws naming the nearest when there is none. */
+export declare function runDevice(name: string): Promise<DeviceProfile>;
+/** `launcher`, emulating `device` in every launch (a launch that names its own device keeps it). */
+export declare function deviceBrowsers(launcher: BrowserLauncher, device: DeviceProfile | undefined): BrowserLauncher;

package/composition/src/device-browsers.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { resolveDevice } from "@parity/product-lab/domain/devices";
+import { DEVICE_VARIABLE } from "@parity/product-lab/domain/checks";
+export async function runDevice(name) {
+    const { playwrightDevices } = await import("@parity/product-lab/browser-playwright");
+    const resolved = resolveDevice(name, playwrightDevices(), DEVICE_VARIABLE);
+    if ("problem" in resolved)
+        throw new Error(resolved.problem);
+    return resolved.profile;
+}
+export function deviceBrowsers(launcher, device) {
+    if (!device)
+        return launcher;
+    return { ...(launcher.prerequisites ? { prerequisites: () => launcher.prerequisites() } : {}), launch: (options = {}) => launcher.launch({ ...options, device: options.device ?? device }) };
+}

package/composition/src/engine-setup.d.ts

@@ -0,0 +1 @@
+export {};

package/composition/src/engine-setup.js

@@ -0,0 +1,37 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { parseArgs } from "node:util";
+import { defaultEngineRepository, defaultStateDirectory, engineRepository, prepareEngine, setupPaths, testedEngineRef, } from "@parity/product-lab/env-engine";
+import { NodeSyncCommandRunner } from "@parity/product-lab/system-node";
+const root = process.cwd();
+try {
+    const { values } = parseArgs({
+        options: {
+            "engine-ref": { type: "string", default: testedEngineRef },
+            "engine-repository": { type: "string", default: defaultEngineRepository },
+            "no-patch": { type: "boolean", default: false },
+            network: { type: "string", default: "paseo-next-v2" },
+            "state-dir": { type: "string", default: defaultStateDirectory },
+            "dry-run": { type: "boolean", default: false },
+        },
+    });
+    const source = { repository: engineRepository({ repository: values["engine-repository"] }), patch: "none" };
+    if (values["dry-run"])
+        console.log(JSON.stringify({
+            ...setupPaths(root, values["engine-ref"], "", values["state-dir"]),
+            network: values.network,
+            engineRef: values["engine-ref"],
+            repository: source.repository,
+            patch: source.patch,
+            nodeRequired: ">=24",
+            mode: "fork",
+        }, null, 2));
+    else {
+        console.log(`Engine configuration: ${prepareEngine(root, values["engine-ref"], values.network, new NodeSyncCommandRunner(), values["state-dir"], undefined, source)}`);
+        console.log("Prepared tooling. Start the owned local fork with product-lab's tools/verify/src/engine-network.ts.");
+    }
+}
+catch (error) {
+    console.error(error);
+    process.exitCode = 1;
+}

package/composition/src/feature-runtime.d.ts

@@ -0,0 +1,5 @@
+import type { LabRuntime } from "@parity/product-lab/ports/driving";
+/** The lab's custom steps (`step()`), which the framework support registers next to the generated steps. */
+export { customStepSource } from "@parity/product-lab/steps";
+/** The run process's runtime; from then on its console lines go through the runtime's redactor (backlog 89). */
+export declare function featureRuntime(): LabRuntime;

package/composition/src/feature-runtime.js

@@ -0,0 +1,12 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createLabRuntime, processEnvironment } from "./create-lab-runtime.js";
+import { redactConsole } from "./redact-console.js";
+export { customStepSource } from "@parity/product-lab/steps";
+export function featureRuntime() {
+    const env = processEnvironment();
+    const config = env.get("PRODUCT_LAB_CONFIG");
+    const runtime = createLabRuntime({ allowPublic: true, ...(config ? { config } : {}) }, env);
+    redactConsole(runtime.redactor);
+    return runtime;
+}

package/composition/src/fixture-sharing.d.ts

@@ -0,0 +1,12 @@
+import type { FixtureSharingPorts } from "@parity/product-lab/application";
+import type { FixtureSourceDeclaration } from "@parity/product-lab/domain";
+import type { FixtureSource } from "@parity/product-lab/ports/storage";
+import type { EnvironmentVariables } from "@parity/product-lab/ports/system";
+/**
+ * The lab lock's components (version and digests), the host lock and the Engine build prepared in `engineState`
+ * (`<cache>/engine`, where saved forks run from).
+ */
+export declare function checkoutVersions(root: string, engineState?: string): Record<string, unknown>;
+/** One FixtureSource per declared source, in declaration order. */
+export declare function fixtureSources(declared: Readonly<Record<string, FixtureSourceDeclaration>>, labRoot: string, env: EnvironmentVariables): FixtureSource[];
+export declare function fixtureSharingPorts(env: EnvironmentVariables): FixtureSharingPorts;

package/composition/src/fixture-sharing.js

@@ -0,0 +1,62 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { savedForkEngineState, testedEngineRef } from "@parity/product-lab/env-engine";
+import { readHostLock } from "@parity/product-lab/host-truapi-cli";
+import { DirectoryFixtureSource, FileFixtureArchives } from "@parity/product-lab/storage-filesystem";
+import { NodeCommandRunner } from "@parity/product-lab/system-node";
+import { GithubReleaseFixtureSource, productLabCacheDir } from "@parity/product-lab/versions-github";
+export function checkoutVersions(root, engineState) {
+    const versions = {};
+    const lockFile = join(root, "lab.lock.json");
+    if (existsSync(lockFile)) {
+        const lock = JSON.parse(readFileSync(lockFile, "utf8"));
+        versions.lab = Object.fromEntries(Object.entries(lock.components ?? {}).map(([id, component]) => [id, { version: component.version, digests: component.digests ?? {} }]));
+    }
+    try {
+        const host = readHostLock();
+        versions.host = { official: host.official.version, patched: { baseVersion: host.patched.baseVersion, base: host.patched.base, patchset: host.patched.patchset, patches: host.patched.patches } };
+    }
+    catch (error) {
+        versions.host = { unreadable: error instanceof Error ? error.message : String(error) };
+    }
+    versions.engine = engineVersions(engineState);
+    return versions;
+}
+function engineVersions(state) {
+    const file = state ? join(state, "engine-build.json") : undefined;
+    if (!file || !existsSync(file))
+        return { ref: testedEngineRef, prepared: false };
+    try {
+        const build = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof build?.resolvedRef !== "string" || !build.resolvedRef)
+            throw new Error(`${file} names no resolved Engine commit`);
+        return build.resolvedRef === testedEngineRef
+            ? { ref: build.resolvedRef, prepared: true, tested: true }
+            : { ref: build.resolvedRef, prepared: true, tested: false, testedRef: testedEngineRef };
+    }
+    catch (error) {
+        return { unreadable: error instanceof Error ? error.message : String(error), testedRef: testedEngineRef };
+    }
+}
+export function fixtureSources(declared, labRoot, env) {
+    const token = env.get("GITHUB_TOKEN") ?? env.get("GH_TOKEN");
+    return Object.entries(declared).map(([id, source]) => source.kind === "directory"
+        ? new DirectoryFixtureSource(id, resolve(labRoot, source.path))
+        : new GithubReleaseFixtureSource({
+            id,
+            repository: source.repository,
+            tag: source.tag,
+            fetch: globalThis.fetch,
+            commands: new NodeCommandRunner(),
+            ...(source.attestation ? { attestation: source.attestation } : {}),
+            ...(source.signerWorkflow ? { signerWorkflow: source.signerWorkflow } : {}),
+            ...(token ? { token } : {}),
+        }));
+}
+export function fixtureSharingPorts(env) {
+    const cacheDir = productLabCacheDir({ PRODUCT_LAB_CACHE_DIR: env.get("PRODUCT_LAB_CACHE_DIR"), XDG_CACHE_HOME: env.get("XDG_CACHE_HOME") });
+    const cache = join(cacheDir, "fixtures");
+    return { archives: new FileFixtureArchives(), versions: async (root) => checkoutVersions(root, savedForkEngineState(cacheDir)), sources: (declared, labRoot) => fixtureSources(declared, labRoot, env), cache };
+}

package/composition/src/fork-attach.d.ts

@@ -0,0 +1,31 @@
+import type { EnvironmentProvider, ForkSnapshot } from "@parity/product-lab";
+/** Chain ports of a local Engine fork: relay +0, People +10, Asset Hub +20, Bulletin +30. */
+export declare function forkEndpoints(base: number): {
+    relay: string;
+    people: string;
+    "asset-hub": string;
+    bulletin: string;
+};
+/**
+ * The fork's snapshot, from Engine's fork bundle manifest (`biteBlocks`) or a
+ * recorded `fork-snapshot.json`. An attached fork cannot report it itself.
+ */
+export declare function readSnapshotFile(file: string): ForkSnapshot;
+/** The network the fork was taken from: a runtime resolved from another network is refused. */
+export declare const PASEO_FORK_NETWORK = "paseo-next-v2";
+/**
+ * The running fork at `fork.base` (relay +0, People +10, Asset Hub +20,
+ * Bulletin +30), attached. The declared offer is what a full Engine fork has;
+ * at start the chains are probed (env-attached) and the probed offer replaces
+ * it, so a fork without DotNS or Bulletin retrieval makes deployed-local apps
+ * unavailable. `fork.snapshot` is recorded in provenance and in manifest
+ * freshness messages. The run's resolved runtimes (`versions`) are compared
+ * with what each chain runs at its finalized head (`:code` hash, spec,
+ * genesis; env-attached `checkAttachedVersions`) and a difference refuses the
+ * start; the comparison is recorded in provenance. lab.lock.json's release
+ * files are not part of it: they belong to fast, which runs them.
+ */
+export declare function attachedForkEnvironment(fork: {
+    readonly base: number;
+    readonly snapshot?: string;
+}): EnvironmentProvider;

package/composition/src/fork-attach.js

@@ -0,0 +1,80 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readFileSync } from "node:fs";
+import { assertAttachedVersions, attachEnvironment, checkAttachedVersions } from "@parity/product-lab/env-attached";
+import { forkSnapshotFrom } from "@parity/product-lab/env-engine";
+export function forkEndpoints(base) {
+    return {
+        relay: `ws://127.0.0.1:${base}`,
+        people: `ws://127.0.0.1:${base + 10}`,
+        "asset-hub": `ws://127.0.0.1:${base + 20}`,
+        bulletin: `ws://127.0.0.1:${base + 30}`,
+    };
+}
+export function readSnapshotFile(file) {
+    const content = JSON.parse(readFileSync(file, "utf8"));
+    if (!isRecord(content))
+        throw new Error(`Invalid fork snapshot in ${file}: expected an object`);
+    return "biteBlocks" in content ? forkSnapshotFrom(content, file) : declaredSnapshotFrom(content, file);
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function declaredSnapshotFrom(content, file) {
+    const { network, bittenAt, source, blocks, runtimes, origin } = content;
+    if (typeof network !== "string" || !network || typeof bittenAt !== "string" || !bittenAt ||
+        origin !== "declared" && origin !== "fork-bundle" || source !== undefined && typeof source !== "string" ||
+        !isRecord(blocks) || runtimes !== undefined && !isRecord(runtimes)) {
+        throw new Error(`Invalid fork snapshot in ${file}: expected network, bittenAt, origin and numeric blocks`);
+    }
+    const parsedBlocks = {};
+    for (const [chain, block] of Object.entries(blocks)) {
+        if (typeof block !== "number" || !Number.isSafeInteger(block) || block < 0)
+            throw new Error(`Invalid fork snapshot in ${file}: ${chain} has no valid block number`);
+        parsedBlocks[chain] = block;
+    }
+    const parsedRuntimes = {};
+    for (const [chain, runtime] of Object.entries(runtimes ?? {})) {
+        if (typeof runtime !== "string")
+            throw new Error(`Invalid fork snapshot in ${file}: ${chain} has no runtime`);
+        parsedRuntimes[chain] = runtime;
+    }
+    return {
+        network, bittenAt, origin,
+        ...(source === undefined ? {} : { source }),
+        blocks: parsedBlocks,
+        ...(runtimes === undefined ? {} : { runtimes: parsedRuntimes }),
+        file,
+    };
+}
+export const PASEO_FORK_NETWORK = "paseo-next-v2";
+export function attachedForkEnvironment(fork) {
+    const endpoints = forkEndpoints(fork.base);
+    return {
+        label: `Local Paseo fork (attached, ports ${fork.base}+)`,
+        description: "An already running local Engine fork of paseo-next-v2, attached (never started, reset or stopped); People, Asset Hub and Bulletin",
+        offer: {
+            chains: ["people", "asset-hub", "bulletin"],
+            capabilities: ["contracts", "dotns", "bulletin", "statementStore", "devAuthority"],
+            local: true,
+        },
+        async start({ system, versions }) {
+            if (!system?.rpc)
+                throw new Error("paseo-copy probes the attached fork over the lab's JSON-RPC client (the start context's system ports); load the lab through the composition root");
+            const attached = await attachEnvironment({ chains: { people: endpoints.people, "asset-hub": endpoints["asset-hub"], bulletin: endpoints.bulletin } }, { rpc: system.rpc });
+            const compared = versions ? await checkAttachedVersions(attached, versions, { rpc: system.rpc, network: PASEO_FORK_NETWORK }) : undefined;
+            if (compared)
+                assertAttachedVersions(compared);
+            return {
+                offer: attached.offer,
+                endpoints,
+                provenance: {
+                    provider: "attached",
+                    ...(fork.snapshot ? { forkSnapshot: readSnapshotFile(fork.snapshot) } : {}),
+                    chains: Object.fromEntries(Object.entries(attached.chains).map(([id, chain]) => [id, { ws: chain.ws, genesis: chain.genesis, runtime: `${chain.specName} ${chain.specVersion}` }])),
+                    evidence: attached.evidence,
+                    ...(compared ? { versions: { runtimes: compared.runtimes, notApplicable: compared.notApplicable } } : {}),
+                },
+                close: async () => { },
+            };
+        },
+    };
+}

package/composition/src/fork-live.d.ts

@@ -0,0 +1,13 @@
+import { type ForkedChain, type LiveCodeFetcher, type LiveRuntime, type LiveRuntimeReader } from "@parity/product-lab/env-engine";
+/**
+ * Read what every live chain runs now through the `deployed` version source (finalized head, `:code` hash and runtime
+ * version), all chains at once, each within `timeoutMs` (default 8 s). Never rejects: an unreachable chain is listed
+ * in `failed`.
+ */
+export declare const readLiveRuntimes: LiveRuntimeReader;
+/** The live chain's runtime code at the block it was resolved at, from the same public endpoint. */
+export declare function downloadLiveCode(live: Pick<LiveRuntime, "endpoint" | "block">): Promise<Uint8Array>;
+/** Refuse code whose blake2-256 is not the live chain's code hash (a wrong or corrupted download): nothing is submitted. */
+export declare function requireLiveCode(chain: ForkedChain, code: Uint8Array, expected: string): void;
+/** `LiveCodeFetcher`: download (default `downloadLiveCode`), then refuse code that does not hash to the live code hash. */
+export declare function liveCodeFetcher(download?: (live: LiveRuntime) => Promise<Uint8Array>): LiveCodeFetcher;

package/composition/src/fork-live.js

@@ -0,0 +1,70 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { blake2b } from "@noble/hashes/blake2b";
+import { PapiChainAccess } from "@parity/product-lab/chain-papi";
+import { ComponentId, VersionSelector } from "@parity/product-lab/domain/versions";
+import { chainLabel, FORKED_CHAINS, shortError } from "@parity/product-lab/env-engine";
+import { deployedRuntimeSource } from "./versions/version-source-catalogue.js";
+export const readLiveRuntimes = async (endpoints, input) => {
+    const started = input.clock.now();
+    const chains = FORKED_CHAINS.filter((chain) => endpoints[chain]);
+    const opened = [];
+    const source = deployedRuntimeSource({ [input.network]: Object.fromEntries(chains.map((chain) => [chain, endpoints[chain]])) }, input.clock, { opened: (access) => opened.push(access) });
+    const runtimes = {};
+    const failed = {};
+    const timeoutMs = input.timeoutMs ?? 8000;
+    await Promise.all(chains.map(async (chain) => {
+        let timer;
+        try {
+            const resolved = await Promise.race([
+                source.resolve({ component: ComponentId.of("runtime", chain), selector: VersionSelector.parse("deployed") }),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`no answer within ${Math.round(timeoutMs / 1000)} s`)), timeoutMs);
+                    timer.unref();
+                }),
+            ]);
+            const component = resolved.component;
+            const block = component.source.type === "network" ? component.source.block : undefined;
+            const code = component.digests.code;
+            const { specName, specVersion } = component.attributes;
+            if (!block || !code)
+                throw new Error("the resolution names no block or code");
+            runtimes[chain] = { spec: `${specName} ${specVersion}`, specVersion, codeHash: `0x${code.hex}`, block: { number: block.number, hash: block.hash }, endpoint: endpoints[chain] };
+        }
+        catch (error) {
+            failed[chain] = shortError(error);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }));
+    for (const access of opened)
+        access.close();
+    return { runtimes, failed, durationMs: input.clock.now() - started };
+};
+const CODE_KEY = "0x3a636f6465";
+const toHex = (bytes) => `0x${Buffer.from(bytes).toString("hex")}`;
+export async function downloadLiveCode(live) {
+    const access = PapiChainAccess.connect(live.endpoint, { publicEndpoint: { reason: "download the live runtime code for an in-place fork upgrade" } });
+    try {
+        const hex = await access.client._request("state_getStorage", [CODE_KEY, live.block.hash]);
+        if (typeof hex !== "string" || !hex.startsWith("0x"))
+            throw new Error(`${live.endpoint} returned no runtime code at #${live.block.number}`);
+        return Uint8Array.from(Buffer.from(hex.slice(2), "hex"));
+    }
+    finally {
+        access.close();
+    }
+}
+export function requireLiveCode(chain, code, expected) {
+    const actual = toHex(blake2b(code, { dkLen: 32 }));
+    if (actual !== expected.toLowerCase())
+        throw new Error(`Refusing to upgrade ${chainLabel(chain)}: the downloaded code hashes to ${actual}, the live chain reports ${expected.toLowerCase()}. Nothing was submitted; the fork is unchanged.`);
+}
+export function liveCodeFetcher(download = downloadLiveCode) {
+    return async (chain, live) => {
+        const code = await download(live);
+        requireLiveCode(chain, code, live.codeHash);
+        return code;
+    };
+}

package/composition/src/gateway-program.d.ts

@@ -0,0 +1 @@
+export {};

package/composition/src/gateway-program.js

@@ -0,0 +1,24 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { GatewayUsageError, runGateway } from "@parity/product-lab/deploy-bulletin";
+import { HttpJsonRpcClient, SystemClock, WebSocketJsonRpcClient } from "@parity/product-lab/system-node";
+import { closeGatewayThenExit } from "./gateway-shutdown.js";
+try {
+    const running = await runGateway(process.argv.slice(2), {
+        rpc: new HttpJsonRpcClient({ timeoutMs: 30_000 }),
+        contentRpc: new WebSocketJsonRpcClient({ timeoutMs: 60_000 }),
+        clock: new SystemClock(),
+        fetchBytes: async (url, { accept, timeoutMs }) => {
+            const answer = await fetch(url, { headers: { accept }, signal: AbortSignal.timeout(timeoutMs), redirect: "follow" });
+            return { status: answer.status, bytes: new Uint8Array(await answer.arrayBuffer()) };
+        },
+    });
+    console.log(running.summary);
+    const stop = () => void closeGatewayThenExit(running.gateway, (code) => process.exit(code), (line) => console.error(line));
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+}
+catch (error) {
+    console.error(`product-lab gateway: ${error.message}`);
+    process.exit(error instanceof GatewayUsageError ? 2 : 1);
+}

package/composition/src/gateway-shutdown.d.ts

@@ -0,0 +1,4 @@
+/** Close `gateway`, then `exit(0)`; when closing fails, `report` the reason and `exit(1)`. Never rejects. */
+export declare function closeGatewayThenExit(gateway: {
+    close(): Promise<void>;
+}, exit: (code: number) => void, report: (line: string) => void): Promise<void>;

package/composition/src/gateway-shutdown.js

@@ -0,0 +1,13 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export async function closeGatewayThenExit(gateway, exit, report) {
+    try {
+        await gateway.close();
+    }
+    catch (error) {
+        report(`product-lab gateway: closing failed: ${error instanceof Error ? error.message : String(error)}`);
+        exit(1);
+        return;
+    }
+    exit(0);
+}

package/composition/src/host-tool-services.d.ts

@@ -0,0 +1,21 @@
+import type { HostToolServices } from "@parity/product-lab/application";
+import type { UpstreamRef, UpstreamRequest } from "@parity/product-lab/ports/host";
+import type { Clock, EnvironmentVariables } from "@parity/product-lab/ports/system";
+import type { HttpClient } from "@parity/product-lab/ports/versions";
+export interface HostToolServicesOptions {
+    readonly clock: Clock;
+    readonly env: EnvironmentVariables;
+    /** Tests: a fake API. Default: fetch. */
+    readonly http?: HttpClient;
+    /** Tests: a loopback API base. Default: https://api.github.com. */
+    readonly apiBase?: string;
+}
+/**
+ * An UpstreamResolver on the GitHub version adapter: `latest` is the newest
+ * published release whose tag has the request's form (other packages' tags,
+ * drafts and prereleases are skipped), `{ version }` that exact tag. It answers
+ * the release's commit, version and tag.
+ */
+export declare function githubUpstreamResolver(options: HostToolServicesOptions): (request: UpstreamRequest) => Promise<UpstreamRef>;
+/** The host tools' services the composition root passes to the runtime. */
+export declare function hostToolServices(options: HostToolServicesOptions): HostToolServices;