@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/environment/relayless/src/owned-people-node.d.ts

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { type ManualSealSession, type SourceNetwork } from "./manual-seal-session.js";
+import type { CommandRunner, JsonRpcClient, PortAllocator, ProcessRunner } from "@parity/product-lab/ports/system";
+/** What an owned People node takes from the machine (Node implementations: `@parity/product-lab/system-node`). */
+export interface PeopleNodeSystem {
+    /** The node is recorded in a registry in the reports directory (`people-node`, log `people-node.log`). */
+    processes: ProcessRunner;
+    /** Bounded one-shot probes such as the node's version command. */
+    commands: CommandRunner;
+    ports: PortAllocator;
+    rpc: JsonRpcClient;
+}
+export declare const peopleNodeConfiguration: z.ZodObject<{
+    binary: z.ZodString;
+    chainSpec: z.ZodString;
+    workspace: z.ZodString;
+    rpcPort: z.ZodDefault<z.ZodNumber>;
+    blockTimeMs: z.ZodDefault<z.ZodNumber>;
+    namePrefix: z.ZodDefault<z.ZodString>;
+    statementStore: z.ZodDefault<z.ZodBoolean>;
+    extraArgs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type PeopleNodeConfiguration = z.infer<typeof peopleNodeConfiguration>;
+/** Preserve every raw genesis storage entry. Only node-network settings change. */
+export declare function isolatedPeopleSpec(input: unknown): {
+    chainType: string;
+    bootNodes: never[];
+    telemetryEndpoints: null;
+    name: string;
+    id: string;
+    genesis: {
+        raw: {
+            top: Record<string, string>;
+            childrenDefault: Record<string, unknown>;
+        };
+    };
+};
+/** Optional fast lane, not relay consensus. No Docker, live storage injection, mocked
+ * runtime calls or fabricated host services. Its source Wasm must match the
+ * recorded full-network runtime before the node is returned as ready. */
+export declare class OwnedPeopleNode {
+    private readonly config;
+    private readonly source;
+    private readonly reports;
+    private readonly system;
+    private owned?;
+    private directory?;
+    private stopping?;
+    private cancelled;
+    constructor(config: PeopleNodeConfiguration, source: Pick<SourceNetwork, "runId" | "network" | "chains">, reports: string, system: PeopleNodeSystem);
+    start(): Promise<ManualSealSession>;
+    waitForUnexpectedExit(): Promise<never>;
+    stop(): Promise<void>;
+    private stopOwned;
+}

package/adapters/environment/relayless/src/owned-people-node.js

@@ -0,0 +1,199 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync, rmSync, statfsSync, } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { HostNetworkRoutes } from "@parity/product-lab/domain";
+import { manualSealSessionSchema } from "./manual-seal-session.js";
+import { nodeRpc, observeChain } from "./chain-readiness.js";
+import { RELAYLESS_STOP, devNodeArgs, requireFreePort, statementMethods } from "./topology/dev-node.js";
+export const peopleNodeConfiguration = z
+    .strictObject({
+    binary: z.string().refine(isAbsolute),
+    chainSpec: z.string().refine(isAbsolute),
+    workspace: z.string().refine(isAbsolute),
+    rpcPort: z.number().int().min(1024).max(65534).default(12010),
+    blockTimeMs: z.number().int().min(500).max(6000).default(1000),
+    namePrefix: z.string().regex(/^[\w-]{1,32}$/).default("product-lab-fast"),
+    statementStore: z.boolean().default(true),
+    extraArgs: z.array(z.string().min(1)).default([]),
+});
+export function isolatedPeopleSpec(input) {
+    const spec = z
+        .looseObject({
+        name: z.string(),
+        id: z.string(),
+        genesis: z.object({
+            raw: z.object({
+                top: z.record(z.string(), z.string()),
+                childrenDefault: z.record(z.string(), z.unknown()),
+            }),
+        }),
+    })
+        .parse(input);
+    if (!spec.genesis.raw.top["0x3a636f6465"])
+        throw new Error("Raw People spec must include its runtime Wasm");
+    return {
+        ...spec,
+        chainType: "Development",
+        bootNodes: [],
+        telemetryEndpoints: null,
+    };
+}
+export class OwnedPeopleNode {
+    config;
+    source;
+    reports;
+    system;
+    owned;
+    directory;
+    stopping;
+    cancelled = false;
+    constructor(config, source, reports, system) {
+        this.config = config;
+        this.source = source;
+        this.reports = reports;
+        this.system = system;
+    }
+    async start() {
+        if (this.owned || this.cancelled)
+            throw new Error("People node already started or stopped");
+        mkdirSync(this.config.workspace, { recursive: true });
+        const disk = statfsSync(this.config.workspace);
+        if (disk.bavail * disk.bsize < 2 * 1024 ** 3)
+            throw new Error("Fast node requires at least 2 GiB free disk space before startup");
+        const specBytes = readFileSync(this.config.chainSpec);
+        const spec = isolatedPeopleSpec(JSON.parse(specBytes.toString()));
+        for (const port of [this.config.rpcPort, this.config.rpcPort + 1])
+            await requireFreePort(this.system.ports, port, "Fast node");
+        if (this.cancelled)
+            throw new Error("People node startup cancelled");
+        const versionResult = await this.system.commands.run({ command: this.config.binary, args: ["--version"], timeoutMs: 10_000 });
+        if (versionResult.code !== 0)
+            throw new Error(`People node version probe failed (${versionResult.code}): ${versionResult.stderr.trim()}`);
+        const version = versionResult.stdout.trim();
+        mkdirSync(this.config.workspace, { recursive: true });
+        mkdirSync(this.reports, { recursive: true });
+        this.directory = mkdtempSync(join(this.config.workspace, "people-"));
+        const specFile = join(this.directory, "chain.json");
+        writeFileSync(specFile, JSON.stringify(spec));
+        const binarySha256 = createHash("sha256")
+            .update(readFileSync(this.config.binary))
+            .digest("hex");
+        const runId = randomUUID();
+        const registry = this.system.processes.open(this.reports);
+        const log = registry.logFile("people-node");
+        const args = devNodeArgs({
+            specFile,
+            name: `${this.config.namePrefix}-${runId}`,
+            blockTimeMs: this.config.blockTimeMs,
+            basePath: join(this.directory, "data"),
+            rpcPort: this.config.rpcPort,
+            p2pPort: this.config.rpcPort + 1,
+            statementStore: this.config.statementStore,
+            extraArgs: this.config.extraArgs,
+        });
+        let started;
+        try {
+            started = await registry.start("people-node", { command: this.config.binary, args, stop: RELAYLESS_STOP });
+        }
+        catch (error) {
+            registry.close();
+            rmSync(this.directory, { recursive: true, force: true });
+            this.directory = undefined;
+            throw error;
+        }
+        const owned = { registry, process: started };
+        this.owned = owned;
+        void started.exited.then((code) => (owned.exitCode = code));
+        const deadline = Date.now() + 120_000;
+        let lastError;
+        try {
+            while (Date.now() < deadline) {
+                if (this.cancelled)
+                    throw new Error("People node startup cancelled");
+                if (owned.exitCode !== undefined)
+                    throw new Error(`People node exited before readiness; inspect ${log}`);
+                let people;
+                try {
+                    people = await observeChain(this.system.rpc, `ws://127.0.0.1:${this.config.rpcPort}`, {
+                        timeoutMs: 5000,
+                        pollMs: 200,
+                    });
+                }
+                catch (error) {
+                    lastError = error;
+                    await delay(250);
+                    continue;
+                }
+                if (people.runtime.specName !== "next-people-paseo" ||
+                    people.codeHash !== this.source.chains.people.codeHash)
+                    throw new Error("Fast node runtime differs from source session; use its matching raw spec");
+                const statement = await statementMethods(this.system.rpc, `http://127.0.0.1:${this.config.rpcPort}`);
+                if (this.config.statementStore && !statement.includes("statement_submit"))
+                    throw new Error("Fast node was started with --enable-statement-store but serves no statement_* RPC");
+                const session = manualSealSessionSchema.parse({
+                    schemaVersion: 2,
+                    provider: "manual-seal",
+                    runId,
+                    network: this.source.network,
+                    namespace: HostNetworkRoutes.namespaceOf(this.source.network),
+                    mode: "genesis",
+                    ownership: "owned",
+                    createdAt: new Date().toISOString(),
+                    node: {
+                        blockTimeMs: this.config.blockTimeMs,
+                        binary: this.config.binary,
+                        binarySha256,
+                        version,
+                        peerId: await nodeRpc(this.system.rpc, people.ws, "system_localPeerId"),
+                        sourceSpec: this.config.chainSpec,
+                        sourceSpecSha256: createHash("sha256")
+                            .update(specBytes)
+                            .digest("hex"),
+                        sourceRunId: this.source.runId,
+                        sourceCodeHash: this.source.chains.people.codeHash,
+                        statementStore: statement.includes("statement_submit"),
+                    },
+                    chains: { people },
+                });
+                writeFileSync(join(this.reports, "session.json"), JSON.stringify(session, null, 2));
+                return session;
+            }
+            throw new Error(`People node readiness timed out: ${String(lastError)}; inspect ${log}`);
+        }
+        catch (error) {
+            await this.stop();
+            throw error;
+        }
+    }
+    waitForUnexpectedExit() {
+        const owned = this.owned;
+        if (!owned || owned.exitCode !== undefined)
+            return Promise.reject(new Error("Owned People node is not running"));
+        return owned.process.exited.then((code) => {
+            throw new Error(`Owned People node exited (${code}); inspect people-node.log`);
+        });
+    }
+    stop() {
+        this.cancelled = true;
+        this.stopping ??= this.stopOwned();
+        return this.stopping;
+    }
+    async stopOwned() {
+        const owned = this.owned;
+        if (owned) {
+            try {
+                await owned.registry.stop("people-node");
+            }
+            catch (error) {
+                throw new Error("People node did not stop; retaining its data", { cause: error });
+            }
+            owned.registry.close();
+        }
+        if (this.directory)
+            rmSync(this.directory, { recursive: true, force: true });
+    }
+}

