@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/environment/relayless/src/topology/relayless-environment.js

@@ -0,0 +1,443 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statfsSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { assertStartable, topologyAccess } from "@parity/product-lab/domain";
+import { createRunManifest } from "@parity/product-lab/domain/lab";
+import { EnvironmentVersions, VersionedWorkspace } from "@parity/product-lab/domain/versions";
+import { nodeRpc, observeChain } from "../chain-readiness.js";
+import { buildDevChainSpec } from "./dev-chain-spec.js";
+import { RELAYLESS_STOP, requireFreePort, statementMethods } from "./dev-node.js";
+import { hasChainDatabase, workspaceRecordSchema } from "./workspace-record.js";
+import { blockTimeMode, DEFAULT_RELAYLESS_BLOCK_TIME_MS } from "./relayless-topology.js";
+import { relaylessLaunchPlan } from "./relayless-plan.js";
+import { acquireResolvedRuntimes, LOCKABLE_BINARIES, withLockedArtifacts, withReleaseCode } from "./locked-artifacts.js";
+import { CATCH_UP_BLOCK_TIME_MS, CATCH_UP_WAIT_MS, clockAheadWords, clockPastWallDay, decodeMoment, TIMESTAMP_NOW_KEY, UTC_DAY_MS, utcMinute, wallClockDayAhead } from "./relayless-time.js";
+export function requireRelaylessSystem(deps) {
+    const { processes, commands, ports, locks, rpc, runManifests } = deps;
+    if (processes && commands && ports && locks && rpc && runManifests)
+        return { processes, commands, ports, locks, rpc, runManifests };
+    const missing = Object.entries({ processes, commands, ports, locks, rpc, runManifests })
+        .filter(([, value]) => value === undefined)
+        .map(([name]) => name);
+    throw new Error(`The local dev chain (Omni Node) needs the lab's system ports (${missing.join(", ")} missing): pass them as defineLab({ system })`);
+}
+class Started {
+    name;
+    process;
+    log;
+    exitCode;
+    constructor(name, process, log) {
+        this.name = name;
+        this.process = process;
+        this.log = log;
+        void process.exited.then((code) => (this.exitCode = code));
+    }
+    get exited() {
+        return this.exitCode !== undefined;
+    }
+    static async start(registry, id, binary, args) {
+        const process = await registry.start(id, { command: binary, args, stop: RELAYLESS_STOP });
+        return new Started(id, process, registry.logFile(id));
+    }
+}
+const CATCH_UP_MAX_GAP_MS = UTC_DAY_MS / 4;
+function withBlockTime(args, blockTimeMs) {
+    const at = args.indexOf("--dev-block-time");
+    if (at < 0)
+        throw new Error("the node has no --dev-block-time to change");
+    return args.map((arg, index) => (index === at + 1 ? String(blockTimeMs) : arg));
+}
+async function nodeClock(rpc, ws) {
+    return decodeMoment(await nodeRpc(rpc, ws.replace(/^ws/, "http"), "state_getStorage", [TIMESTAMP_NOW_KEY], 5000));
+}
+const WORKSPACE_FILE = "workspace.json";
+export function keptGenerations(parent, environment) {
+    const generations = [];
+    for (const entry of existsSync(parent) ? readdirSync(parent) : []) {
+        try {
+            const record = JSON.parse(readFileSync(join(parent, entry, WORKSPACE_FILE), "utf8"));
+            const named = typeof record.name === "string" && (record.name === environment || record.name.startsWith(`${environment}.versions-`));
+            if (named && typeof record.runs?.[0]?.runId === "string")
+                generations.push(record.runs[0].runId);
+        }
+        catch {
+        }
+    }
+    return generations;
+}
+const LOCK = "workspace.lock";
+const sha256File = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
+export function relaylessFingerprint(t, plan) {
+    const specs = {};
+    for (const node of plan.nodes) {
+        const file = "build" in node.spec ? node.spec.build.wasm : node.spec.copy;
+        if (!existsSync(file))
+            throw new Error(`${node.chain} runtime source ${file} does not exist`);
+        specs[node.chain] =
+            "build" in node.spec
+                ? { kind: "wasm", sha256: sha256File(file), edits: node.spec.build.edits }
+                : { kind: "spec", sha256: sha256File(file) };
+    }
+    return { network: t.network, chains: [...t.chains], statementStore: t.statementStore, specs };
+}
+export function fingerprintDifferences(recorded, declared) {
+    const differences = [];
+    if (recorded.network !== declared.network)
+        differences.push(`network ${recorded.network} → ${declared.network}`);
+    if (recorded.chains.join(",") !== declared.chains.join(","))
+        differences.push(`chains ${recorded.chains.join(", ")} → ${declared.chains.join(", ")}`);
+    if (recorded.statementStore !== declared.statementStore)
+        differences.push(`statementStore ${recorded.statementStore} → ${declared.statementStore}`);
+    for (const chain of declared.chains) {
+        const before = recorded.specs[chain];
+        const after = declared.specs[chain];
+        if (!before || !after)
+            continue;
+        if (before.kind !== after.kind || before.sha256 !== after.sha256)
+            differences.push(`runtimes.${chain} (${before.kind} sha256 ${before.sha256.slice(0, 12)}… → ${after.kind} sha256 ${after.sha256.slice(0, 12)}…)`);
+        else if (JSON.stringify(before.edits ?? {}) !== JSON.stringify(after.edits ?? {}))
+            differences.push(`genesisEdits.${chain}`);
+    }
+    return differences;
+}
+function lockWorkspace(locks, directory, runId, reports) {
+    const attempt = locks.tryAcquire({ path: join(directory, LOCK), record: { runId, reports }, onStale: "reclaim", ownerless: "stale" });
+    if (attempt.acquired) {
+        const held = attempt.lock;
+        return {
+            reclaimed: held.reclaimed,
+            unlock: () => {
+                held.release();
+            },
+        };
+    }
+    if (attempt.reason === "held")
+        throw new Error(`The local dev chain's workspace ${directory} is in use by process ${attempt.owner?.process?.pid ?? attempt.owner?.pid ?? "unknown"}`);
+    throw new Error(`Could not lock the local dev chain's workspace ${directory} (${attempt.reason})`);
+}
+async function stopLeftovers(processes, reclaimed) {
+    const reports = reclaimed?.reports;
+    if (typeof reports !== "string" || !isAbsolute(reports) || !existsSync(join(reports, "processes.json")))
+        return undefined;
+    const registry = processes.open(reports);
+    try {
+        const running = registry.status().filter((entry) => entry.processes > 0).map((entry) => entry.id);
+        if (running.length)
+            await registry.stopAll();
+        return { runId: typeof reclaimed?.runId === "string" ? reclaimed.runId : undefined, reports, stopped: running };
+    }
+    finally {
+        registry.close();
+    }
+}
+async function waitReady(rpc, node, owned, statementStore, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        if (owned.exited)
+            throw new Error(`${node.chain} node exited before readiness; inspect ${owned.log}`);
+        let observation;
+        let methods;
+        try {
+            observation = await observeChain(rpc, node.ws, { timeoutMs: 5000, pollMs: 200 });
+            if (statementStore)
+                methods = await statementMethods(rpc, node.ws.replace(/^ws/, "http"));
+        }
+        catch (error) {
+            lastError = error;
+            await delay(250);
+            continue;
+        }
+        if (methods && !methods.includes("statement_submit"))
+            throw new Error(`${node.chain} serves no statement_* RPC despite --enable-statement-store`);
+        return observation;
+    }
+    throw new Error(`${node.chain} readiness timed out: ${String(lastError)}; inspect ${owned.log}`);
+}
+export async function startRelaylessTopology(declared, options) {
+    assertStartable(declared);
+    const { system } = options;
+    const progress = options.progress ?? (() => { });
+    const split = options.versions
+        ? EnvironmentVersions.split({ resolution: options.versions, chains: declared.chains, network: declared.network, adapter: "local dev chain (Omni Node)", binaries: LOCKABLE_BINARIES.filter((name) => declared.binaries[name] === "locked") })
+        : undefined;
+    if (split?.refusals.length)
+        throw new Error(`The local dev chain (Omni Node) cannot honour this version resolution:\n${split.refusals.map((item) => `- ${item}`).join("\n")}`);
+    const fetched = await acquireResolvedRuntimes(declared, options.versions, options.artifacts, progress);
+    const t = withLockedArtifacts(declared, {
+        ...(options.versions ? { versions: options.versions } : {}),
+        ...(options.artifacts ? { artifacts: options.artifacts } : {}),
+        ...(options.binaryPaths ? { binaryPaths: options.binaryPaths } : {}),
+    });
+    const resolvedRuntimes = withReleaseCode(declared, t, split?.runtimes ?? []);
+    const versionNotes = [
+        ...fetched.map((item) => `${item.component}: downloaded and verified ${item.asset} (${item.sha256}) into the shared cache`),
+        ...resolvedRuntimes
+            .filter((item) => item.file)
+            .map((item) => `${item.runtime.id} ${item.runtime.version} records no code hash: the code expected on ${item.runtime.chain} is the blake2-256 of its verified release file ${basename(item.file)}, which this start put in a fresh genesis`),
+        ...resolvedRuntimes
+            .map((item) => item.runtime)
+            .filter((runtime) => runtime.fromNetwork)
+            .map((runtime) => `${runtime.chain} starts from a fresh genesis: it runs ${runtime.id}'s code (${runtime.version}, compared by code hash) but not ${runtime.network}'s state at #${runtime.block.number}`),
+    ];
+    const runId = randomUUID();
+    mkdirSync(options.workspace, { recursive: true, mode: 0o700 });
+    mkdirSync(options.reports, { recursive: true, mode: 0o700 });
+    const disk = statfsSync(options.workspace);
+    if (disk.bavail * disk.bsize < 2 * 1024 ** 3)
+        throw new Error("The local dev chain (Omni Node) needs at least 2 GiB free disk space");
+    const requested = "workspace" in t.state ? t.state.workspace : undefined;
+    const name = requested !== undefined && options.versions ? VersionedWorkspace.select(requested, options.versions) : requested;
+    if (name !== undefined && (!/^[\w.-]{1,64}$/.test(name) || name === "." || name === ".."))
+        throw new Error(`Invalid local dev chain workspace name ${JSON.stringify(name)}`);
+    const directory = name ? join(options.workspace, name) : mkdtempSync(join(options.workspace, "relayless-"));
+    const plan = relaylessLaunchPlan(t, { workspace: directory, binaryPaths: options.binaryPaths, runId: runId.slice(0, 8) });
+    let record;
+    let unlock;
+    let reclaimed;
+    const createdDirectory = name !== undefined && !existsSync(directory);
+    let replaced;
+    if (name) {
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const lock = lockWorkspace(system.locks, directory, runId, options.reports);
+        unlock = lock.unlock;
+        try {
+            reclaimed = await stopLeftovers(system.processes, lock.reclaimed);
+            if (reclaimed?.stopped.length)
+                progress(`workspace ${name}: stopped ${reclaimed.stopped.join(", ")}, left running by a start whose process is gone (${reclaimed.reports})`);
+            if (options.kept?.replace) {
+                try {
+                    const old = JSON.parse(readFileSync(join(directory, WORKSPACE_FILE), "utf8"));
+                    if (typeof old.runs?.[0]?.runId === "string")
+                        replaced = old.runs[0].runId;
+                }
+                catch {
+                }
+                for (const entry of readdirSync(directory))
+                    if (entry !== LOCK)
+                        rmSync(join(directory, entry), { recursive: true, force: true });
+                progress(`workspace ${name}: the kept chains were discarded; new ones start from genesis`);
+            }
+            const declared = relaylessFingerprint(t, plan);
+            if (existsSync(join(directory, WORKSPACE_FILE))) {
+                let stored;
+                try {
+                    stored = JSON.parse(readFileSync(join(directory, WORKSPACE_FILE), "utf8"));
+                }
+                catch {
+                    throw new Error(`${join(directory, WORKSPACE_FILE)} has invalid JSON; refusing to resume the workspace`);
+                }
+                const parsed = workspaceRecordSchema.safeParse(stored);
+                if (!parsed.success || parsed.data.name !== name)
+                    throw new Error(`${join(directory, WORKSPACE_FILE)} has an invalid local dev chain workspace record (schema, fingerprint or run history)`);
+                record = parsed.data;
+                const decision = VersionedWorkspace.resume({ name, recorded: record.versions, current: options.versions });
+                if (decision.action === "refuse")
+                    throw new Error(`The local dev chain's workspace ${name}: ${decision.message}`);
+                const differences = fingerprintDifferences(record.fingerprint, declared);
+                if (differences.length)
+                    throw new Error(`The local dev chain's workspace ${name} was created from a different topology (${differences.join("; ")}); resuming it would run other chains on its databases. Use another workspace name, or delete ${directory} to start again`);
+                for (const node of plan.nodes)
+                    if (!existsSync(node.specFile) || !hasChainDatabase(join(node.directory, "data")))
+                        throw new Error(`The local dev chain's workspace ${name} is incomplete: ${node.chain} has no chain spec or database in ${node.directory}`);
+            }
+            else if (plan.nodes.some((node) => existsSync(node.directory)))
+                throw new Error(`${directory} holds chain directories but no ${WORKSPACE_FILE}; refusing to reuse it as workspace ${name}`);
+        }
+        catch (error) {
+            unlock();
+            throw error;
+        }
+    }
+    const resumed = record !== undefined;
+    const keepData = options.keepData || name !== undefined;
+    const processes = [];
+    let registry;
+    let stopped = false;
+    const stop = async () => {
+        const errors = [];
+        for (const owned of [...processes].reverse())
+            await registry.stop(owned.name).then(() => owned.process.exited, (error) => errors.push(error));
+        if (errors.length)
+            throw new AggregateError(errors, "Some local dev chain processes did not stop; data retained");
+        stopped = true;
+        registry?.close();
+        if (!keepData)
+            rmSync(directory, { recursive: true, force: true });
+        unlock?.();
+    };
+    try {
+        for (const binary of new Set([...plan.nodes.map((node) => node.binary), ...plan.services.map((service) => service.binary)]))
+            if (!existsSync(binary))
+                throw new Error(`Missing binary ${binary}`);
+        for (const node of plan.nodes) {
+            await requireFreePort(system.ports, node.rpcPort, `${node.chain} node`);
+            await requireFreePort(system.ports, node.p2pPort, `${node.chain} node`);
+        }
+        for (const service of plan.services)
+            await requireFreePort(system.ports, service.port, service.name);
+        const specs = {};
+        if (!resumed)
+            await Promise.all(plan.nodes.map(async (node) => {
+                mkdirSync(node.directory, { recursive: true, mode: 0o700 });
+                if ("build" in node.spec) {
+                    progress(`${node.chain}: building a development chain spec from ${basename(node.spec.build.wasm)}`);
+                    const built = await buildDevChainSpec({
+                        binary: node.binary,
+                        wasm: node.spec.build.wasm,
+                        chain: node.chain,
+                        output: node.specFile,
+                        edits: node.spec.build.edits,
+                        commands: system.commands,
+                        signal: options.signal,
+                        ...(options.specCache ? { cacheDirectory: options.specCache } : {}),
+                    });
+                    if (built.reusedFrom)
+                        progress(`${node.chain}: reused the development chain spec built before (${built.reusedFrom})`);
+                    specs[node.chain] = built.provenance;
+                }
+                else {
+                    const spec = JSON.parse(readFileSync(node.spec.copy, "utf8"));
+                    writeFileSync(node.specFile, JSON.stringify({ ...spec, chainType: "Development", bootNodes: [], telemetryEndpoints: null }), { mode: 0o600 });
+                    specs[node.chain] = { copiedFrom: node.spec.copy };
+                }
+            }));
+        const timeoutMs = options.readinessTimeoutMs ?? 120_000;
+        registry = system.processes.open(options.reports);
+        const started = [];
+        for (const node of plan.nodes) {
+            progress(`${node.chain}: starting polkadot-omni-node on ${node.ws}, waiting for its first finalized block`);
+            const owned = await Started.start(registry, `${node.chain}-node`, node.binary, node.args);
+            processes.push(owned);
+            started.push({ node, owned });
+        }
+        const observations = await Promise.all(started.map(({ node, owned }) => waitReady(system.rpc, node, owned, node.chain === "people" && t.statementStore, timeoutMs)));
+        const chains = {};
+        started.forEach(({ node }, index) => (chains[node.chain] = observations[index]));
+        const versions = split
+            ? {
+                runtimes: resolvedRuntimes.map(({ runtime }) => {
+                    const observed = chains[runtime.chain];
+                    return runtime.compare({ codeHash: observed.codeHash, specName: observed.runtime.specName, specVersion: observed.runtime.specVersion, genesis: observed.genesis });
+                }),
+                notApplicable: split.notApplicable,
+                notes: versionNotes,
+            }
+            : undefined;
+        const mismatched = versions?.runtimes.flatMap((comparison) => comparison.problems) ?? [];
+        if (mismatched.length)
+            throw new Error(`The local dev chain's chains do not run the resolved runtimes, so they were stopped: ${mismatched.join("; ")}`);
+        const wallNow = options.wallNow ?? Date.now;
+        const startAgain = options.startAgain ?? (name ? `delete ${directory} to start it again from genesis` : "start again for a new chain");
+        const catchUp = async (entry) => {
+            const { node } = entry;
+            const from = await nodeClock(system.rpc, node.ws);
+            const wall = wallNow();
+            const tomorrow = clockPastWallDay(from, wall);
+            if (tomorrow !== undefined && from !== undefined) {
+                const chainDayEnded = { chain: node.chain, hoursAhead: Math.round((from - wall) / 3_600_000), kept: !!options.kept, mode: blockTimeMode(node.chain, t.blockTime[node.chain] ?? DEFAULT_RELAYLESS_BLOCK_TIME_MS) };
+                throw Object.assign(new Error(`${clockAheadWords(node.chain, from, wall)}: ${startAgain}`), { chainDayEnded });
+            }
+            const midnight = wallClockDayAhead(from, wall);
+            if (midnight === undefined || from === undefined)
+                return undefined;
+            const why = `${node.chain}'s clock read ${utcMinute(from)} and the wall clock ${utcMinute(wall)}: a host takes an allowance's period (a UTC day) from the wall clock, so on the chain's earlier day it cannot sign a statement`;
+            if (midnight - from > CATCH_UP_MAX_GAP_MS)
+                throw new Error(`${why}. It is ${Math.round((midnight - from) / 3_600_000)} h short of ${utcMinute(midnight)} (a fresh node starts about 2 h behind the wall clock): ${startAgain}`);
+            progress(`${why}. Running ${node.chain} with a block every ${CATCH_UP_BLOCK_TIME_MS} ms until its clock reaches ${utcMinute(midnight)}`);
+            const began = Date.now();
+            const restart = async (id, args) => {
+                await registry.stop(entry.owned.name);
+                await entry.owned.process.exited;
+                processes.splice(processes.indexOf(entry.owned), 1);
+                entry.owned = await Started.start(registry, id, node.binary, args);
+                processes.push(entry.owned);
+                return waitReady(system.rpc, node, entry.owned, node.chain === "people" && t.statementStore, timeoutMs);
+            };
+            await restart(`${node.chain}-node-catch-up`, withBlockTime(node.args, CATCH_UP_BLOCK_TIME_MS));
+            const deadline = Date.now() + CATCH_UP_WAIT_MS;
+            let clock = await nodeClock(system.rpc, node.ws);
+            while ((clock ?? 0) < midnight) {
+                options.signal?.throwIfAborted();
+                if (entry.owned.exited)
+                    throw new Error(`${why}; ${node.chain}'s node exited while it ran fast blocks; inspect ${entry.owned.log}`);
+                if (Date.now() > deadline)
+                    throw new Error(`${why}; its fast blocks did not reach ${utcMinute(midnight)} within ${CATCH_UP_WAIT_MS / 60_000} min (its clock read ${clock === undefined ? "nothing" : utcMinute(clock)})`);
+                await delay(250);
+                clock = await nodeClock(system.rpc, node.ws);
+            }
+            chains[node.chain] = await restart(`${node.chain}-node`, node.args);
+            const to = (await nodeClock(system.rpc, node.ws)) ?? clock;
+            const ms = Date.now() - began;
+            return { chain: node.chain, from, to, ms, notice: `${why}; the lab ran it with a block every ${CATCH_UP_BLOCK_TIME_MS} ms for ${Math.round(ms / 1000)} s until its clock read ${utcMinute(to)}, then with its own block time again` };
+        };
+        const caughtUp = (await Promise.all(started.map(catchUp))).filter((advance) => advance !== undefined);
+        for (const { node } of started) {
+            const observed = chains[node.chain];
+            const locked = versions?.runtimes.find((comparison) => comparison.chain === node.chain);
+            progress(`${node.chain}: ready at #${observed.finalized.number}, runtime ${observed.runtime.specName} ${observed.runtime.specVersion}${locked ? " (its code is the resolved one)" : ""}`);
+        }
+        for (const service of plan.services) {
+            const owned = await Started.start(registry, service.name, service.binary, service.args);
+            processes.push(owned);
+            const deadline = Date.now() + timeoutMs;
+            for (;;) {
+                if (owned.exited)
+                    throw new Error(`${service.name} exited before readiness; inspect ${owned.log}`);
+                try {
+                    await nodeRpc(system.rpc, service.url, "eth_chainId", [], 2000);
+                    break;
+                }
+                catch (error) {
+                    if (Date.now() > deadline)
+                        throw new Error(`${service.name} readiness timed out: ${String(error)}`);
+                    await delay(250);
+                }
+            }
+        }
+        let workspace;
+        if (name) {
+            const startedAt = new Date().toISOString();
+            record = record
+                ? { ...record, runs: [...record.runs, { runId, startedAt, resumed: true }] }
+                : {
+                    kind: "product-lab-relayless-workspace",
+                    schemaVersion: 1,
+                    name,
+                    createdAt: startedAt,
+                    fingerprint: relaylessFingerprint(t, plan),
+                    specs,
+                    runs: [{ runId, startedAt, resumed: false }],
+                    ...(options.versions ? { versions: options.versions.toJSON() } : {}),
+                };
+            writeFileSync(join(directory, WORKSPACE_FILE), JSON.stringify(record, null, 2) + "\n", { mode: 0o600 });
+            workspace = { name, directory, generation: record.runs[0].runId, resumed, runs: record.runs.length, ...(replaced ? { replaced } : {}), kept: keptGenerations(options.workspace, requested ?? name) };
+        }
+        const manifestFile = join(options.reports, "run-manifest.json");
+        options.system.runManifests.writeTo(manifestFile, createRunManifest(t, new Date().toISOString(), {
+            runId,
+            ...(options.environment ? { environment: options.environment } : {}),
+            plan,
+            extra: {
+                specs: resumed ? record.specs : specs,
+                chains,
+                ...(workspace ? { workspace } : {}),
+                ...(reclaimed ? { reclaimed } : {}),
+                ...(versions && options.versions ? { versions: { resolution: options.versions.toJSON(), ...versions } } : {}),
+                ...(caughtUp.length ? { caughtUp } : {}),
+            },
+        }));
+        const owned = registry;
+        const running = () => (stopped ? [] : owned.status().filter((entry) => processes.some((started) => started.name === entry.id)));
+        return { runId, ...(workspace ? { workspace } : {}), ...(versions ? { versions } : {}), ...(caughtUp.length ? { caughtUp } : {}), topology: t, plan, chains, access: topologyAccess(t), manifestFile, processes: running, stop };
+    }
+    catch (error) {
+        await stop().catch(() => undefined);
+        if (createdDirectory && processes.every((owned) => owned.exited))
+            rmSync(directory, { recursive: true, force: true });
+        throw error;
+    }
+}

