@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/environment/engine/src/engine/ipfs-isolation.js

@@ -0,0 +1,62 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkedSync } from "../setup/sync-command.js";
+function denyAllBut(keep, keepLength, width) {
+    const format = (value) => width === 32
+        ? [24n, 16n, 8n, 0n].map((shift) => String((value >> shift) & 0xffn)).join(".")
+        : [112n, 96n, 80n, 64n, 48n, 32n, 16n, 0n].map((shift) => ((value >> shift) & 0xffffn).toString(16)).join(":");
+    const filters = [];
+    for (let length = 1; length <= keepLength; length++) {
+        const bit = 1n << BigInt(width - length);
+        const mask = ((1n << BigInt(width)) - 1n) ^ (bit - 1n);
+        filters.push(`/${width === 32 ? "ip4" : "ip6"}/${format((keep ^ bit) & mask)}/ipcidr/${length}`);
+    }
+    return filters;
+}
+export const LOOPBACK_ONLY_ADDRESS_FILTERS = [...denyAllBut(0x7f000000n, 8, 32), ...denyAllBut(1n, 128, 128)];
+export function isolateIpfsConfig(config, expose) {
+    const isolated = { ...config, Bootstrap: [] };
+    isolated.Routing = { ...(config.Routing ?? {}), Type: "none" };
+    const discovery = config.Discovery ?? {};
+    isolated.Discovery = { ...discovery, MDNS: { ...(discovery.MDNS ?? {}), Enabled: false } };
+    if (!expose)
+        isolated.Swarm = { ...(config.Swarm ?? {}), AddrFilters: LOOPBACK_ONLY_ADDRESS_FILTERS };
+    const addresses = config.Addresses ?? {};
+    if (!expose && Array.isArray(addresses.Swarm))
+        isolated.Addresses = {
+            ...addresses,
+            Swarm: addresses.Swarm.map((address) => typeof address === "string" ? address.replace(/^\/ip4\/0\.0\.0\.0\//, "/ip4/127.0.0.1/").replace(/^\/ip6\/::\//, "/ip6/::1/") : address),
+        };
+    return isolated;
+}
+export const IPFS_IDENTITY_MARKER = "product-lab-identity";
+export function requireIpfsRepository(repository, fix) {
+    if (existsSync(join(repository, "config")))
+        return;
+    throw new Error(`Fork isolation cannot configure Engine's IPFS repository: ${repository} does not exist, and Engine's start would create a default one listening on every interface. ${fix}, then start again`);
+}
+export function isolateIpfsRepository(repository, options) {
+    const file = join(repository, "config");
+    if (!existsSync(file))
+        return undefined;
+    let rotated = false;
+    const marker = join(repository, IPFS_IDENTITY_MARKER);
+    const identity = () => JSON.parse(readFileSync(file, "utf8")).Identity.PeerID;
+    if (options.rotate && (!existsSync(marker) || readFileSync(marker, "utf8").trim() !== identity())) {
+        options.rotate(repository);
+        writeFileSync(marker, `${identity()}\n`);
+        rotated = true;
+    }
+    const config = JSON.parse(readFileSync(file, "utf8"));
+    const updated = JSON.stringify(isolateIpfsConfig(config, options.expose), null, 2) + "\n";
+    if (updated !== readFileSync(file, "utf8"))
+        writeFileSync(file, updated);
+    return { peerId: identity(), rotated };
+}
+export function ipfsIdentityRotation(ipfs, commands) {
+    return (repository) => {
+        checkedSync(commands, { command: ipfs, args: ["key", "rotate", "--type=ed25519", "--oldkey=product-lab-previous-self"], env: { IPFS_PATH: repository }, timeoutMs: 30_000 });
+    };
+}

package/adapters/environment/engine/src/engine/live-network.d.ts

@@ -0,0 +1,32 @@
+/** A live network's endpoint: off this machine, so every connection to it needs its own recorded opt-in. */
+export interface PublicNetworkEndpoint {
+    readonly url: string;
+    readonly public: true;
+}
+export interface PublishedNetwork {
+    readonly network: string;
+    /** Where the endpoints were read: the published bundle's manifest, else Engine's network file. */
+    readonly from: {
+        readonly kind: "fork-bundle" | "network-file";
+        readonly file: string;
+    };
+    /** Chain id (`relay`, `people`, `asset-hub`, `bulletin`, `web3-storage`) → its public WebSocket endpoint. */
+    readonly endpoints: Readonly<Record<string, PublicNetworkEndpoint>>;
+    /** The published bundle, when there is one: when it was bitten, from where, and each chain's runtime then. */
+    readonly bundle?: {
+        readonly bittenAt: string;
+        readonly source?: string;
+        readonly runtimes: Readonly<Record<string, {
+            readonly specName: string;
+            readonly specVersion: number;
+        }>>;
+    };
+}
+/**
+ * The live endpoints of `network` from the prepared Engine (its workspace's published bundle, else its checkout's
+ * network file). Throws naming the network when neither names one.
+ */
+export declare function publishedNetworkEndpoints(engine: {
+    readonly checkout: string;
+    readonly workspace: string;
+}, network: string): PublishedNetwork;

package/adapters/environment/engine/src/engine/live-network.js

@@ -0,0 +1,41 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { forkBundleManifestPath } from "./fork-snapshot.js";
+import { liveEndpoints, resolveNetworkRpc } from "./fork-freshness.js";
+const manifestSchema = z.object({
+    bittenAt: z.string(),
+    source: z.string().optional(),
+    network: z.string(),
+    chains: z.record(z.string(), z.looseObject({ endpoint: z.string().optional(), specName: z.string(), specVersion: z.number() })),
+});
+const publicEndpoint = (url) => ({ url: resolveNetworkRpc(url, undefined), public: true });
+export function publishedNetworkEndpoints(engine, network) {
+    const manifestFile = forkBundleManifestPath(engine.workspace, network);
+    let bundle;
+    if (existsSync(manifestFile)) {
+        const manifest = manifestSchema.parse(JSON.parse(readFileSync(manifestFile, "utf8")));
+        if (manifest.network !== network)
+            throw new Error(`${manifestFile} is a bundle of ${manifest.network}, not ${network}`);
+        const endpoints = {};
+        const runtimes = {};
+        for (const [chain, info] of Object.entries(manifest.chains)) {
+            if (info.endpoint)
+                endpoints[chain] = publicEndpoint(info.endpoint);
+            runtimes[chain] = { specName: info.specName, specVersion: info.specVersion };
+        }
+        bundle = { bittenAt: manifest.bittenAt, ...(manifest.source ? { source: manifest.source } : {}), runtimes };
+        if (Object.keys(endpoints).length)
+            return { network, from: { kind: "fork-bundle", file: manifestFile }, endpoints, bundle };
+    }
+    const networkFile = join(engine.checkout, "networks", `${network}.json`);
+    if (!existsSync(networkFile))
+        throw new Error(`No live endpoint for ${network}: there is no published bundle at ${manifestFile} and Engine has no network file ${networkFile}`);
+    const { sudo: _sudo, ...fromFile } = liveEndpoints(engine, network);
+    const endpoints = Object.fromEntries(Object.entries(fromFile).flatMap(([chain, url]) => (url ? [[chain, publicEndpoint(url)]] : [])));
+    if (!Object.keys(endpoints).length)
+        throw new Error(`No live endpoint for ${network}: neither ${manifestFile} nor ${networkFile} names one`);
+    return { network, from: { kind: "network-file", file: networkFile }, endpoints, ...(bundle ? { bundle } : {}) };
+}

package/adapters/environment/engine/src/engine/network-adoption.d.ts

@@ -0,0 +1,56 @@
+export interface NetworkAdoptionInput {
+    /** The snapshot directory (`network/`, `network.json`, `session.json`, …). */
+    readonly snapshot: string;
+    /** The saved network's workspace (the snapshot record's `detail.directory`). */
+    readonly from: string;
+    /** This environment's workspace. */
+    readonly to: string;
+    /** This workspace's running plan (its network.json), for this checkout's Engine and ports. Absent for a workspace with no network yet (a seed: network-seed.ts), which names its Engine with `toTooling`. */
+    readonly live?: {
+        readonly processes: readonly {
+            readonly id: string;
+            readonly plan: {
+                readonly command: string;
+                readonly env?: Readonly<Record<string, string>>;
+            };
+        }[];
+    };
+    /** This checkout's prepared Engine tooling directory (`…/engine/tooling/<digest>`), when there is no running plan to read it from. */
+    readonly toTooling?: string;
+    /** This network's Engine ports (its `network/engine-ports.json`), when known. */
+    readonly livePorts?: Readonly<Record<string, number>>;
+}
+export interface NetworkAdoptionPlan {
+    /** One line per kind of change, for the import report. */
+    readonly remapped: readonly string[];
+    /** What cannot be moved; non-empty: the adoption is refused. */
+    readonly refused: readonly string[];
+    /** Directory prefixes to replace, in order. */
+    readonly paths: readonly (readonly [string, string])[];
+    /** Old port to new port (empty: the same block). */
+    readonly ports: ReadonlyMap<number, number>;
+    /** Files (relative to a snapshot) to rewrite and to remove. */
+    readonly rewrite: readonly string[];
+    readonly remove: readonly string[];
+}
+/** Rewrite directory prefixes and, where they are ports of the old block, loopback ports in one file's text. */
+export declare function rewriteText(text: string, paths: NetworkAdoptionPlan["paths"], ports: NetworkAdoptionPlan["ports"]): {
+    text: string;
+    paths: number;
+    ports: number;
+};
+/**
+ * What adopting the snapshot moves and what it cannot, read from the snapshot and this workspace's running plan.
+ * Reads only; `applyNetworkAdoption` makes the changes after the snapshot is copied into place.
+ */
+export declare function planNetworkAdoption(input: NetworkAdoptionInput): NetworkAdoptionPlan;
+/** Apply a plan to the copied snapshot at `directory` (this workspace, after the copy). Returns what each file changed. */
+export declare function applyNetworkAdoption(plan: NetworkAdoptionPlan, directory: string): {
+    file: string;
+    paths: number;
+    ports: number;
+}[];
+/** The adopted lineage record kept inside the data folder, so a template reset (which replaces the folder) forgets it. */
+export declare const ADOPTED_LINEAGE = "adopted-lineage.json";
+/** The lineage an adopted network brought with it, when it was adopted (`<workspace>/network/adopted-lineage.json`). */
+export declare function readAdoptedLineage(directory: string): string | undefined;

package/adapters/environment/engine/src/engine/network-adoption.js

@@ -0,0 +1,195 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, sep } from "node:path";
+import { engineCheckout } from "./persisted-data.js";
+import { listenedPorts } from "./plan-ports.js";
+const TEXT_FILES = ["network.json", "session.json", "versions.json", "network/engine-ports.json", "network/isolation.json", "network/zombie.json", "network/fork-snapshot.json", "network/lab-ipfs/config"];
+function extraFiles(snapshot) {
+    const directory = join(snapshot, "files");
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory).filter((name) => lstatSync(join(directory, name)).isFile()).map((name) => `files/${name}`);
+}
+const REGENERATED = ["network/identity-pgdata/postmaster.opts"];
+const SCAN_LIMIT = 8 * 1024 * 1024;
+function readJson(file) {
+    if (!existsSync(file))
+        return undefined;
+    return JSON.parse(readFileSync(file, "utf8"));
+}
+function toolingRoot(plan) {
+    const checkout = engineCheckout(plan);
+    return checkout ? dirname(checkout) : undefined;
+}
+export function rewriteText(text, paths, ports) {
+    let out = text;
+    let pathCount = 0;
+    for (const [from, to] of paths) {
+        const parts = out.split(from);
+        pathCount += parts.length - 1;
+        out = parts.join(to);
+    }
+    let portCount = 0;
+    if (ports.size) {
+        const move = (value) => {
+            const next = ports.get(Number(value));
+            if (next === undefined)
+                return undefined;
+            portCount++;
+            return String(next);
+        };
+        out = out
+            .replace(/((?:127\.0\.0\.1|localhost|0\.0\.0\.0):)(\d{2,5})\b/g, (match, host, port) => (move(port) ? `${host}${ports.get(Number(port))}` : match))
+            .replace(/\/(tcp|udp)\/(\d{2,5})\b/g, (match, protocol, port) => (move(port) ? `/${protocol}/${ports.get(Number(port))}` : match))
+            .replace(/("(?:--rpc-port|--port|--prometheus-port|-p)",\s*")(\d{2,5})"/g, (match, flag, port) => (move(port) ? `${flag}${ports.get(Number(port))}"` : match))
+            .replace(/("[A-Za-z0-9_]*(?:PORT|[Pp]ort)":\s*)(\d{2,5})\b/g, (match, key, port) => (move(port) ? `${key}${ports.get(Number(port))}` : match))
+            .replace(/("ports":\s*\[)([\d,\s]*)(\])/g, (_match, open, list, close) => `${open}${list.replace(/\d+/g, (port) => move(port) ?? port)}${close}`);
+    }
+    return { text: out, paths: pathCount, ports: portCount };
+}
+function chainSpecs(snapshot) {
+    const network = join(snapshot, "network");
+    const specs = [];
+    for (const name of readdirSync(network)) {
+        const path = join(network, name);
+        if (name.endsWith(".json") && !TEXT_FILES.includes(`network/${name}`) && lstatSync(path).isFile())
+            specs.push(`network/${name}`);
+        const cfg = join(path, "cfg");
+        if (lstatSync(path).isDirectory() && existsSync(cfg))
+            for (const spec of readdirSync(cfg))
+                if (spec.endsWith(".json"))
+                    specs.push(`network/${name}/cfg/${spec}`);
+    }
+    return specs;
+}
+function scannable(root) {
+    const found = [];
+    const skip = (path) => /(^|\/)(db|paritydb|base|pg_wal|pg_xact|global|pg_multixact|pg_subtrans|blocks|datastore|keystore)(\/|$)/.test(path) || /(^|\/)LOG(\.old\.\d+)?$|\.log$|\.tgz$|\.wasm$/.test(path);
+    const visit = (directory) => {
+        for (const name of readdirSync(join(root, directory))) {
+            const path = directory ? `${directory}/${name}` : name;
+            const stat = lstatSync(join(root, path));
+            if (stat.isDirectory()) {
+                if (!skip(path))
+                    visit(path);
+            }
+            else if (stat.isFile() && !skip(path) && stat.size <= SCAN_LIMIT)
+                found.push(path);
+        }
+    };
+    visit("");
+    return found;
+}
+function ipfsBlocksNaming(root, ports) {
+    const blocks = join(root, "network", "lab-ipfs", "blocks");
+    if (!existsSync(blocks) || !ports.size)
+        return [];
+    const named = [];
+    const pattern = /(?:127\.0\.0\.1|localhost):(\d{2,5})\b/g;
+    for (const shard of readdirSync(blocks)) {
+        const directory = join(blocks, shard);
+        if (!lstatSync(directory).isDirectory())
+            continue;
+        for (const name of readdirSync(directory)) {
+            const file = join(directory, name);
+            if (lstatSync(file).size > SCAN_LIMIT)
+                continue;
+            const text = readFileSync(file).toString("latin1");
+            for (const match of text.matchAll(pattern))
+                if (ports.has(Number(match[1]))) {
+                    named.push(relative(root, file).split(sep).join("/"));
+                    break;
+                }
+        }
+    }
+    return named;
+}
+export function planNetworkAdoption(input) {
+    const refused = [];
+    const remapped = [];
+    const saved = readJson(join(input.snapshot, "network.json"));
+    if (!saved?.processes)
+        return { remapped, refused: [`the snapshot has no saved plan (network.json with processes)`], paths: [], ports: new Map(), rewrite: [], remove: [] };
+    const paths = [];
+    if (input.from !== input.to) {
+        paths.push([input.from, input.to]);
+        remapped.push(`workspace ${input.from} → ${input.to}`);
+    }
+    const fromTooling = toolingRoot({ processes: saved.processes });
+    const toTooling = input.toTooling ?? (input.live ? toolingRoot(input.live) : undefined);
+    if (fromTooling && toTooling && fromTooling !== toTooling) {
+        if (basename(fromTooling) !== basename(toTooling))
+            refused.push(`it was made by another prepared Engine (tooling ${basename(fromTooling)}; this checkout prepares ${basename(toTooling)}): the saved network's binaries and scripts are that Engine's; import it into a checkout with the same Engine lock`);
+        else {
+            paths.push([fromTooling, toTooling]);
+            remapped.push(`Engine tooling ${fromTooling} → ${toTooling} (the same prepared Engine ${basename(toTooling)})`);
+        }
+    }
+    else if (fromTooling && !toTooling)
+        refused.push("this workspace's running plan names no Engine checkout to move the saved network's services to");
+    const fromPorts = readJson(join(input.snapshot, "network", "engine-ports.json")) ?? {};
+    const toPorts = input.livePorts ?? {};
+    const ports = new Map();
+    const keys = Object.keys(fromPorts).filter((key) => key in toPorts);
+    const deltas = new Set(keys.map((key) => toPorts[key] - fromPorts[key]));
+    if (keys.length && deltas.size > 1)
+        refused.push(`its Engine ports are laid out differently from this block's (${deltas.size} different offsets), so they cannot be moved as one block`);
+    const delta = deltas.size === 1 ? [...deltas][0] : 0;
+    if (delta !== 0 && deltas.size === 1) {
+        const planned = readJson(join(input.snapshot, "network.json"))?.ports ?? [];
+        const listened = saved.processes.flatMap((entry) => listenedPorts(entry.plan.args ?? []).map((item) => item.port));
+        const known = [...Object.values(fromPorts), ...planned, ...listened];
+        const low = Math.min(...known);
+        const high = Math.max(...known);
+        if (low + delta < 1024 || high + delta > 65535)
+            refused.push(`the block ${low}-${high} would move outside the valid port range (${low + delta}-${high + delta})`);
+        for (let port = low; port <= high; port++)
+            ports.set(port, port + delta);
+        remapped.push(`ports: the block ${low}-${high} moved by ${delta > 0 ? "+" : ""}${delta} to ${low + delta}-${high + delta}, wherever a port is named (plan arguments and environment, session endpoints, Engine ports, isolation and zombienet records, chain spec boot nodes, IPFS addresses)`);
+    }
+    const rewrite = [...TEXT_FILES, ...extraFiles(input.snapshot), ...(ports.size ? chainSpecs(input.snapshot) : [])].filter((file) => existsSync(join(input.snapshot, file)));
+    const remove = REGENERATED.filter((file) => existsSync(join(input.snapshot, file)));
+    if (remove.length && (paths.length || ports.size))
+        remapped.push(`removed ${remove.join(", ")} (PostgreSQL writes it again at start)`);
+    for (const block of ipfsBlocksNaming(input.snapshot, ports))
+        refused.push(`${block} is content-addressed IPFS data naming a loopback port of the old block; it cannot be rewritten without changing its content id (import into the same port block)`);
+    if (paths.length || ports.size) {
+        const rewritten = new Set([...rewrite, ...remove]);
+        for (const file of scannable(input.snapshot)) {
+            if (rewritten.has(file))
+                continue;
+            const text = readFileSync(join(input.snapshot, file)).toString("latin1");
+            const { paths: namedPaths, ports: namedPorts } = rewriteText(text, paths, ports);
+            if (namedPaths || namedPorts)
+                refused.push(`${file} names the old ${namedPaths ? "workspace or Engine" : "ports"} and is not a file adoption rewrites`);
+        }
+    }
+    if (!refused.length && paths.length + ports.size === 0)
+        remapped.push("nothing to move: the same workspace directory, Engine and port block");
+    if (!refused.length && (paths.length || ports.size))
+        remapped.push("not examined: chain databases (no file paths), the identity backend's database rows, RocksDB LOG files (history only)");
+    return { remapped, refused, paths, ports, rewrite, remove };
+}
+export function applyNetworkAdoption(plan, directory) {
+    const changed = [];
+    for (const file of plan.rewrite) {
+        const path = join(directory, file);
+        if (!existsSync(path))
+            continue;
+        const before = readFileSync(path, "utf8");
+        const result = rewriteText(before, plan.paths, plan.ports);
+        if (result.text !== before) {
+            writeFileSync(path, result.text, { mode: lstatSync(path).mode & 0o777 });
+            changed.push({ file, paths: result.paths, ports: result.ports });
+        }
+    }
+    for (const file of plan.remove)
+        rmSync(join(directory, file), { force: true });
+    return changed;
+}
+export const ADOPTED_LINEAGE = "adopted-lineage.json";
+export function readAdoptedLineage(directory) {
+    const record = readJson(join(directory, "network", ADOPTED_LINEAGE));
+    return typeof record?.lineage === "string" && record.lineage ? record.lineage : undefined;
+}

package/adapters/environment/engine/src/engine/network-plan.d.ts

@@ -0,0 +1,71 @@
+import type { ProcessPlan, SyncCommandRunner } from "@parity/product-lab/ports/system";
+import type { EngineSession } from "../session/session.js";
+import type { EngineConfiguration } from "./engine-config.js";
+import { type PortRange } from "./plan-ports.js";
+import { type ForkIsolation, type NodeKeys } from "./fork-isolation.js";
+/** Version 2 is an isolated network (fork-isolation.ts); version 1 predates isolation. */
+export interface NetworkPlan {
+    version: 1 | 2;
+    session: EngineSession;
+    directory: string;
+    processes: {
+        id: string;
+        plan: ProcessPlan;
+    }[];
+    ports: number[];
+    isolation?: ForkIsolation;
+}
+/** The first boot's effective config/ports.env (applyEnginePorts), kept with the network's data. */
+export declare const ENGINE_PORTS_FILE = "engine-ports.json";
+/** What completes a saved plan: the ports config/ports.env gave the network, and the range for the rest. */
+export interface PlanFacts {
+    /** config/ports.env's effective values (engine-ports.json, or engine.json `ports` for an older network). */
+    enginePorts: Record<string, number>;
+    /** engine.json `nodePorts`. */
+    nodePorts?: PortRange;
+}
+/**
+ * The saved plan, completed: Engine's eth-rpc on its reserved port, and with
+ * `nodePorts` every port inside the workspace's own ports (containPlanPorts),
+ * around the `taken` ones. Pure and idempotent; `moved` lists the ports renamed (the chain spec copies
+ * must follow: remapSpecBootNodePorts).
+ */
+export declare function completePlan(plan: NetworkPlan, facts: PlanFacts, taken?: Iterable<number>): {
+    plan: {
+        ports: number[];
+        version: 1 | 2;
+        session: EngineSession;
+        directory: string;
+        processes: {
+            id: string;
+            plan: ProcessPlan;
+        }[];
+        isolation?: ForkIsolation;
+    };
+    moved: Map<number, number>;
+    ethRpcUnavailable: string | undefined;
+};
+/** The facts a saved network was completed with: engine-ports.json (first boots since eth-rpc), else engine.json. */
+export declare function planFacts(data: string, config: Pick<EngineConfiguration, "ports" | "nodePorts"> | undefined): PlanFacts;
+/** The resume plan with fork isolation applied to its node processes and IPFS repository (network.json version 2). */
+export declare function isolatedPlan(plan: NetworkPlan, options: {
+    expose: boolean;
+    keys?: NodeKeys;
+    rotateIpfs?: (repository: string) => void;
+    commands?: SyncCommandRunner;
+}): {
+    plan: NetworkPlan;
+    applied: {
+        ipfs: {
+            peerId: string;
+            rotated: boolean;
+        } | undefined;
+        isolation: ForkIsolation;
+        args: Record<string, string[]>;
+        specs: string[];
+        rekeyed: string[];
+        cachesCleared: string[];
+    };
+};
+/** Resume persisted node databases; never replay genesis funding or scheduling scripts. */
+export declare function resumePlan(directory: string, session: EngineSession): NetworkPlan;

package/adapters/environment/engine/src/engine/network-plan.js

@@ -0,0 +1,158 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readFileSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { containPlanPorts, planPorts, withEthRpc } from "./plan-ports.js";
+import { ipfsIdentityRotation, isolateIpfsRepository, isolatePersistedNetwork } from "./fork-isolation.js";
+export const ENGINE_PORTS_FILE = "engine-ports.json";
+export function completePlan(plan, facts, taken = []) {
+    const home = plan.processes.map((entry) => entry.plan.env?.PPN_HOME).find((value) => !!value) ?? engineHome(plan);
+    const eth = withEthRpc(plan, { port: facts.enginePorts.ETH_RPC_PORT, home });
+    let completed = eth.plan;
+    let moved = new Map();
+    if (facts.nodePorts) {
+        const contained = containPlanPorts(completed, facts.nodePorts, Object.values(facts.enginePorts), taken);
+        completed = contained.plan;
+        moved = contained.moved;
+    }
+    return { plan: { ...completed, ports: planPorts(completed) }, moved, ethRpcUnavailable: eth.reason };
+}
+function engineHome(plan) {
+    const postgres = plan.processes.find((entry) => entry.id === "network-postgres")?.plan.command ?? "";
+    const at = postgres.indexOf("/bin/postgres-dist/");
+    return at === -1 ? "" : postgres.slice(0, at);
+}
+export function planFacts(data, config) {
+    let enginePorts = { ...(config?.ports ?? {}) };
+    try {
+        enginePorts = { ...enginePorts, ...JSON.parse(readFileSync(join(data, ENGINE_PORTS_FILE), "utf8")) };
+    }
+    catch {
+    }
+    return { enginePorts, ...(config?.nodePorts ? { nodePorts: config.nodePorts } : {}) };
+}
+export function isolatedPlan(plan, options) {
+    const applied = isolatePersistedNetwork(plan.directory, options);
+    const ipfsProcess = plan.processes.find((entry) => entry.id === "network-ipfs")?.plan;
+    const repository = ipfsProcess?.env?.IPFS_PATH;
+    if (repository && !options.rotateIpfs && !options.commands)
+        throw new Error("IPFS identity rotation needs synchronous commands");
+    const ipfs = repository
+        ? isolateIpfsRepository(repository, {
+            expose: options.expose,
+            rotate: options.rotateIpfs ?? ipfsIdentityRotation(ipfsProcess.command, options.commands),
+        })
+        : undefined;
+    if (ipfs)
+        applied.isolation.ipfsPeerId = ipfs.peerId;
+    const processes = plan.processes.map((entry) => {
+        const args = applied.args[entry.id.replace(/^network-/, "")];
+        return args ? { ...entry, plan: { ...entry.plan, args } } : entry;
+    });
+    const isolated = { ...plan, version: 2, processes, isolation: applied.isolation };
+    return { plan: isolated, applied: { ...applied, ipfs } };
+}
+export function resumePlan(directory, session) {
+    if (session.schemaVersion !== 1)
+        throw new Error("Persistent hosted workspaces require the full network");
+    const topology = JSON.parse(readFileSync(join(directory, "zombie.json"), "utf8"));
+    const nodes = [
+        ...topology.relay.nodes,
+        ...Object.values(topology.parachains).flatMap((groups) => groups.flatMap((group) => group.collators)),
+    ];
+    const processes = [];
+    const ports = nodes.map((node) => Number(new URL(node.ws_uri).port));
+    for (const node of nodes) {
+        if (relative(directory, node.inner.data_dir).startsWith("..") ||
+            !existsSync(node.inner.data_dir))
+            throw new Error("Node data is outside the persisted network or missing");
+        processes.push({
+            id: `network-${node.name}`,
+            plan: {
+                command: node.inner.program,
+                args: node.inner.args,
+                env: Object.fromEntries(node.inner.env),
+            },
+        });
+    }
+    const services = topology.initial_spec.custom_processes;
+    const postgres = services.find((p) => p.name === "dub-postgres");
+    if (!postgres)
+        throw new Error("Missing identity database service");
+    const env = Object.fromEntries(postgres.env.map((e) => [e.name, e.value]));
+    const home = env.PPN_HOME;
+    if (!home)
+        throw new Error("Missing Engine workspace");
+    const db = join(directory, "identity-pgdata");
+    if (!existsSync(join(db, "PG_VERSION")))
+        throw new Error("Saved identity database is missing; refusing to initialize a replacement");
+    const api = services.find((p) => p.name === "dub-api");
+    const apiEnv = Object.fromEntries(api.env.map((e) => [e.name, e.value]));
+    const databaseUrl = new URL(apiEnv.DEVICE_ATTESTATION_DATABASE_URL);
+    const pgPort = Number(databaseUrl.port || 5432);
+    ports.push(pgPort, Number(new URL(session.identityBackend).port), Number(new URL(session.engine.dashboard).port));
+    processes.push({
+        id: "network-postgres",
+        plan: {
+            command: join(home, "bin/postgres-dist/bin/postgres"),
+            args: [
+                "-D",
+                db,
+                "-p",
+                String(pgPort),
+                "-c",
+                "listen_addresses=127.0.0.1",
+                "-c",
+                "unix_socket_directories=",
+            ],
+            env: {},
+        },
+    });
+    const ipfs = join(directory, "lab-ipfs");
+    if (existsSync(join(ipfs, "config"))) {
+        const config = JSON.parse(readFileSync(join(ipfs, "config"), "utf8"));
+        for (const address of [
+            config.Addresses.API,
+            config.Addresses.Gateway,
+            ...config.Addresses.Swarm,
+        ]) {
+            const match = /\/tcp\/(\d+)/.exec(address);
+            if (match)
+                ports.push(Number(match[1]));
+        }
+        processes.push({
+            id: "network-ipfs",
+            plan: {
+                command: join(home, "bin/ipfs"),
+                args: ["daemon"],
+                env: { IPFS_PATH: ipfs },
+            },
+        });
+    }
+    for (const name of [
+        "dashboard",
+        "dub-api",
+        "device-attestation-chain-writer",
+        "registration-queue",
+        "invite-tickets-pool",
+    ]) {
+        const service = services.find((p) => p.name === name);
+        if (!service)
+            throw new Error(`Missing persisted service: ${name}`);
+        processes.push({
+            id: `network-${name}`,
+            plan: {
+                command: service.command,
+                args: service.args ?? [],
+                env: Object.fromEntries(service.env.map((e) => [e.name, e.value])),
+            },
+        });
+    }
+    return {
+        version: 1,
+        session,
+        directory,
+        processes,
+        ports: [...new Set(ports)],
+    };
+}

package/adapters/environment/engine/src/engine/network-reset.d.ts

@@ -0,0 +1,18 @@
+import type { Logger, SyncCommandRunner } from "@parity/product-lab/ports/system";
+import { type RestoredNetwork } from "./network-template.js";
+export type NetworkReset = {
+    readonly method: "template";
+    readonly restored: RestoredNetwork;
+    readonly stopMs: number;
+} | {
+    readonly method: "fork-again";
+    readonly reason: string;
+    readonly stopMs: number;
+};
+export declare function resetPersistentNetwork(directory: string, options: {
+    /** Stop what runs of the saved network (its processes; hosts and sessions are the caller's). */
+    stop: () => Promise<void>;
+    sessionFile: string;
+    commands: SyncCommandRunner;
+    logger?: Pick<Logger, "info" | "warn">;
+}): Promise<NetworkReset>;

package/adapters/environment/engine/src/engine/network-reset.js

@@ -0,0 +1,21 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { hasNetworkTemplate, restoreNetworkTemplate } from "./network-template.js";
+export async function resetPersistentNetwork(directory, options) {
+    const started = performance.now();
+    await options.stop();
+    const stopMs = Math.round(performance.now() - started);
+    const data = join(directory, "network");
+    rmSync(join(directory, "network.json"), { force: true });
+    rmSync(data, { recursive: true, force: true });
+    if (!hasNetworkTemplate(directory)) {
+        const reason = `${directory} keeps no template (created before templates, or engine.json template: false)`;
+        options.logger?.warn(`Reset: ${reason}; forking the live network again, which takes minutes and saves a template when engine.json asks for one`);
+        return { method: "fork-again", reason, stopMs };
+    }
+    const restored = restoreNetworkTemplate(directory, { data, sessionFile: options.sessionFile, commands: options.commands, ...(options.logger ? { logger: options.logger } : {}) });
+    options.logger?.info(`Reset: restored the first boot's template (${restored.copy}, ${(restored.ms / 1000).toFixed(1)} s) as a new generation (run ${restored.session.runId}; was ${restored.from.runId})`);
+    return { method: "template", restored, stopMs };
+}