package/adapters/environment/relayless/src/prepare-people-genesis.d.ts

@@ -0,0 +1,87 @@
+import type { BlockRef, ChainAccess } from "@parity/product-lab/ports/chain";
+import { type SourceNetwork } from "./manual-seal-session.js";
+import type { JsonRpcClient } from "@parity/product-lab/ports/system";
+export interface PreparePeopleGenesisOptions {
+    /** JSON-RPC to the source network (HttpJsonRpcClient from @product-lab/system-node in the Node composition). */
+    rpc: JsonRpcClient;
+    /**
+     * Reads from the source session's People chain, opened by the caller (for
+     * example `PapiChainAccess.connect(source.chains.people.ws)` from
+     * @product-lab/chain-papi) and closed by it afterwards. Its genesis must be
+     * the source chain's.
+     */
+    chain: ChainAccess;
+    /**
+     * Checks that the source network still runs as recorded and returns its
+     * current record, for example env-engine's `checkEngineSession` bound to a
+     * `JsonRpcClient` for an Engine source (the fast lane imports no other
+     * adapter). Its result is validated again here.
+     */
+    checkSource: (source: SourceNetwork) => Promise<unknown>;
+    /** Development authority made Sudo.Key and endowed in the fresh genesis.
+     * The consumer supplies it (for example its development `//Alice`); the
+     * framework derives no privileged account itself. */
+    authority: {
+        address: string;
+    };
+    /** Consumer-owned reads at the source block, recorded in genesis.json next
+     * to the framework's runtime provenance (for example a pallet parameter its scenarios rely on). */
+    observe?: (chain: ChainAccess, at: BlockRef) => Promise<Record<string, unknown>>;
+}
+/** Prepare a fresh dev genesis with the exact source runtime. Only the supplied
+ * authority's Sudo key/endowment and matching total issuance change. No other
+ * pallet storage is injected. Codecs come from the source runtime's own
+ * metadata at the recorded block, so no generated descriptors are needed. */
+export declare function preparePeopleGenesis(source: SourceNetwork, templateFile: string, directory: string, options: PreparePeopleGenesisOptions): Promise<{
+    specFile: string;
+    provenance: {
+        runtime: {
+            templateCodeHash: string;
+            selectedCodeHash: string;
+            sourceBlock: {
+                hash: string;
+                number: number;
+            };
+        };
+        preparedAt: string;
+        sourceSession: {
+            [x: string]: unknown;
+            schemaVersion: 1;
+            runId: string;
+            network: "paseo-next-v2" | "previewnet";
+            namespace: string;
+            chains: {
+                [x: string]: unknown;
+                people: {
+                    ws: string;
+                    genesis: string;
+                    initialFinalized: {
+                        hash: string;
+                        number: string;
+                    };
+                    finalized: {
+                        hash: string;
+                        number: string;
+                    };
+                    runtime: {
+                        [x: string]: unknown;
+                        specName: string;
+                        specVersion: number;
+                        transactionVersion: number;
+                    };
+                    codeHash: string;
+                    observedAt: string;
+                };
+            };
+        };
+        sourceSpec: string;
+        sourceSpecSha256: string;
+        specSha256: string;
+        changes: {
+            storage: string;
+            key: string;
+            before?: string;
+            after: string;
+        }[];
+    };
+}>;