package/adapters/environment/relayless/src/topology/relayless-plan.d.ts

@@ -0,0 +1,43 @@
+import type { GenesisEdits, Topology, TopologyChain } from "@parity/product-lab/domain";
+export interface RelaylessNodePlan {
+    chain: TopologyChain;
+    binary: string;
+    /** How the chain spec is obtained before start. */
+    spec: {
+        build: {
+            wasm: string;
+            preset: "development";
+            edits: GenesisEdits;
+        };
+    } | {
+        copy: string;
+    };
+    specFile: string;
+    directory: string;
+    args: string[];
+    rpcPort: number;
+    p2pPort: number;
+    ws: string;
+    blockTimeMs: number;
+}
+export interface RelaylessServicePlan {
+    name: "eth-rpc";
+    binary: string;
+    args: string[];
+    port: number;
+    url: string;
+}
+export interface RelaylessLaunchPlan {
+    provider: "relayless";
+    workspace: string;
+    nodes: RelaylessNodePlan[];
+    services: RelaylessServicePlan[];
+    unsupported: string[];
+}
+/** Paths for binaries the topology leaves "locked" (the lock lands in Phase 6). */
+export type BinaryPaths = Partial<Record<"polkadot-omni-node" | "eth-rpc", string>>;
+export declare function relaylessLaunchPlan(t: Topology, options: {
+    workspace: string;
+    binaryPaths?: BinaryPaths;
+    runId?: string;
+}): RelaylessLaunchPlan;

