@parity/product-lab 0.0.1-placeholder → 0.1.0

package/composition/src/host-tool-services.js

@@ -0,0 +1,27 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ComponentId, VersionSelector } from "@parity/product-lab/domain/versions";
+import { NodeCommandRunner, NodeProcessSandbox } from "@parity/product-lab/system-node";
+import { FetchHttpClient, GitHubVersionSource } from "@parity/product-lab/versions-github";
+const UPSTREAM_COMPONENT = "host:upstream";
+export function githubUpstreamResolver(options) {
+    return async (request) => {
+        const token = options.env.get("GITHUB_TOKEN");
+        const source = new GitHubVersionSource({
+            http: options.http ?? new FetchHttpClient(),
+            clock: options.clock,
+            components: { [UPSTREAM_COMPONENT]: { repository: request.repository, tag: request.tag } },
+            ...(options.apiBase ? { apiBase: options.apiBase } : {}),
+            ...(token ? { token } : {}),
+        });
+        const selector = request.selector === "latest" ? VersionSelector.LATEST_RELEASE : VersionSelector.parse(request.selector.version);
+        const { component } = await source.resolve({ component: ComponentId.parse(UPSTREAM_COMPONENT), selector, ...(request.signal ? { signal: request.signal } : {}) });
+        const commit = /^git-sha1:([0-9a-f]{40})$/.exec(component.digests.commit?.toString() ?? "")?.[1];
+        if (!commit || component.source.type !== "github-release")
+            throw new Error(`${request.repository} release ${component.version} has no commit`);
+        return { commit, version: component.version, tag: component.source.tag };
+    };
+}
+export function hostToolServices(options) {
+    return { commands: new NodeCommandRunner(), resolveUpstream: githubUpstreamResolver(options), sandbox: new NodeProcessSandbox() };
+}

package/composition/src/host-words.d.ts

@@ -0,0 +1,3 @@
+import type { UnconfiguredHost } from "@parity/product-lab/ports/lab";
+/** A host adapter the lab does not declare, in plain words, with the config that turns it on. */
+export declare function unconfiguredHost(kind: string, adapterLabel: string | undefined): UnconfiguredHost;

package/composition/src/host-words.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const WORDS = {
+    "truapi-cli": { label: "truAPI CLI", why: "The person's wallet app on a computer, a program of its own: what most users run, and the lab watches every request it makes" },
+    "truapi-wasm": { label: "truAPI WASM", why: "The wallet running inside the browser page around the app: the web wallet path, nothing to install; truAPI WASM cannot read Bulletin yet (upstream), so what an app stored there before the page opened is not readable" },
+    dotli: { label: "dot.li host", why: "The app opened through the dot.li web host, as a visitor would open it; its sessions sign nothing yet" },
+};
+export function unconfiguredHost(kind, adapterLabel) {
+    const words = WORDS[kind];
+    return {
+        kind,
+        label: words?.label ?? adapterLabel ?? kind,
+        why: words?.why ?? adapterLabel ?? `The ${kind} host adapter`,
+        turnOn: `hosts: { "${kind}": { kind: "${kind}" } } in lab.config.ts`,
+    };
+}

package/composition/src/identity-funding.d.ts

@@ -0,0 +1,37 @@
+import { ScenarioJournal } from "@parity/product-lab/chain";
+import type { IntegrationChain } from "@parity/product-lab";
+import { type TransactionDeclaration } from "@parity/product-lab/domain";
+import type { Signer } from "@parity/product-lab/ports/chain";
+import type { Clock } from "@parity/product-lab/ports/system";
+export interface IdentityFundingOptions {
+    readonly chains: Readonly<Record<string, IntegrationChain>>;
+    /** The account that pays: the dev authority, or on a public network the user's funder. */
+    readonly authority: Signer;
+    readonly journal: ScenarioJournal;
+    readonly signal: AbortSignal;
+    readonly clock: Clock;
+    /** How much each account gets, in the chain's smallest unit: one amount, or by chain id. */
+    readonly planck: bigint | Readonly<Record<string, bigint>>;
+    /** Only these chains are funded (default: every chain with `Balances.transfer_keep_alive`). */
+    readonly chainIds?: readonly string[];
+    /** Runs before each funding transaction with the chain and the total it sends; throwing refuses it, sending nothing. */
+    readonly beforeSubmit?: (chainId: string, total: bigint) => Promise<void>;
+    /** A failed funding fails the identity's creation (default: a notice naming the identity and the chain). */
+    readonly required?: boolean;
+    /** The signed extensions an app declares for a chain (`apps.<id>.fundingSigning`), if any. */
+    readonly signing: (appId: string, chainId: string) => Record<string, unknown> | undefined;
+    /** Each funding transaction is declared here (category `lab-setup`). */
+    readonly transactions: TransactionDeclaration[];
+}
+/** One creation's funding of one app account. */
+export interface FundingPass {
+    /** Fund `account` for `name` on every chain that can; resolves with a notice per chain that did not. Once per pass. */
+    fund(name: string, account: string): Promise<string[]>;
+    /** The creation ended without asking (or after): no batch waits for it. Idempotent. */
+    end(): void;
+}
+export interface IdentityFunding {
+    /** A creation of an identity starts opening `appId`: from now its batch waits for it to ask or end. */
+    begin(appId: string): FundingPass;
+}
+export declare function identityFunding(options: IdentityFundingOptions): IdentityFunding;