package/adapters/environment/relayless/src/prepare-people-genesis.js

@@ -0,0 +1,119 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getDynamicBuilder, getLookupFn } from "@polkadot-api/metadata-builders";
+import { decAnyMetadata, unifyMetadata } from "@polkadot-api/substrate-bindings";
+import { blake2b } from "@noble/hashes/blake2b";
+import { validateSourceNetwork } from "./manual-seal-session.js";
+import { nodeRpc } from "./chain-readiness.js";
+import { isolatedPeopleSpec } from "./owned-people-node.js";
+export async function preparePeopleGenesis(source, templateFile, directory, options) {
+    validateSourceNetwork(source);
+    const current = validateSourceNetwork(await options.checkSource(source));
+    if (current.runId !== source.runId || current.chains.people.genesis !== source.chains.people.genesis)
+        throw new Error("The source check returned another network; prepare from its current session");
+    const chain = options.chain;
+    const [connected, expected] = await Promise.all([
+        chain.genesisHash(),
+        nodeRpc(options.rpc, current.chains.people.ws, "chain_getBlockHash", [0]),
+    ]);
+    if (connected.toLowerCase() !== String(expected).toLowerCase())
+        throw new Error("The chain access is not connected to the source session's People chain");
+    const spec = isolatedPeopleSpec(JSON.parse(readFileSync(templateFile, "utf8")));
+    const top = spec.genesis.raw.top;
+    const templateCodeHash = "0x" +
+        Buffer.from(blake2b(Buffer.from(top["0x3a636f6465"].slice(2), "hex"), {
+            dkLen: 32,
+        })).toString("hex");
+    const sourceBlock = await chain.finalizedHead();
+    const extensions = (await options.observe?.(chain, sourceBlock)) ?? {};
+    const wasm = await nodeRpc(options.rpc, current.chains.people.ws, "state_getStorage", [
+        "0x3a636f6465",
+        sourceBlock.hash,
+    ]);
+    if (typeof wasm !== "string" || !/^0x[\da-f]+$/i.test(wasm))
+        throw new Error("The source People chain returned no runtime code at the source block");
+    const codeHash = "0x" +
+        Buffer.from(blake2b(Buffer.from(wasm.slice(2), "hex"), { dkLen: 32 })).toString("hex");
+    if (codeHash !== current.chains.people.codeHash)
+        throw new Error("Runtime changed during preparation; retry with its current session");
+    top["0x3a636f6465"] = wasm;
+    const builder = getDynamicBuilder(getLookupFn(unifyMetadata(decAnyMetadata(await chain.metadata(sourceBlock.hash)))));
+    const storage = (pallet, entry) => {
+        try {
+            return builder.buildStorage(pallet, entry);
+        }
+        catch {
+            throw new Error(`Runtime has no ${pallet}.${entry} storage`);
+        }
+    };
+    const codec = (pallet, entry) => storage(pallet, entry).value;
+    const codecs = {
+        number: codec("System", "Number"),
+        sudo: codec("Sudo", "Key"),
+        account: codec("System", "Account"),
+        issuance: codec("Balances", "TotalIssuance"),
+    };
+    const numberKey = storage("System", "Number").keys.enc();
+    if (top[numberKey] && codecs.number.dec(top[numberKey]) !== 0)
+        throw new Error("Use a fresh raw genesis spec, not exported running-chain storage");
+    const authority = options.authority;
+    const [sudo, account, issuance] = [
+        storage("Sudo", "Key").keys.enc(),
+        storage("System", "Account").keys.enc(authority.address),
+        storage("Balances", "TotalIssuance").keys.enc(),
+    ];
+    const encode = (value) => "0x" + Buffer.from(value).toString("hex");
+    const changes = [];
+    const set = (storage, key, after) => {
+        changes.push({ storage, key, before: top[key], after });
+        top[key] = after;
+    };
+    set("Sudo.Key", sudo, encode(codecs.sudo.enc(authority.address)));
+    const endowment = 10n ** 20n;
+    if (!top[account]) {
+        set("System.Account(authority)", account, encode(codecs.account.enc({
+            nonce: 0,
+            consumers: 0,
+            providers: 1,
+            sufficients: 0,
+            data: {
+                free: endowment,
+                reserved: 0n,
+                frozen: 0n,
+                flags: 1n << 127n,
+            },
+        })));
+        const previous = top[issuance]
+            ? codecs.issuance.dec(top[issuance])
+            : 0n;
+        set("Balances.TotalIssuance", issuance, encode(codecs.issuance.enc(previous + endowment)));
+    }
+    else if (codecs.account.dec(top[account]).data.free < 10n ** 18n) {
+        throw new Error("Existing genesis authority has insufficient funds; use a fresh development spec");
+    }
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const specFile = join(directory, "people.json");
+    const contents = JSON.stringify(spec);
+    writeFileSync(specFile, contents, { flag: "wx", mode: 0o600 });
+    const provenance = {
+        ...extensions,
+        runtime: {
+            templateCodeHash,
+            selectedCodeHash: codeHash,
+            sourceBlock: { hash: sourceBlock.hash, number: sourceBlock.number },
+        },
+        preparedAt: new Date().toISOString(),
+        sourceSession: current,
+        sourceSpec: templateFile,
+        sourceSpecSha256: createHash("sha256")
+            .update(readFileSync(templateFile))
+            .digest("hex"),
+        specSha256: createHash("sha256").update(contents).digest("hex"),
+        changes,
+    };
+    writeFileSync(join(directory, "genesis.json"), JSON.stringify(provenance, null, 2), { flag: "wx", mode: 0o600 });
+    return { specFile, provenance };
+}