package/adapters/environment/relayless/src/topology/relayless-plan.js

@@ -0,0 +1,85 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { isAbsolute, join } from "node:path";
+import { devNodeArgs } from "./dev-node.js";
+function binaryPath(name, source, paths) {
+    if (source && typeof source === "object" && "path" in source)
+        return source.path;
+    const path = paths[name];
+    if (!path)
+        return `<${name}: pass binaryPaths["${name}"] until version locking lands>`;
+    if (!isAbsolute(path))
+        throw new Error(`${name} path must be absolute`);
+    return path;
+}
+function specSource(chain, source, edits) {
+    if (source && typeof source === "object" && "wasm" in source)
+        return { build: { wasm: source.wasm, preset: "development", edits } };
+    if (source && typeof source === "object" && "spec" in source)
+        return { copy: source.spec };
+    return { copy: `<runtimes.${chain} must be { wasm } or { spec }>` };
+}
+export function relaylessLaunchPlan(t, options) {
+    if (t.provider !== "relayless")
+        throw new Error(`Topology uses the ${t.provider} provider, not relayless`);
+    if (!isAbsolute(options.workspace))
+        throw new Error("The local dev chain's workspace must be absolute");
+    const paths = options.binaryPaths ?? {};
+    const omniNode = binaryPath("polkadot-omni-node", t.binaries["polkadot-omni-node"], paths);
+    const nodes = t.chains.map((chain) => {
+        const endpoint = t.endpoints.chains[chain];
+        const directory = join(options.workspace, chain);
+        const specFile = join(directory, "chain.json");
+        const blockTimeMs = t.blockTime[chain];
+        return {
+            chain,
+            binary: omniNode,
+            spec: specSource(chain, t.runtimes[chain], t.genesisEdits[chain] ?? {}),
+            specFile,
+            directory,
+            args: devNodeArgs({
+                specFile,
+                name: `product-lab-${chain}${options.runId ? `-${options.runId}` : ""}`,
+                blockTimeMs,
+                basePath: join(directory, "data"),
+                rpcPort: endpoint.rpcPort,
+                p2pPort: endpoint.p2pPort,
+                statementStore: chain === "people" && t.statementStore,
+                ipfsServer: chain === "bulletin",
+                extraArgs: t.nodeArgs[chain],
+            }),
+            rpcPort: endpoint.rpcPort,
+            p2pPort: endpoint.p2pPort,
+            ws: endpoint.ws,
+            blockTimeMs,
+        };
+    });
+    const services = [];
+    if (t.services.ethRpc && t.endpoints.chains["asset-hub"]) {
+        const port = t.ports.ethRpc;
+        services.push({
+            name: "eth-rpc",
+            binary: binaryPath("eth-rpc", t.binaries["eth-rpc"], paths),
+            args: [
+                "--node-rpc-url",
+                t.endpoints.chains["asset-hub"].ws,
+                "--rpc-port",
+                String(port),
+                "--no-prometheus",
+                "--eth-pruning",
+                "archive",
+                "--base-path",
+                join(options.workspace, "eth-rpc"),
+            ],
+            port,
+            url: t.endpoints.services.ethRpc,
+        });
+    }
+    return {
+        provider: "relayless",
+        workspace: options.workspace,
+        nodes,
+        services,
+        unsupported: t.issues.filter((issue) => issue.severity === "error").map((issue) => issue.message),
+    };
+}