package/composition/src/identity-funding.js

@@ -0,0 +1,92 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { Enum } from "polkadot-api";
+import { BatchFailedError, FundingBatch, submitBatch, TransactionExecutor } from "@parity/product-lab/chain";
+import { AccountAddress } from "@parity/product-lab/domain";
+import { transactionSubmitter } from "./chain-connections.js";
+const api = (chain) => chain.api;
+const names = (requests) => requests.map((request) => request.name).join(", ").replace(/, ([^,]*)$/, " and $1");
+export function identityFunding(options) {
+    const funded = new Set();
+    const batches = new Map();
+    const declare = (chain, receipt, accounts) => options.transactions.push({ chain, hash: receipt.txHash, category: "lab-setup", reason: `Fund the default session identities ${accounts} on ${chain}` });
+    const batchFor = (appId, chainId, chain, transfer) => {
+        const key = `${appId}\u0000${chainId}`;
+        const existing = batches.get(key);
+        if (existing)
+            return existing;
+        const executor = new TransactionExecutor(transactionSubmitter(chain, options.signing(appId, chainId)), options.journal, { signal: options.signal, chain: chainId, mode: "finalized", clock: options.clock });
+        const batchAll = api(chain)?.tx?.Utility?.batch_all;
+        const planck = typeof options.planck === "bigint" ? options.planck : options.planck[chainId];
+        const call = (account) => transfer({ dest: Enum("Id", account), value: planck });
+        const batch = new FundingBatch({
+            batches: !!batchAll,
+            separable: (error) => error instanceof BatchFailedError,
+            submit: async (requests) => {
+                const accounts = requests.map((request) => `${request.name} (${request.account})`).join(", ");
+                await options.beforeSubmit?.(chainId, planck * BigInt(requests.length));
+                if (requests.length === 1) {
+                    const receipt = await executor.submit(`Fund ${accounts} on ${chainId}`, call(requests[0].account), options.authority);
+                    declare(chainId, receipt, accounts);
+                    return receipt;
+                }
+                const { receipt } = await submitBatch(executor, {
+                    label: `Fund ${names(requests)} on ${chainId}`,
+                    calls: requests.map((request) => ({ label: `${request.name} (${request.account})`, call: call(request.account) })),
+                    signer: options.authority,
+                    build: (calls) => batchAll({ calls: calls.map((item) => item.decodedCall) }),
+                    mode: "all",
+                });
+                declare(chainId, receipt, accounts);
+                return receipt;
+            },
+        });
+        batches.set(key, batch);
+        return batch;
+    };
+    return {
+        begin(appId) {
+            const tickets = new Map();
+            for (const [id, chain] of Object.entries(options.chains)) {
+                if (options.chainIds && !options.chainIds.includes(id))
+                    continue;
+                const transfer = api(chain)?.tx?.Balances?.transfer_keep_alive;
+                if (transfer)
+                    tickets.set(id, batchFor(appId, id, chain, transfer).begin());
+            }
+            const end = () => tickets.forEach((ticket) => ticket.end());
+            let asked = false;
+            return {
+                end,
+                async fund(name, account) {
+                    if (asked)
+                        throw new Error(`${name}'s creation already asked for funding`);
+                    asked = true;
+                    if (funded.has(account)) {
+                        end();
+                        return [];
+                    }
+                    funded.add(account);
+                    const address = AccountAddress.parse(account);
+                    if (address.kind !== "account") {
+                        end();
+                        return [`${account} is a 20-byte address: the lab does not fund it (which 32-byte account it maps to depends on the chain). Let the host tell the account, or fund it in the lab's own setup.`];
+                    }
+                    const dest = address.ss58();
+                    const warnings = [];
+                    await Promise.all([...tickets].map(async ([id, ticket]) => {
+                        try {
+                            await ticket.fund({ name, account: dest });
+                        }
+                        catch (error) {
+                            warnings.push(`Funding ${name} (${account}) on ${id} failed: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }));
+                    if (options.required && warnings.length)
+                        throw new Error(warnings.join("; "));
+                    return warnings;
+                },
+            };
+        },
+    };
+}

package/composition/src/index.d.ts

@@ -0,0 +1,38 @@
+export { createLabRuntime, hostRegistry, labConfigPath, processEnvironment, STATE_DIR_VARIABLE, withSelectedAdapters, type LabRuntimeOptions } from "./create-lab-runtime.js";
+export { connectLabRuntime, type AttachedLabRuntime } from "./attached/attached-lab-runtime.js";
+export { followRunningLab, type FollowingLabRuntime } from "./attached/following-lab-runtime.js";
+export { labWindowLauncher, type LabCommand, type LabWindowLauncher, type LabWindowOpening } from "./attached/lab-window-launcher.js";
+export { headlessLab, HeadlessLabStarting, type HeadlessLab } from "./attached/headless-lab.js";
+export { LAB_CLAIM_RANGE, LAB_PORTS_VARIABLE, NodeSystem, parseLabPorts } from "./node-system.js";
+export { FIXTURE_INPUTS, labDefinitionFrom, LIVE_NETWORK_PRESETS, LOCAL_PEOPLE_SIGNING, millisecondsOf, OUTPUT_VARIABLE, planckOf, type LabDefinitionContext } from "./default-lab.js";
+export { declaredDevServer, detectDevServer, type DetectedDevServer } from "./default-dev-server.js";
+export { redactConsole } from "./redact-console.js";
+export { ENVIRONMENT_ADAPTERS, HOST_ADAPTERS, HOST_TOOL_KINDS } from "./adapter-catalogue.js";
+export { chainConnector, connectChains, transactionSubmitter } from "./chain-connections.js";
+export { deployedRuntimeSource } from "./versions/version-source-catalogue.js";
+export { downloadLiveCode, liveCodeFetcher, readLiveRuntimes, requireLiveCode } from "./fork-live.js";
+export { PEOPLE_DEV_GENESIS, peopleDevGenesis } from "./people-dev/genesis.js";
+export { DEFAULT_FAST_ONBOARDING, labAttester, MEMBER_READERS, memberStanding, PEOPLE_COLLECTION, PeopleAttesterChain, peopleOnboarding, RING_TIMEOUT_MS, sameKey, truapiCliAllocCheck, type AllocCheck, type FastOnboarding, type LabAttesterDeps, type MemberStanding, type PeopleOnboarding, type PeopleOnboardingOptions } from "./people-dev/onboarding.js";
+export { chainCode, indexBytes, papiRingStorage, PERSON_COLLECTIONS, personProductId, personRingEntropy, releasedAllocCheck, RING_LOOKBACK, type MemberKeyOf, type RingStorage } from "./people-dev/member-key.js";
+export { personReadings, type ReadPerson } from "./people-dev/readings.js";
+export { allocationFailures, BULLETIN_ALLOWANCES, continuesChain, followBlocks, StandInLedger, standInForXcm, unansweredReason, PROBE_BLOB_STORED, XCM_STAND_IN_LABEL, XcmStandIn, xcmStandIn, type AllocationFailure, type ProbeBlob, type FinalizedBlock, type FinalizedBlocks, type PeopleEvent, type StandInForXcmOptions, type XcmStandInOptions } from "./people-dev/xcm-stand-in.js";
+export { keptPeople, type KeptPeople, type KeptPeopleOptions, type KeptPerson } from "./people-keep/kept-people.js";
+export { SavedPeople, type SavedPerson } from "./people-keep/saved-people.js";
+export { PeopleLifecycle, type ActorEntry, type LifecycleActor, type StoppedActor } from "./people-keep/lifecycle.js";
+export { discardedLine, discardGeneration, replacedFolder, sweepGenerations, sweptLine, type DiscardedGeneration } from "./people-keep/discard.js";
+export { DEFAULT_FORK_PORT_BASE, paseoCopy, previewnetCopy, savedForkOptions, type NetworkCopyOptions } from "./network-copies.js";
+export { forkPortBase, MACHINE_VARIABLES, machineInputs, type MachineInputs } from "./machine-inputs.js";
+export { attachedForkEnvironment, forkEndpoints, PASEO_FORK_NETWORK, readSnapshotFile } from "./fork-attach.js";
+export { defaultSessions } from "./default-session.js";
+export { defaultSessionPage, readyAccount, type AppPage } from "./default-session-page.js";
+export { preOnboardedIdentity, preOnboardedViews, type PreOnboardedSecrets } from "./pre-onboarded-identities.js";
+export { locate, readPageAccount, waitUntilReady, type ReadinessSubject } from "./app-readiness.js";
+export { serveApp, type ServeAppRequest, type ServedApp } from "./app-server.js";
+export { deployedAppServer, type DeployedAppPlan } from "./deployed-app-server.js";
+export { AppUpdateHub, type AppUpdateHubOptions } from "./app-updates.js";
+export { environmentConditions } from "./actor-conditions.js";
+export { SessionHosts, type SessionHostsOptions } from "./session-hosts.js";
+export { unconfiguredHost } from "./host-words.js";
+export { observeBrowserPage, observeBrowserPages } from "./observe-browser-page.js";
+/** The deployed-local gateway program's path (a host runs it as the app; see gateway-program.ts). */
+export declare const GATEWAY_PROGRAM: string;

package/composition/src/index.js

@@ -0,0 +1,40 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { siblingModule } from "@parity/product-lab/domain/shared";
+export { createLabRuntime, hostRegistry, labConfigPath, processEnvironment, STATE_DIR_VARIABLE, withSelectedAdapters } from "./create-lab-runtime.js";
+export { connectLabRuntime } from "./attached/attached-lab-runtime.js";
+export { followRunningLab } from "./attached/following-lab-runtime.js";
+export { labWindowLauncher } from "./attached/lab-window-launcher.js";
+export { headlessLab, HeadlessLabStarting } from "./attached/headless-lab.js";
+export { LAB_CLAIM_RANGE, LAB_PORTS_VARIABLE, NodeSystem, parseLabPorts } from "./node-system.js";
+export { FIXTURE_INPUTS, labDefinitionFrom, LIVE_NETWORK_PRESETS, LOCAL_PEOPLE_SIGNING, millisecondsOf, OUTPUT_VARIABLE, planckOf } from "./default-lab.js";
+export { declaredDevServer, detectDevServer } from "./default-dev-server.js";
+export { redactConsole } from "./redact-console.js";
+export { ENVIRONMENT_ADAPTERS, HOST_ADAPTERS, HOST_TOOL_KINDS } from "./adapter-catalogue.js";
+export { chainConnector, connectChains, transactionSubmitter } from "./chain-connections.js";
+export { deployedRuntimeSource } from "./versions/version-source-catalogue.js";
+export { downloadLiveCode, liveCodeFetcher, readLiveRuntimes, requireLiveCode } from "./fork-live.js";
+export { PEOPLE_DEV_GENESIS, peopleDevGenesis } from "./people-dev/genesis.js";
+export { DEFAULT_FAST_ONBOARDING, labAttester, MEMBER_READERS, memberStanding, PEOPLE_COLLECTION, PeopleAttesterChain, peopleOnboarding, RING_TIMEOUT_MS, sameKey, truapiCliAllocCheck } from "./people-dev/onboarding.js";
+export { chainCode, indexBytes, papiRingStorage, PERSON_COLLECTIONS, personProductId, personRingEntropy, releasedAllocCheck, RING_LOOKBACK } from "./people-dev/member-key.js";
+export { personReadings } from "./people-dev/readings.js";
+export { allocationFailures, BULLETIN_ALLOWANCES, continuesChain, followBlocks, StandInLedger, standInForXcm, unansweredReason, PROBE_BLOB_STORED, XCM_STAND_IN_LABEL, XcmStandIn, xcmStandIn } from "./people-dev/xcm-stand-in.js";
+export { keptPeople } from "./people-keep/kept-people.js";
+export { SavedPeople } from "./people-keep/saved-people.js";
+export { PeopleLifecycle } from "./people-keep/lifecycle.js";
+export { discardedLine, discardGeneration, replacedFolder, sweepGenerations, sweptLine } from "./people-keep/discard.js";
+export { DEFAULT_FORK_PORT_BASE, paseoCopy, previewnetCopy, savedForkOptions } from "./network-copies.js";
+export { forkPortBase, MACHINE_VARIABLES, machineInputs } from "./machine-inputs.js";
+export { attachedForkEnvironment, forkEndpoints, PASEO_FORK_NETWORK, readSnapshotFile } from "./fork-attach.js";
+export { defaultSessions } from "./default-session.js";
+export { defaultSessionPage, readyAccount } from "./default-session-page.js";
+export { preOnboardedIdentity, preOnboardedViews } from "./pre-onboarded-identities.js";
+export { locate, readPageAccount, waitUntilReady } from "./app-readiness.js";
+export { serveApp } from "./app-server.js";
+export { deployedAppServer } from "./deployed-app-server.js";
+export { AppUpdateHub } from "./app-updates.js";
+export { environmentConditions } from "./actor-conditions.js";
+export { SessionHosts } from "./session-hosts.js";
+export { unconfiguredHost } from "./host-words.js";
+export { observeBrowserPage, observeBrowserPages } from "./observe-browser-page.js";
+export const GATEWAY_PROGRAM = siblingModule("./gateway-program.ts", import.meta.url).pathname;

package/composition/src/machine-inputs.d.ts

@@ -0,0 +1,67 @@
+import type { ResolvedConfigEntry } from "@parity/product-lab/ports/driving";
+/** The variables, by what they set. */
+export declare const MACHINE_VARIABLES: {
+    readonly chopsticksBin: "CHOPSTICKS_BIN";
+    readonly workerCaches: "PRODUCT_LAB_WORKER_CACHES";
+    readonly baseline: "PRODUCT_LAB_BASELINE";
+    readonly nodeLog: "PRODUCT_LAB_NODE_LOG";
+    readonly liveAccounts: "PRODUCT_LAB_LIVE_ACCOUNTS";
+    readonly forkPortBase: "PRODUCT_LAB_FORK_PORT_BASE";
+    readonly portBase: "PRODUCT_LAB_PORT_BASE";
+    readonly forkAttach: "PRODUCT_LAB_FORK_ATTACH";
+    readonly forkSnapshot: "PRODUCT_LAB_FORK_SNAPSHOT";
+    readonly worker: "PRODUCT_LAB_WORKER";
+};
+/** The port block a copy uses unless the lab or a variable names another. */
+export declare const DEFAULT_FORK_PORT_BASE = 42000;
+type Env = Readonly<Record<string, string | undefined>>;
+export interface MachineInputs {
+    /** A Chopsticks installed outside the workspace (the Chopsticks adapter's `bin`). */
+    readonly chopsticksBin?: string;
+    /** One product-lab cache per worker (`product-lab test --workers`): worker i's PRODUCT_LAB_CACHE_DIR. */
+    readonly workerCaches?: readonly string[];
+    /** A prepared fast baseline, verified: fast's People runtime and its node. */
+    readonly baseline?: {
+        readonly directory: string;
+        readonly runtimes: {
+            readonly people: {
+                readonly spec: string;
+            };
+        };
+        readonly binaries: {
+            readonly "polkadot-omni-node": {
+                readonly path: string;
+            };
+        };
+    };
+    /** Log targets for fast's nodes (`-l<targets>`, for instance `offchain=debug`). */
+    readonly nodeLog?: string;
+    /** The account the host gives the app for a live person, by person. */
+    readonly liveAccounts?: Readonly<Record<string, string>>;
+    /** A running Engine fork of paseo-next-v2 that paseo-copy attaches to, at this port block, and its snapshot file. */
+    readonly forkAttach?: {
+        readonly base: number;
+        readonly snapshot?: string;
+    };
+}
+/** Read and check this machine's inputs; `livePeople`: the people the config names on live networks. Refuses by variable. */
+export declare function machineInputs(env: Env, livePeople: readonly string[]): MachineInputs;
+/** Worker `<index>/<count>`'s index (PRODUCT_LAB_WORKER, set for each worker of `product-lab test --workers`), else 0. */
+export declare function workerIndex(env: Env): number;
+/**
+ * The copies' port block: PRODUCT_LAB_FORK_PORT_BASE, else 1000 after a block PRODUCT_LAB_PORT_BASE names (where a lab
+ * that names its block kept its fork), else 42000; a worker's 1000 ports on per index.
+ */
+export declare function forkPortBase(env: Env): {
+    readonly base: number;
+    readonly why: string;
+};
+/** Worker `index`'s cache from PRODUCT_LAB_WORKER_CACHES, refused by name when the list names none for it. */
+export declare function workerCache(inputs: MachineInputs, index: number): Record<string, string>;
+/** Each machine input as the resolved config shows it: set (its value), or greyed with how to set it. */
+export declare function machineEntries(inputs: MachineInputs, notes: {
+    readonly liveAccountsUnused?: string;
+}): ResolvedConfigEntry[];
+/** The saved copies' folder under the lab's output (a worker's own with its output folder). */
+export declare const copiesDirectory: (output: string) => string;
+export {};

package/composition/src/machine-inputs.js

@@ -0,0 +1,98 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { isAbsolute, join } from "node:path";
+import { AccountAddress } from "@parity/product-lab/domain/accounts";
+import { readFastBaseline } from "@parity/product-lab/env-relayless";
+export const MACHINE_VARIABLES = {
+    chopsticksBin: "CHOPSTICKS_BIN",
+    workerCaches: "PRODUCT_LAB_WORKER_CACHES",
+    baseline: "PRODUCT_LAB_BASELINE",
+    nodeLog: "PRODUCT_LAB_NODE_LOG",
+    liveAccounts: "PRODUCT_LAB_LIVE_ACCOUNTS",
+    forkPortBase: "PRODUCT_LAB_FORK_PORT_BASE",
+    portBase: "PRODUCT_LAB_PORT_BASE",
+    forkAttach: "PRODUCT_LAB_FORK_ATTACH",
+    forkSnapshot: "PRODUCT_LAB_FORK_SNAPSHOT",
+    worker: "PRODUCT_LAB_WORKER",
+};
+export const DEFAULT_FORK_PORT_BASE = 42_000;
+export function machineInputs(env, livePeople) {
+    const value = (name) => (env[name]?.trim() ? env[name].trim() : undefined);
+    const chopsticksBin = value(MACHINE_VARIABLES.chopsticksBin);
+    const caches = value(MACHINE_VARIABLES.workerCaches)?.split(",").map((path) => path.trim()).filter(Boolean);
+    if (caches?.some((path) => !isAbsolute(path)))
+        throw new Error(`${MACHINE_VARIABLES.workerCaches} must list absolute paths, one product-lab cache per worker, comma-separated`);
+    const baselineDirectory = value(MACHINE_VARIABLES.baseline);
+    if (baselineDirectory !== undefined && !isAbsolute(baselineDirectory))
+        throw new Error(`${MACHINE_VARIABLES.baseline} must be an absolute fast-baseline directory`);
+    const baseline = baselineDirectory === undefined ? undefined : readFastBaseline(baselineDirectory);
+    const nodeLog = value(MACHINE_VARIABLES.nodeLog);
+    const liveAccounts = value(MACHINE_VARIABLES.liveAccounts);
+    const attach = value(MACHINE_VARIABLES.forkAttach);
+    const snapshot = value(MACHINE_VARIABLES.forkSnapshot);
+    if (snapshot !== undefined && attach === undefined)
+        throw new Error(`${MACHINE_VARIABLES.forkSnapshot} describes the fork ${MACHINE_VARIABLES.forkAttach} attaches, and ${MACHINE_VARIABLES.forkAttach} is not set`);
+    if (snapshot !== undefined && !isAbsolute(snapshot))
+        throw new Error(`${MACHINE_VARIABLES.forkSnapshot} must be an absolute path`);
+    return {
+        ...(chopsticksBin ? { chopsticksBin } : {}),
+        ...(caches?.length ? { workerCaches: caches } : {}),
+        ...(baseline ? { baseline: { directory: baselineDirectory, runtimes: { people: { spec: baseline.chainSpec } }, binaries: { "polkadot-omni-node": { path: baseline.binary } } } } : {}),
+        ...(nodeLog ? { nodeLog } : {}),
+        ...(liveAccounts ? { liveAccounts: parseLiveAccounts(liveAccounts, livePeople) } : {}),
+        ...(attach ? { forkAttach: { base: portBlock(MACHINE_VARIABLES.forkAttach, attach), ...(snapshot ? { snapshot } : {}) } } : {}),
+    };
+}
+function parseLiveAccounts(text, livePeople) {
+    const accounts = {};
+    const form = "write Person=<SS58 address>, comma-separated (the value is not shown)";
+    for (const [index, entry] of text.split(",").map((item) => item.trim()).filter(Boolean).entries()) {
+        const at = entry.indexOf("=");
+        const person = at > 0 ? entry.slice(0, at).trim() : "";
+        if (!livePeople.includes(person))
+            throw new Error(`${MACHINE_VARIABLES.liveAccounts} entry ${index + 1} names no live person of this lab (${livePeople.join(", ") || "none: live names no people"}): ${form}`);
+        const address = AccountAddress.tryParse(entry.slice(at + 1).trim());
+        if (!address || address.kind !== "account" || address.prefix === undefined)
+            throw new Error(`${MACHINE_VARIABLES.liveAccounts} entry ${index + 1} (${person}) is not an SS58 address: ${form}`);
+        accounts[person] = address.text;
+    }
+    return accounts;
+}
+function portBlock(variable, text) {
+    const base = Number(text);
+    if (!Number.isInteger(base) || base < 1024 || base + 999 > 65535)
+        throw new Error(`${variable} must be the first port of 1000 that fit in 1024-65535`);
+    return base;
+}
+export function workerIndex(env) {
+    return Number(env[MACHINE_VARIABLES.worker]?.split("/")[0] ?? 0) || 0;
+}
+export function forkPortBase(env) {
+    const worker = workerIndex(env);
+    const named = env[MACHINE_VARIABLES.forkPortBase]?.trim();
+    const block = env[MACHINE_VARIABLES.portBase]?.trim();
+    const first = named ? portBlock(MACHINE_VARIABLES.forkPortBase, named) : block ? portBlock(MACHINE_VARIABLES.portBase, String(Number(block) + 1000)) : DEFAULT_FORK_PORT_BASE;
+    const from = named ? MACHINE_VARIABLES.forkPortBase : block ? `${MACHINE_VARIABLES.portBase} + 1000` : "the lab's default";
+    return { base: portBlock(`${from}${worker ? ` + 1000 for worker ${worker}` : ""}`, String(first + 1000 * worker)), why: `${from}${worker ? `, 1000 on for worker ${worker}` : ""}` };
+}
+export function workerCache(inputs, index) {
+    const caches = inputs.workerCaches;
+    if (!caches)
+        return {};
+    if (caches.length <= index)
+        throw new Error(`${MACHINE_VARIABLES.workerCaches} names ${caches.length} cache(s), none for worker ${index}`);
+    return { PRODUCT_LAB_CACHE_DIR: caches[index] };
+}
+export function machineEntries(inputs, notes) {
+    const entry = (variable, label, value, why, change) => ({ key: `machine.${variable}`, label, value: value ?? false, source: "machine", why: `${variable}${value === undefined ? " is not set" : ""}: ${why}`, change });
+    const accounts = inputs.liveAccounts && Object.entries(inputs.liveAccounts).map(([person, account]) => `${person}: ${account}`);
+    return [
+        entry(MACHINE_VARIABLES.chopsticksBin, "Chopsticks binary", inputs.chopsticksBin, "a Chopsticks installed outside the workspace, else the workspace's", `${MACHINE_VARIABLES.chopsticksBin}=/path/to/chopsticks.cjs`),
+        entry(MACHINE_VARIABLES.workerCaches, "A cache per worker", inputs.workerCaches, "worker i of product-lab test --workers uses the i-th as its product-lab cache, else the workers share the cache (saved forks only)", `${MACHINE_VARIABLES.workerCaches}=/abs/cache-0,/abs/cache-1`),
+        entry(MACHINE_VARIABLES.baseline, "Fast chain's baseline", inputs.baseline?.directory, "the local dev chain's People runtime and node from a prepared fast baseline (verified), else the locked release", `${MACHINE_VARIABLES.baseline}=/path/to/fast-baseline`),
+        entry(MACHINE_VARIABLES.nodeLog, "Fast chain's node log", inputs.nodeLog, "log targets for the local dev chain's nodes (-l<targets>)", `${MACHINE_VARIABLES.nodeLog}=offchain=debug`),
+        entry(MACHINE_VARIABLES.liveAccounts, "Live people's accounts", accounts, `the account the host gives the app for a live person, else the host's own${notes.liveAccountsUnused ? `; not used here: ${notes.liveAccountsUnused}` : ""}`, `${MACHINE_VARIABLES.liveAccounts}=Ada=<SS58 address>`),
+        entry(MACHINE_VARIABLES.forkAttach, "Attach a running Paseo fork", inputs.forkAttach ? `ports ${inputs.forkAttach.base}+${inputs.forkAttach.snapshot ? `, snapshot ${inputs.forkAttach.snapshot}` : ""}` : undefined, "paseo-copy attaches the running Engine fork of paseo-next-v2 on that block (never started, reset or stopped) instead of its saved copy; paseo-copy only: previewnet-copy is refused while it is set", `${MACHINE_VARIABLES.forkAttach}=10000`),
+    ];
+}
+export const copiesDirectory = (output) => join(output, "environments");

package/composition/src/network-copies.d.ts

@@ -0,0 +1,19 @@
+import { type OptionsEnvironment } from "@parity/product-lab";
+import { type SavedFork, type SavedForkSettings } from "@parity/product-lab/env-engine";
+import { DEFAULT_FORK_PORT_BASE } from "./machine-inputs.js";
+export { DEFAULT_FORK_PORT_BASE };
+/** What a lab may change of a copy: its id and words, and any of the saved fork's settings (the live reads are composed here). */
+export type NetworkCopyOptions = {
+    readonly id?: string;
+    readonly label?: string;
+    readonly description?: string;
+} & Partial<Omit<SavedForkSettings, "readLive" | "fetchCode">>;
+/** A saved fork's two layouts as one environment's options, Full first (its folder) and Light (its own folder). */
+export declare function savedForkOptions(forks: {
+    readonly full: SavedFork;
+    readonly light: SavedFork;
+}, settings?: NetworkCopyOptions): OptionsEnvironment;
+/** "Local copy of Paseo": the live Paseo network (relay chain, People, Asset Hub, Bulletin) saved on this machine, Full or Light. */
+export declare function paseoCopy(options?: NetworkCopyOptions): Record<string, OptionsEnvironment>;
+/** "Local copy of Previewnet": the live Previewnet network saved on this machine, Full or Light. */
+export declare function previewnetCopy(options?: NetworkCopyOptions): Record<string, OptionsEnvironment>;

package/composition/src/network-copies.js

@@ -0,0 +1,44 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { environmentOptions, nameEnvironment } from "@parity/product-lab";
+import { SAVED_FORK_LAYOUTS, savedForkEnvironment, savedForkFor } from "@parity/product-lab/env-engine";
+import { productLabCacheDir } from "@parity/product-lab/versions-github";
+import { join } from "node:path";
+import { processEnvironment } from "./create-lab-runtime.js";
+import { liveCodeFetcher, readLiveRuntimes } from "./fork-live.js";
+import { DEFAULT_FORK_PORT_BASE } from "./machine-inputs.js";
+export { DEFAULT_FORK_PORT_BASE };
+function forkSettings(options) {
+    const env = processEnvironment();
+    const cacheDir = options.cacheDir ?? productLabCacheDir({ PRODUCT_LAB_CACHE_DIR: env.get("PRODUCT_LAB_CACHE_DIR"), XDG_CACHE_HOME: env.get("XDG_CACHE_HOME") });
+    const { id: _id, label: _label, description: _description, ...settings } = options;
+    return {
+        ...settings,
+        portBase: options.portBase ?? Number(env.get("PRODUCT_LAB_FORK_PORT_BASE") ?? DEFAULT_FORK_PORT_BASE),
+        cacheDir,
+        seedsDir: options.seedsDir ?? (env.get("PRODUCT_LAB_SHARED_FIXTURES") || join(cacheDir, "shared-fixtures")),
+        readLive: readLiveRuntimes,
+        fetchCode: liveCodeFetcher(),
+    };
+}
+export function savedForkOptions(forks, settings = {}) {
+    const resolved = forkSettings(settings);
+    return environmentOptions(SAVED_FORK_LAYOUTS.map(({ topology: _topology, ...layout }) => ({ ...layout, environment: savedForkEnvironment(layout.id === "light" ? forks.light : forks.full, resolved) })));
+}
+function networkCopy(network, name, words, options) {
+    const id = options.id ?? `${network === "previewnet" ? "previewnet" : "paseo"}-copy`;
+    const [full, light] = SAVED_FORK_LAYOUTS.map((layout) => savedForkFor(network, name, id, layout));
+    return { [id]: nameEnvironment(savedForkOptions({ full: full, light: light }, options), { kind: "network-copy", label: options.label ?? words.label, description: options.description ?? words.description }) };
+}
+export function paseoCopy(options = {}) {
+    return networkCopy("paseo-next-v2", "Paseo", {
+        label: "Local copy of Paseo",
+        description: "The live Paseo network (relay chain, People, Asset Hub, Bulletin) copied onto this machine, with sudo: the real runtimes and state, no fees, nothing live touched",
+    }, options);
+}
+export function previewnetCopy(options = {}) {
+    return networkCopy("previewnet", "Previewnet", {
+        label: "Local copy of Previewnet",
+        description: "The live Previewnet network copied onto this machine, with sudo: its runtimes and state, nothing live touched",
+    }, options);
+}

package/composition/src/node-system.d.ts

@@ -0,0 +1,69 @@
+import type { EnvironmentVariables, PortRange, Redactor, SystemPorts } from "@parity/product-lab/ports/system";
+import { FileBreakpointStore, FileEnvironmentOptionChoices, FileFixtureStore, FileLabSettingsStore, FileRpcChoices, FileRunManifestStore, LockRunningLabRecord, NodeFileSystem } from "@parity/product-lab/storage-filesystem";
+import { ConsoleLogger, NodeCommandRunner, NodeSyncCommandRunner, NodeTreeCloner, NodeStdioWorker, NodeTerminalCommandRunner, NodeAppProxies, NodeChainGates, NodeConditionedLinks, NodeDocumentHeaders, FileLockManager, HttpJsonRpcClient, NodeHttpProbe, NodeProcessRunner, NodeProcessSandbox, NodeMachineMetrics, NodeOsPorts, RandomIdGenerator, SystemClock, TcpPortAllocator } from "@parity/product-lab/system-node";
+/** The system ports without a lab: the run manifest store needs the lab's directory (`forLab`). */
+export declare class NodeSystem {
+    readonly environment: EnvironmentVariables;
+    readonly files: NodeFileSystem;
+    readonly clock: SystemClock;
+    /** How busy the machine is, for run recordings (backlog 25). */
+    readonly machine: NodeMachineMetrics;
+    readonly ids: RandomIdGenerator;
+    /** Diagnostics on the console; with `redactor`, every line is scrubbed of the lab's secrets first (backlog 89). */
+    readonly logger: ConsoleLogger;
+    readonly processes: NodeProcessRunner;
+    readonly commands: NodeCommandRunner;
+    readonly syncCommands: NodeSyncCommandRunner;
+    readonly stdioWorker: NodeStdioWorker;
+    /** A command on this process's terminal until it exits (an agent the terminal app opens in its place). */
+    readonly terminalCommands: NodeTerminalCommandRunner;
+    readonly locks: FileLockManager;
+    /** The OS's ephemeral range and a port's holder (backlog 114): the start's warning, the bind error's holder. */
+    readonly osPorts: NodeOsPorts;
+    /** The lab's ports (config redesign): `next` from PRODUCT_LAB_PORTS, else blocks it claims on this machine (labPortClaim). */
+    readonly ports: TcpPortAllocator;
+    readonly rpc: HttpJsonRpcClient;
+    /** Whether a service endpoint answers HTTP (the environment overview's services). */
+    readonly http: NodeHttpProbe;
+    /** Deny-by-default networking for a native process, picked by platform: macOS sandbox-exec, Linux user and network namespaces (probed on first use). */
+    readonly sandbox: NodeProcessSandbox;
+    /** Copy-on-write copies of stopped state (fixtures): APFS clones on macOS, reflinks elsewhere. */
+    readonly trees: NodeTreeCloner;
+    /** The lab's proxy in front of an app's dev server (backlog items 64 to 66): the bridge script, held updates, framing headers. */
+    readonly appProxies: NodeAppProxies;
+    readonly conditionedLinks: NodeConditionedLinks;
+    /** Origin gates in front of local chain nodes for deny-by-default hosts (backlog 92). */
+    readonly chainGates: NodeChainGates;
+    readonly documentHeaders: NodeDocumentHeaders;
+    /** One application service over the raw reader, lent to hosts and the driving runtime. */
+    private readonly framing;
+    readonly inspectAppFraming: (request: import("@parity/product-lab/domain").AppFramingInspectionRequest) => Promise<import("@parity/product-lab/domain").AppFramingInspection>;
+    constructor(environment: EnvironmentVariables, options?: {
+        redactor?: Pick<Redactor, "text">;
+    });
+    /** Where a lab records run manifests: `<root>/.product-lab/runs`. */
+    runManifests(root: string): FileRunManifestStore;
+    /** Where a lab keeps its fixtures (saved states scenarios start from): `<root>/.product-lab/fixtures`. */
+    fixtures(root: string): FileFixtureStore;
+    /** Where a lab keeps its step breakpoints (backlog 17, its local state): `<root>/.product-lab/breakpoints.json`. */
+    breakpoints(root: string): FileBreakpointStore;
+    /** Where a lab keeps its lab window's settings (panel Settings, its local state): `<root>/.product-lab/settings.json`. */
+    labSettings(root: string): FileLabSettingsStore;
+    /** The lab window's remembered RPC per chain (3 October 2026): `<lab root>/.product-lab/state/rpc.json`, plain URLs only, 0600. */
+    rpcChoices(root: string, state?: string): FileRpcChoices;
+    /** The person's last choice of each environment's options (backlog 184): `<lab root>/.product-lab/state/environment-options.json`, 0600. */
+    optionChoices(root: string, state?: string): FileEnvironmentOptionChoices;
+    /**
+     * B1 step a (backlog B2): the lab running in this folder, as a lock at `<lab root>/.product-lab/running` (its
+     * `owner.json`), or at `path` (PRODUCT_LAB_RUNNING_DIR, or a lab of its own's `--record`).
+     */
+    runningLab(root: string, path?: string): LockRunningLabRecord;
+    /** The bundle for one lab; `range`: the ports the lab declares (`ports`), which its `next` hands out instead. */
+    forLab(root: string, range?: PortRange): SystemPorts;
+}
+/** The variable that gives every lab in this process its ports: `<from>-<to>` (gates, lane briefs, a person's habit). */
+export declare const LAB_PORTS_VARIABLE = "PRODUCT_LAB_PORTS";
+/** Where a lab claims its ports when nothing names them: 100-port blocks below every OS's ephemeral range (Linux's starts at 32768). */
+export declare const LAB_CLAIM_RANGE: Readonly<PortRange>;
+/** PRODUCT_LAB_PORTS parsed; throws for anything but a range of at least ten ports in 1024-65535. */
+export declare function parseLabPorts(value: string | undefined): PortRange | undefined;