package/adapters/environment/relayless/src/topology/dev-chain-spec.d.ts

@@ -0,0 +1,44 @@
+import type { GenesisEdits, TopologyChain } from "@parity/product-lab/domain";
+import type { CommandRunner } from "@parity/product-lab/ports/system";
+/** Para ids shared by paseo-next-v2 and previewnet (Engine network descriptors). */
+export declare const PARA_IDS: Readonly<Partial<Record<TopologyChain, number>>>;
+/** Well-known sr25519 development accounts (`//Alice` … `//Ferdie`). */
+export declare const DEV_ACCOUNTS: Readonly<Record<string, string>>;
+export declare function parseExact(text: string): unknown;
+/** Merge declared edits into a genesis preset patch. Arrays in `patch` replace
+ * the preset's; `endow` sets or replaces entries in `balances.balances`. */
+export declare function applyGenesisEdits(preset: unknown, edits?: GenesisEdits): Record<string, unknown>;
+export interface DevChainSpecOptions {
+    commands: CommandRunner;
+    signal?: AbortSignal;
+    /** `polkadot-omni-node` (its `chain-spec-builder` subcommand is used). */
+    binary: string;
+    wasm: string;
+    chain: TopologyChain;
+    output: string;
+    preset?: string;
+    relayChain?: string;
+    edits?: GenesisEdits;
+    /**
+     * Reuse specs built before (backlog 33): a directory of finished specs keyed by every input that shapes one (the
+     * binary's and the runtime's sha256, chain, preset, para id, relay chain, edits). An entry is used only when its
+     * bytes still hash to what it recorded; otherwise the spec is built again. Without it every start builds.
+     */
+    cacheDirectory?: string;
+}
+export interface DevChainSpec {
+    specFile: string;
+    provenance: {
+        chain: TopologyChain;
+        preset: string;
+        paraId: number;
+        wasmSha256: string;
+        specSha256: string;
+        edits: GenesisEdits;
+        rawStorageEdits: number;
+    };
+    /** The spec came from `cacheDirectory` (the entry's directory), not from chain-spec-builder. */
+    reusedFrom?: string;
+}
+/** Raw, isolated development spec: no boot nodes, no telemetry. */
+export declare function buildDevChainSpec(options: DevChainSpecOptions): Promise<DevChainSpec>;