package/adapters/environment/relayless/src/topology/relayless-provider.d.ts

@@ -0,0 +1,60 @@
+import { type Topology } from "@parity/product-lab/domain";
+import type { TopologyEnvironment } from "@parity/product-lab/ports/environment";
+import type { EnvironmentStartup } from "@parity/product-lab/ports/environment";
+import type { ProcessRunner, SystemPorts } from "@parity/product-lab/ports/system";
+import type { ArtifactStore } from "@parity/product-lab/ports/versions";
+import type { BinaryPaths } from "./relayless-plan.js";
+import { type RelaylessEnvironment } from "./relayless-environment.js";
+/** Machine settings of the relay-less adapter (where runs go, binaries, timeouts); the topology says what runs. */
+export interface RelaylessEnvironmentSettings {
+    /**
+     * Base directory, relative to lab.config.ts unless absolute (default
+     * `.product-lab/relayless`). Disposable runs go to `runs/`, named workspaces
+     * (`state: { workspace }`) to `workspaces/<name>`, logs and manifests to `reports/`.
+     */
+    directory?: string;
+    /** Binaries a topology leaves "locked" when the lab's lock pins none (a machine's own build). */
+    binaryPaths?: BinaryPaths;
+    /**
+     * The cache of lab.lock.json's release files (the composition root's
+     * `GitHubReleaseArtifacts`): `locked` runtimes and binaries run from it.
+     */
+    artifacts?: ArtifactStore;
+    readinessTimeoutMs?: number;
+    /** Keep a disposable run's chain data after close (named workspaces always keep it). */
+    keepData?: boolean;
+    /** The wall clock, in ms since the epoch (default `Date.now`); tests pin it (backlog 105, `toWallClockDay`). */
+    wallNow?: () => number;
+    /** How often a running environment reads its chains' clocks, in ms (default `CLOCK_WATCH_MS`); tests shorten it. */
+    clockWatchMs?: number;
+}
+/** How a relay-less start began: a resumed named workspace is warm; a new workspace or a disposable run starts from genesis (cold). */
+export declare function relaylessStartup(environment: Pick<RelaylessEnvironment, "workspace" | "runId">): EnvironmentStartup;
+/** How a person replaces a kept chain (backlog 183): start clean, in the lab window, the terminal app or the CLI. */
+export declare const CLEAN_START_WORDS = "start clean for a new chain and new people (the people kept with this chain are discarded): turn off \"Keep chain and people between starts\" (the lab window's environment menu, or k on the terminal app's Chains screen) and start again, or start with product-lab --clean";
+/** Label and description of the environment serving a relay-less topology, and what a kept start keeps of it. */
+export declare function describeRelayless(t: Topology): {
+    label: string;
+    description: string;
+    keeps?: string;
+};
+/**
+ * Stop what an earlier lab process, killed before it stopped them, left running in the run registries under
+ * `reports` (backlog 13a): its node would hold the ports this start needs. A run whose lab process still runs is left
+ * alone; `workspaces/` (a resumable workspace's chain data) holds no processes and is not read.
+ */
+export declare function stopAbandonedRuns(processes: ProcessRunner, reports: string, progress?: (message: string) => void): Promise<void>;
+/**
+ * The block times a kept start runs (the user, 8 October 2026): a chain kept between starts runs in real time, so its
+ * clock follows the wall clock and it never goes stale; a clean start keeps the topology's own (fast by default). A
+ * config that names a pace or a block time keeps its own either way. Undefined: the start runs the topology's.
+ */
+export declare function keptBlockTimes(declared: Topology): Topology["blockTime"] | undefined;
+/** Said once when a kept start runs in real time instead of the topology's fast pace. */
+export declare const KEPT_REAL_TIME_WORDS = "A kept chain runs in real time (its clock follows the wall clock, so it never goes stale); clean starts stay fast. pace: \"fast\" in lab.config.ts keeps it fast.";
+/**
+ * A lab environment for one relay-less topology (resolved by this adapter; the
+ * lab's registry routes only those here). Starting it needs the lab's
+ * `processes`, `ports`, `locks` and `rpc` system ports.
+ */
+export declare function relaylessEnvironment(declared: Topology, options?: RelaylessEnvironmentSettings, deps?: Partial<SystemPorts>): TopologyEnvironment;