package/adapters/environment/relayless/src/topology/dev-chain-spec.js

@@ -0,0 +1,131 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { readCachedSpec, specCacheEntry, writeCachedSpec } from "./spec-cache.js";
+const sha256 = (value) => createHash("sha256").update(value).digest("hex");
+export const PARA_IDS = {
+    "asset-hub": 1500,
+    bulletin: 1501,
+    people: 1502,
+};
+export const DEV_ACCOUNTS = {
+    "//Alice": "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
+    "//Bob": "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
+    "//Charlie": "5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y",
+    "//Dave": "5DAAnrj7VHTznn2AWBemMuyBwZWs6FNFjdyVXUeYum3PTXFy",
+    "//Eve": "5HGjWAeFDfFCWPsjFQdVV2Msvz2XtMktvgocEZcCj68kUMaw",
+    "//Ferdie": "5CiPPseXPECbkjWCa6MnjNokrgYjMqmKndv2rSnekmSK2DjL",
+};
+function account(value) {
+    if (value.startsWith("//")) {
+        const address = DEV_ACCOUNTS[value];
+        if (!address)
+            throw new Error(`Unknown development account ${value}; use an SS58 address`);
+        return address;
+    }
+    if (!/^[1-9A-HJ-NP-Za-km-z]{47,48}$/.test(value))
+        throw new Error(`Invalid SS58 address ${value}`);
+    return value;
+}
+const json = JSON;
+export function parseExact(text) {
+    return json.parse(text, (_key, value, context) => typeof value === "number" && context.source !== undefined && !Number.isSafeInteger(value)
+        ? json.rawJSON(context.source)
+        : value);
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value) && !("rawJSON" in value);
+function merge(base, patch) {
+    if (!isObject(base) || !isObject(patch))
+        return patch;
+    const result = { ...base };
+    for (const [key, value] of Object.entries(patch))
+        result[key] = merge(base[key], value);
+    return result;
+}
+export function applyGenesisEdits(preset, edits = {}) {
+    let result = merge(preset, edits.patch ?? {});
+    if (edits.sudo)
+        result = merge(result, { sudo: { key: account(edits.sudo) } });
+    const endow = Object.entries(edits.endow ?? {});
+    if (endow.length) {
+        const balances = isObject(result.balances) ? result.balances : {};
+        const entries = new Map((Array.isArray(balances.balances) ? balances.balances : []).map(([who, amount]) => [who, amount]));
+        for (const [who, amount] of endow)
+            entries.set(account(who), json.rawJSON(amount));
+        result = merge(result, { balances: { balances: [...entries] } });
+    }
+    return result;
+}
+export async function buildDevChainSpec(options) {
+    const paraId = PARA_IDS[options.chain];
+    if (paraId === undefined)
+        throw new Error(`No local dev chain para id for ${options.chain}`);
+    const preset = options.preset ?? "development";
+    mkdirSync(dirname(options.output), { recursive: true, mode: 0o700 });
+    const wasmSha256 = () => sha256(readFileSync(options.wasm));
+    const entry = options.cacheDirectory
+        ? specCacheEntry(options.cacheDirectory, {
+            binarySha256: sha256(readFileSync(options.binary)),
+            wasmSha256: wasmSha256(),
+            chain: options.chain,
+            preset,
+            paraId,
+            relayChain: options.relayChain ?? "paseo",
+            edits: options.edits ?? {},
+        })
+        : undefined;
+    if (entry) {
+        const cached = readCachedSpec(entry, options.output);
+        if (cached)
+            return { specFile: options.output, provenance: cached, reusedFrom: entry.directory };
+    }
+    const run = async (args) => {
+        const result = await options.commands.run({ command: options.binary, args: ["chain-spec-builder", ...args], timeoutMs: 120_000, maxOutputBytes: 64 * 1024 * 1024, signal: options.signal });
+        if (result.code !== 0)
+            throw new Error(`chain-spec-builder exited ${result.code}: ${result.stderr.trim()}`);
+        return result.stdout;
+    };
+    const presetJson = parseExact(await run(["display-preset", "-r", options.wasm, "-p", preset]));
+    const patchFile = join(dirname(options.output), `${options.chain}.genesis-patch.json`);
+    writeFileSync(patchFile, JSON.stringify(applyGenesisEdits(presetJson, options.edits)), { mode: 0o600 });
+    await run([
+        "-c",
+        options.output,
+        "create",
+        "-t",
+        "development",
+        "-n",
+        `product-lab ${options.chain}`,
+        "-i",
+        `product-lab-${options.chain}`,
+        "-c",
+        options.relayChain ?? "paseo",
+        "-p",
+        String(paraId),
+        "-r",
+        options.wasm,
+        "-s",
+        "patch",
+        patchFile,
+    ]);
+    const spec = JSON.parse(readFileSync(options.output, "utf8"));
+    const storage = Object.entries(options.edits?.storage ?? {});
+    for (const [key, value] of storage)
+        spec.genesis.raw.top[key.toLowerCase()] = value.toLowerCase();
+    const contents = JSON.stringify({ ...spec, chainType: "Development", bootNodes: [], telemetryEndpoints: null });
+    writeFileSync(options.output, contents, { mode: 0o600 });
+    const provenance = {
+        chain: options.chain,
+        preset,
+        paraId,
+        wasmSha256: entry?.inputs.wasmSha256 ?? wasmSha256(),
+        specSha256: sha256(contents),
+        edits: options.edits ?? {},
+        rawStorageEdits: storage.length,
+    };
+    if (entry)
+        writeCachedSpec(entry, contents, provenance);
+    return { specFile: options.output, provenance };
+}

package/adapters/environment/relayless/src/topology/dev-node.d.ts

@@ -0,0 +1,21 @@
+import type { JsonRpcClient, PortAllocator, StopPolicy } from "@parity/product-lab/ports/system";
+/** How an owned node is stopped: SIGINT (a clean shutdown), 15 s for that, then SIGKILL; a node still alive 5 s later fails the stop and its data is kept. */
+export declare const RELAYLESS_STOP: StopPolicy;
+export interface DevNodeArgsInput {
+    specFile: string;
+    name: string;
+    blockTimeMs: number;
+    basePath: string;
+    rpcPort: number;
+    p2pPort: number;
+    /** People: serve `statement_*` (`--enable-statement-store`). */
+    statementStore?: boolean;
+    /** Bulletin: serve bitswap retrieval (`--ipfs-server`). */
+    ipfsServer?: boolean;
+    extraArgs?: readonly string[];
+}
+export declare function devNodeArgs(input: DevNodeArgsInput): string[];
+/** Refuse a port another process holds, naming it when the OS can tell (backlog 114); the lab never takes one over. */
+export declare function requireFreePort(ports: PortAllocator, port: number, owner: string): Promise<void>;
+/** `statement_*` methods the node exposes (empty without `--enable-statement-store`). */
+export declare function statementMethods(client: JsonRpcClient, http: string): Promise<string[]>;