@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/environment/engine/src/engine/fork-toml.js

@@ -0,0 +1,260 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isolateNodeArgs, COLLATOR_WRAPPER } from "./node-isolation.js";
+const SECTION = /^\[\[?([\w.]+)\]\]?\s*$/;
+const NODE_ARG_SECTIONS = {
+    relaychain: "default_args",
+    parachains: "default_args",
+    "relaychain.nodes": "args",
+    "parachains.collators": "args",
+};
+const NODE_SECTIONS = new Set(["relaychain.nodes", "parachains.collators"]);
+function missingPortKeys(keys) {
+    return ["prometheus_port", "p2p_port"].filter((key) => !keys.has(key));
+}
+export function assignForkTomlPorts(toml, options) {
+    return planForkTomlPorts(toml, options).toml;
+}
+export function planForkTomlPorts(toml, options) {
+    const lines = toml.split("\n");
+    const sections = [];
+    const used = new Set([...(options.nodePorts?.named ?? []), ...(options.nodePorts?.taken ?? [])]);
+    lines.forEach((line, index) => {
+        const header = SECTION.exec(line);
+        if (header) {
+            sections.push({ kind: header[1], start: index, end: index, keys: new Set() });
+            return;
+        }
+        const current = sections.at(-1);
+        const key = /^(\w+)\s*=\s*(.*)$/.exec(line);
+        if (current && key) {
+            current.keys.add(key[1]);
+            current.end = index;
+            if (key[1] === "name")
+                current.name = /^"(.*)"$/.exec(key[2].trim())?.[1];
+            if (/_port$/.test(key[1]) && /^\d+$/.test(key[2].trim()))
+                used.add(Number(key[2].trim()));
+        }
+        for (const match of line.matchAll(/\/(?:tcp|udp)\/(\d+)/g))
+            used.add(Number(match[1]));
+    });
+    const range = options.nodePorts?.range;
+    let next = range?.from ?? 0;
+    const allocate = () => {
+        while (range && next <= range.to && used.has(next))
+            next++;
+        if (!range || next > range.to)
+            throw new Error(`The fork needs more node ports than nodePorts ${range?.from}-${range?.to} holds; widen the range in engine.json`);
+        used.add(next);
+        return next++;
+    };
+    const inserts = new Map();
+    const replaced = new Map();
+    for (const section of sections) {
+        if (range && NODE_SECTIONS.has(section.kind))
+            inserts.set(section.end, missingPortKeys(section.keys).map((key) => `${key} = ${allocate()}`));
+        if (options.ethRpc && section.kind === "custom_processes" && section.name === "eth-rpc") {
+            for (let index = section.start + 1; index <= section.end; index++) {
+                const key = /^(\w+)\s*=/.exec(lines[index])?.[1];
+                if (key === "command")
+                    replaced.set(index, `command = ${JSON.stringify(options.ethRpc.command)}`);
+                else if (key === "args")
+                    replaced.set(index, null);
+            }
+            inserts.set(section.end, [...(inserts.get(section.end) ?? []), `args = ${JSON.stringify(options.ethRpc.args)}`]);
+        }
+    }
+    const relayPorts = {};
+    if (range)
+        for (const section of sections)
+            if (section.kind === "parachains.collators" && section.name)
+                relayPorts[section.name] = { port: allocate(), prometheus: allocate() };
+    const out = [];
+    lines.forEach((line, index) => {
+        const replacement = replaced.get(index);
+        if (replacement !== null)
+            out.push(replacement ?? line);
+        out.push(...(inserts.get(index) ?? []));
+    });
+    return { toml: out.join("\n"), relayPorts };
+}
+export function isolateForkToml(toml, options) {
+    let section = "";
+    let collators = 0;
+    let isolatedCollators = 0;
+    let wrappedCollators = 0;
+    const lines = toml.split("\n").map((line) => {
+        const header = SECTION.exec(line);
+        if (header) {
+            section = header[1];
+            if (section === "parachains.collators")
+                collators++;
+            return line;
+        }
+        const args = /^(default_args|args)\s*=\s*(\[.*\])\s*$/.exec(line);
+        if (args && NODE_ARG_SECTIONS[section] === args[1]) {
+            let list;
+            try {
+                list = JSON.parse(args[2]);
+            }
+            catch {
+                throw new Error(`Cannot read the ${section} ${args[1]} list of the zombienet config`);
+            }
+            if (!Array.isArray(list) || !list.every((item) => typeof item === "string"))
+                throw new Error(`The ${section} ${args[1]} of the zombienet config is not a list of strings`);
+            if (section === "parachains.collators")
+                isolatedCollators++;
+            const isolated = isolateNodeArgs(list, { expose: options.expose, collator: section === "parachains.collators", ...(options.txpoolLog ? { txpoolLog: options.txpoolLog } : {}), ...(options.bulletinAuthoring ? { bulletinAuthoring: options.bulletinAuthoring } : {}) });
+            return `${args[1]} = ${JSON.stringify(section === "relaychain" ? withArgs(isolated, options.relayArgs ?? []) : isolated)}`;
+        }
+        if (options.nodeCommand && section === "relaychain" && /^default_command\s*=/.test(line))
+            return `default_command = ${JSON.stringify(options.nodeCommand)}`;
+        if (options.nodeCommand && section === "relaychain.nodes" && /^command\s*=/.test(line))
+            throw new Error("Fork isolation wraps the relay chain's default_command; a relay node with its own command is not supported");
+        const command = /^command\s*=\s*"(.*\/omni-node\.sh)"\s*$/.exec(line);
+        if (command && section === "parachains.collators") {
+            wrappedCollators++;
+            return `command = ${JSON.stringify(options.collatorCommand)}`;
+        }
+        return line;
+    });
+    if (isolatedCollators !== collators || wrappedCollators !== collators)
+        throw new Error(`Fork isolation needs an args list and Engine's omni-node.sh launcher on every collator (${collators} collators, ${isolatedCollators} with args, ${wrappedCollators} launched by omni-node.sh)`);
+    const isolated = lines.join("\n");
+    return options.nodePorts || options.ethRpc ? assignForkTomlPorts(isolated, options) : isolated;
+}
+function withArgs(list, extra) {
+    const added = [];
+    for (let index = 0; index < extra.length; index++) {
+        const flag = extra[index];
+        const value = extra[index + 1]?.startsWith("--") === false ? extra[++index] : undefined;
+        if (list.some((arg) => arg === flag || arg.startsWith(`${flag}=`)))
+            continue;
+        added.push(flag, ...(value !== undefined ? [value] : []));
+    }
+    return [...list, ...added];
+}
+function shellCase(ports) {
+    const cases = Object.entries(ports).map(([name, { port, prometheus }]) => `  ${shellQuote(name)}) p2p=${port}; prom=${prometheus} ;;`);
+    return cases.length ? `case "$name" in\n${cases.join("\n")}\nesac\n` : "";
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function collatorWrapperScript(engineLauncher, relayPorts = {}, 
+options = {}) {
+    const loopback = options.loopback ?? false;
+    return `#!/usr/bin/env bash
+# Written by product-lab (fork isolation): run Engine's collator launcher, and
+# give the collator's relay side (the arguments after --) --no-mdns${Object.keys(relayPorts).length ? " and its\n# workspace's own --port and --prometheus-port (zombie-cli picks free ones)" : ""}.${loopback ? "\n# Both sides listen on loopback only (zombie-cli passes 0.0.0.0, --prometheus-external and a bare --port)." : ""}
+set -euo pipefail
+name=""
+prev=""
+for arg in "$@"; do
+  if [[ "$arg" == "--" ]]; then break; fi
+  if [[ "$prev" == "--name" ]]; then name="$arg"; fi
+  prev="$arg"
+done
+p2p=""
+prom=""
+${shellCase(relayPorts)}loopback=${loopback ? 1 : 0}
+from=${options.range?.from ?? 0}
+to=${options.range?.to ?? 0}
+# zombie-cli's choice is replaced; a port inside the range is the saved plan's (a resume) and is kept.
+ours() { [[ $to -gt 0 && "$1" =~ ^[0-9]+$ && $1 -ge $from && $1 -le $to ]]; }
+out=()
+relay=0
+mdns=0
+value=""
+port=""
+for arg in "$@"; do
+  if [[ -n "$port" ]]; then
+    if [[ -n "$p2p" ]] && ! ours "$arg"; then arg="$p2p"; fi
+    out+=("--listen-addr" "/ip4/127.0.0.1/tcp/$arg"); port=""; continue
+  fi
+  if [[ -n "$value" ]]; then
+    if ours "$arg"; then out+=("$arg"); else out+=("$value"); fi
+    value=""; continue
+  fi
+  if [[ "$arg" == "--" ]]; then relay=1; fi
+  if [[ $relay == 1 && "$arg" == "--no-mdns" ]]; then mdns=1; fi
+${LOOPBACK_REWRITE}
+  if [[ $relay == 1 && $loopback == 1 && "$arg" == "--port" ]]; then port=1; continue; fi
+  if [[ $relay == 1 && -n "$p2p" && "$arg" == "--port" ]]; then out+=("$arg"); value="$p2p"; continue; fi
+  if [[ $relay == 1 && -n "$prom" && "$arg" == "--prometheus-port" ]]; then out+=("$arg"); value="$prom"; continue; fi
+  out+=("$arg")
+done
+if [[ $relay == 1 && $mdns == 0 ]]; then
+  exec ${shellQuote(engineLauncher)} \${out[@]+"\${out[@]}"} --no-mdns
+fi
+exec ${shellQuote(engineLauncher)} \${out[@]+"\${out[@]}"}
+`;
+}
+const LOOPBACK_REWRITE = `  if [[ $loopback == 1 ]]; then
+    case "$arg" in
+      --prometheus-external|--rpc-external|--unsafe-rpc-external) continue ;;
+    esac
+    any4="/ip4/0.0.0.0/"; lo4="/ip4/127.0.0.1/"; any6="/ip6/::/"; lo6="/ip6/::1/"
+    arg="\${arg//$any4/$lo4}"
+    arg="\${arg//$any6/$lo6}"
+  fi`;
+export function nodeWrapperScript(binary, options) {
+    return `#!/usr/bin/env bash
+# Written by product-lab (fork isolation): run the relay node binary${options.expose ? "" : " with loopback\n# listeners only (zombie-cli passes 0.0.0.0 and --prometheus-external)"}.
+set -euo pipefail
+loopback=${options.expose ? 0 : 1}
+out=()
+for arg in "$@"; do
+${LOOPBACK_REWRITE}
+  out+=("$arg")
+done
+exec ${shellQuote(binary)} \${out[@]+"\${out[@]}"}
+`;
+}
+export function moveForkTomlPorts(toml, ports) {
+    let moved = 0;
+    const left = new Set();
+    const move = (value) => {
+        const next = ports.get(Number(value));
+        if (next === undefined) {
+            left.add(Number(value));
+            return value;
+        }
+        moved++;
+        return String(next);
+    };
+    const out = toml
+        .split("\n")
+        .map((line) => {
+        if (/^\s*#/.test(line))
+            return line;
+        return line
+            .replace(/^(\s*\w+_port\s*=\s*)(\d+)(\s*(?:#.*)?)$/, (_match, key, port, rest) => `${key}${move(port)}${rest}`)
+            .replace(/((?:127\.0\.0\.1|localhost|0\.0\.0\.0):)(\d{2,5})\b/g, (_match, host, port) => `${host}${move(port)}`)
+            .replace(/\/(tcp|udp)\/(\d{2,5})\b/g, (_match, protocol, port) => `/${protocol}/${move(port)}`)
+            .replace(/("--(?:rpc-port|port|prometheus-port)",\s*")(\d{2,5})"/g, (_match, flag, port) => `${flag}${move(port)}"`);
+    })
+        .join("\n");
+    return { toml: out, moved, left: [...left].sort((a, b) => a - b) };
+}
+export const NODE_WRAPPER_DIRECTORY = "relay";
+export function writeIsolatedForkToml(options) {
+    const raw = readFileSync(options.rawToml, "utf8");
+    const launcher = /^command\s*=\s*"(.*\/omni-node\.sh)"\s*$/m.exec(raw)?.[1];
+    if (!launcher)
+        throw new Error("The fork's zombienet config launches no collator through omni-node.sh");
+    const collatorCommand = join(options.directory, COLLATOR_WRAPPER);
+    const relayBinary = /^\[relaychain\]\s*$[\s\S]*?^default_command\s*=\s*"(.*)"\s*$/m.exec(raw)?.[1];
+    const nodeCommand = !options.expose && relayBinary ? join(options.directory, NODE_WRAPPER_DIRECTORY, basename(relayBinary)) : undefined;
+    if (nodeCommand) {
+        mkdirSync(dirname(nodeCommand), { recursive: true });
+        writeFileSync(nodeCommand, nodeWrapperScript(relayBinary, { expose: false }), { mode: 0o755 });
+    }
+    const isolated = isolateForkToml(raw, { expose: options.expose, collatorCommand, ...(options.txpoolLog ? { txpoolLog: options.txpoolLog } : {}), ...(options.bulletinAuthoring ? { bulletinAuthoring: options.bulletinAuthoring } : {}), ...(nodeCommand ? { nodeCommand } : {}), ...(options.relayArgs?.length ? { relayArgs: options.relayArgs } : {}) });
+    const planned = options.nodePorts || options.ethRpc ? planForkTomlPorts(isolated, options) : { toml: isolated, relayPorts: {} };
+    writeFileSync(collatorCommand, collatorWrapperScript(launcher, planned.relayPorts, { loopback: !options.expose, ...(options.nodePorts ? { range: options.nodePorts.range } : {}) }), { mode: 0o755 });
+    writeFileSync(options.toml, planned.toml, { mode: 0o600 });
+    return { collatorCommand, ...(nodeCommand ? { nodeCommand } : {}) };
+}

package/adapters/environment/engine/src/engine/fork-topology.d.ts

@@ -0,0 +1,65 @@
+export declare const FORK_TOPOLOGIES: readonly ["faithful", "light"];
+export type ForkTopologyName = (typeof FORK_TOPOLOGIES)[number];
+export interface ForkLayout {
+    readonly name: Exclude<ForkTopologyName, "faithful">;
+    /** `ppn bite` and `ppn start` flags: the bite lays the cores out with them, and `start` checks the bundle against them. */
+    readonly engineArgs: readonly string[];
+    /** Appended to every relay node's arguments (the isolated zombienet config's relay chain `default_args`). */
+    readonly relayArgs: readonly string[];
+    /** The descriptor overlay per Engine network: an entry of patches/previewnet-engine/manifest.json (`DESCRIPTOR_OVERLAYS`). */
+    readonly descriptors: Readonly<Record<string, string>>;
+    /** Where its first bundle comes from (backlog 184): `LIGHT_BUNDLE_SOURCE` for `light`. */
+    readonly bundleSource: LayoutBundleSource;
+}
+/**
+ * Where a layout's first bundle comes from. `bite`: bitten on this machine (about 20 minutes on 16 cores), because
+ * Engine publishes bundles of its own layout only. `published`: Engine's own bundle of this layout, fetched like the
+ * faithful one (`ppn fork fetch-bundle`), with `asset` naming it on Engine's rolling bite release
+ * (`PPN_FORK_BUNDLE_ASSET`).
+ */
+export type LayoutBundleSource = {
+    readonly source: "bite";
+} | {
+    readonly source: "published";
+    readonly asset: (network: string) => string;
+};
+/**
+ * Backlog 184: the light layout's bundle source. Off (`bite`) until Engine publishes a light bundle; it publishes none
+ * as of Engine 7907a3b, whose `ppn fork fetch-bundle` always takes `fork-bundle-<network>.tar.gz` (an upstream item,
+ * docs/verification/2026-10-06-environment-options.md). To turn it on, one setting and a version bump: set
+ * `{ source: "published", asset: (network) => "<its asset>" }` here and move the Engine pin in lab.lock.json to the
+ * first Engine version that publishes it and reads `PPN_FORK_BUNDLE_ASSET`. A light fork's first start then downloads
+ * it instead of biting (`publishesLayout`); --refresh stays Engine's faithful bundle only.
+ */
+export declare const LIGHT_BUNDLE_SOURCE: LayoutBundleSource;
+/** Whether Engine publishes this layout's bundles: faithful always; another when its bundle source is `published`. */
+export declare function publishesLayout(name: ForkTopologyName | undefined, layouts?: Readonly<Record<ForkLayout["name"], ForkLayout>>): boolean;
+/** The layout of `name` on `network`; undefined for `faithful`. Refuses a network the layout has no descriptor for. */
+export declare function forkLayout(name: ForkTopologyName | undefined, network: string, layouts?: Readonly<Record<ForkLayout["name"], ForkLayout>>): ForkLayout | undefined;
+/**
+ * The Engine workspace a fork of this layout uses: Engine's own for `faithful`; for another, `<workspace>.<name>`,
+ * created on first use with Engine's `bin/` cloned in (a copy-on-write clone where the file system has one). That
+ * includes Engine's IPFS repository (`bin/.ipfs`) but not a running daemon's `api` file or lock: the lab sets the
+ * repository's ports and loopback isolation before each start, and without a repository Engine's start creates a
+ * default one afterwards (all interfaces, the default ports), which a light fork's first boot did on 5 October 2026.
+ * Each persisted copy rotates its IPFS identity (ipfs-isolation.ts), so sharing the repository's identity here is safe.
+ */
+export declare function forkTopologyWorkspace(engine: {
+    readonly workspace: string;
+}, name: ForkTopologyName | undefined): string;
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** `base` with `overlay` merged in: objects key by key, everything else replaced. */
+export declare function mergeDescriptor(base: Json, overlay: Json): Json;
+/**
+ * Write the layout's descriptor into its workspace (`networks/<network>.json`, which Engine reads before the
+ * checkout's): the workspace's current descriptor (the TURN relay choice's copy, turn-relay.ts) or else the checkout's,
+ * with the overlay merged in. Run after the TURN relay choice, before every start.
+ */
+export declare function applyForkLayoutDescriptor(layout: ForkLayout, input: {
+    checkout: string;
+    workspace: string;
+    network: string;
+}): string;
+export {};

package/adapters/environment/engine/src/engine/fork-topology.js

@@ -0,0 +1,61 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { constants, cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { DESCRIPTOR_OVERLAYS } from "../setup/patch-catalogue.js";
+const RUNNING_DAEMON = new Set(["api", "repo.lock"]);
+export const FORK_TOPOLOGIES = ["faithful", "light"];
+export const LIGHT_BUNDLE_SOURCE = { source: "bite" };
+const LAYOUTS = {
+    light: {
+        name: "light",
+        engineArgs: ["--cores", "asset-hub=1"],
+        relayArgs: ["--execute-workers-max-num", "1", "--prepare-workers-soft-max-num", "1", "--prepare-workers-hard-max-num", "1"],
+        descriptors: { "paseo-next-v2": "light-topology", previewnet: "light-topology" },
+        bundleSource: LIGHT_BUNDLE_SOURCE,
+    },
+};
+export function publishesLayout(name, layouts = LAYOUTS) {
+    return !name || name === "faithful" || layouts[name].bundleSource.source === "published";
+}
+export function forkLayout(name, network, layouts = LAYOUTS) {
+    if (!name || name === "faithful")
+        return undefined;
+    const layout = layouts[name];
+    if (!layout.descriptors[network])
+        throw new Error(`The ${name} fork topology is defined for ${Object.keys(layout.descriptors).join(", ")}, not ${network}`);
+    return layout;
+}
+export function forkTopologyWorkspace(engine, name) {
+    if (!name || name === "faithful")
+        return engine.workspace;
+    const workspace = `${engine.workspace}.${name}`;
+    const bin = join(engine.workspace, "bin");
+    const clone = (from, to) => cpSync(from, to, { recursive: true, mode: constants.COPYFILE_FICLONE, filter: (source) => !(basename(dirname(source)) === ".ipfs" && RUNNING_DAEMON.has(basename(source))) });
+    if (!existsSync(join(workspace, "bin")) && existsSync(bin))
+        clone(bin, join(workspace, "bin"));
+    else if (!existsSync(join(workspace, "bin", ".ipfs")) && existsSync(join(bin, ".ipfs")))
+        clone(join(bin, ".ipfs"), join(workspace, "bin", ".ipfs"));
+    mkdirSync(workspace, { recursive: true });
+    return workspace;
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export function mergeDescriptor(base, overlay) {
+    if (!isObject(base) || !isObject(overlay))
+        return overlay;
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(overlay))
+        merged[key] = mergeDescriptor(base[key] ?? null, value);
+    return merged;
+}
+export function applyForkLayoutDescriptor(layout, input) {
+    const name = layout.descriptors[input.network];
+    const overlay = DESCRIPTOR_OVERLAYS[name];
+    if (overlay === undefined)
+        throw new Error(`The ${layout.name} fork topology names descriptor overlay ${name}, which this adapter does not carry`);
+    const target = join(input.workspace, "networks", `${input.network}.json`);
+    const base = JSON.parse(readFileSync(existsSync(target) ? target : join(input.checkout, "networks", `${input.network}.json`), "utf8"));
+    mkdirSync(join(input.workspace, "networks"), { recursive: true });
+    writeFileSync(target, `${JSON.stringify(mergeDescriptor(base, overlay), null, 2)}\n`);
+    return target;
+}

package/adapters/environment/engine/src/engine/fork-updates.d.ts

@@ -0,0 +1,61 @@
+import type { EnvironmentRuntimeUpgrade, EnvironmentUpdate, StartPhaseSink } from "@parity/product-lab/ports/environment";
+import type { OwnedProcesses, SystemPorts } from "@parity/product-lab/ports/system";
+import { type ForkUpdateCommands, type ForkUpgradeTarget, type LiveCodeFetcher, type LiveRuntimeReader, type UpgradeDeps, type UpgradedRuntime, type ForkedChain } from "./fork-freshness.js";
+import { type RefreshHandle } from "./fork-refresh.js";
+export interface SavedForkUpdatesOptions {
+    /** The fork's saved directory (network.json, network/, session). */
+    readonly directory: string;
+    readonly engine: {
+        readonly checkout: string;
+        readonly workspace: string;
+        readonly extraPath: readonly string[];
+    };
+    readonly network: string;
+    readonly system: Pick<SystemPorts, "clock" | "environment" | "files" | "logger" | "rpc"> & {
+        readonly processes: {
+            open(directory: string): OwnedProcesses;
+        };
+    };
+    /** The live network's runtimes (the composition root's `readLiveRuntimes`). */
+    readonly readLive: LiveRuntimeReader;
+    /** The live code for `--update-runtime`, checked against its hash (the composition root's `liveCodeFetcher()`). */
+    readonly fetchCode: LiveCodeFetcher;
+    /** What this start was asked (`EnvironmentStartContext.update`). */
+    readonly update?: EnvironmentUpdate;
+    /**
+     * The lab's own RPC per chain for the live reads (3 October 2026; the environment's `rpc`, role `upstream`): over
+     * Engine's network file, chain by chain. Only read from (runtimes and, for `--update-runtime`, their code).
+     */
+    readonly liveRpc?: Readonly<Partial<Record<ForkedChain, string>>>;
+    readonly commands?: ForkUpdateCommands;
+    /**
+     * `false`: the fork is laid out otherwise than Engine publishes (fork-topology.ts), so no published state fits it:
+     * `--refresh` is refused and no newer state is fetched. Default true.
+     */
+    readonly published?: boolean;
+    readonly signal: AbortSignal;
+    readonly phase?: StartPhaseSink;
+    readonly fetch?: typeof fetch;
+    /** Tests: the upgrade (default Engine's `ppn upgrade`) and blocks to settle after one (default 16). */
+    readonly upgrade?: UpgradeDeps["upgrade"];
+    readonly settleBlocks?: number;
+}
+export interface SavedForkUpdates {
+    /** `--refresh`'s handle: the old fork set aside (undefined when not asked, or nothing newer is published). */
+    readonly refresh?: RefreshHandle;
+    /** The freshness line and a newer published state, as they are known (the environment's `notices`). */
+    notices(): string[];
+    /** The network runs: `--update-runtime` (before anything connects), the runtimes recorded, a refresh committed, a newer state fetched in the background. */
+    started(target: ForkUpgradeTarget): Promise<readonly UpgradedRuntime[]>;
+    /**
+     * The running (just restored) fork brought to the live network's runtimes in place, read again now (a saved
+     * fixture's `fixture refresh`: `networkSnapshots({ upgrade })`). Refused when the live network cannot be read.
+     */
+    upgradeToLive(target: ForkUpgradeTarget, signal: AbortSignal): Promise<EnvironmentRuntimeUpgrade>;
+    /** The start failed: a refresh puts the old fork back. */
+    failed(): void;
+    /** The environment is stopping: a background download stopped by it is not a failure. */
+    stopping(): void;
+}
+/** Before the network starts: `--refresh` when asked, then the live read beside the start. */
+export declare function savedForkUpdates(options: SavedForkUpdatesOptions): Promise<SavedForkUpdates>;

package/adapters/environment/engine/src/engine/fork-updates.js

@@ -0,0 +1,148 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { chainLabel, forkState, freshness, liveEndpoints, recordForkRuntimes, updateForkRuntimes, updateRuntimeCommand, } from "./fork-freshness.js";
+import { prefetchNewerState, prepareRefresh } from "./fork-refresh.js";
+export async function savedForkUpdates(options) {
+    const { system, network, engine, directory } = options;
+    if (options.update === "refresh" && options.published === false)
+        throw new Error(`This fork's layout is bitten on this machine and Engine publishes no state of it, so --refresh has nothing to refresh from: move ${directory} aside to fork the live network again, or run "${updateRuntimeCommand(options.commands)}" to bring its runtimes to the live ones`);
+    const log = system.logger;
+    const phase = options.phase ?? (() => { });
+    let refresh;
+    if (options.update === "refresh") {
+        const step = { id: "fork-refresh", title: "Newest published state" };
+        phase({ ...step, state: "active", detail: "checking what Engine publishes, then setting the old fork aside" });
+        try {
+            refresh = await prepareRefresh(directory, { engine, network, environment: system.environment, files: system.files, logger: log, processes: system.processes, signal: options.signal, ...(options.fetch ? { fetch: options.fetch } : {}) });
+        }
+        catch (error) {
+            phase({ ...step, state: "failed", detail: options.signal.aborted ? "stopped" : "nothing was changed" });
+            throw error;
+        }
+        phase(refresh ? { ...step, state: "done", detail: `bitten ${refresh.bundle.bittenAt}` } : { ...step, state: "skipped", detail: "the fork already runs it" });
+    }
+    const updateRuntime = options.update === "update-runtime";
+    const notices = {};
+    const fork = forkState(directory, engine.workspace, network, system.files);
+    const { sudo, ...fromFile } = liveEndpoints(engine, network);
+    const endpoints = { ...fromFile, ...options.liveRpc };
+    const check = { id: "fork-freshness", title: "Live runtimes" };
+    phase({ ...check, state: "active", detail: "reading what the live network runs" });
+    let lastLive;
+    const clock = system.clock;
+    const checked = options.readLive(endpoints, { network, clock, timeoutMs: updateRuntime ? 30_000 : 8000 }).then((live) => {
+        lastLive = live;
+        const result = freshness(fork, live, clock.date(), updateRuntime ? "updating it in place now (--update-runtime)" : updateRuntimeCommand(options.commands));
+        notices.freshness = result.line;
+        log.info(`${result.line} [checked in ${(live.durationMs / 1000).toFixed(1)} s]`);
+        phase(result.firstStart
+            ? { ...check, state: "skipped", detail: "first start: no fork on this machine yet, nothing to compare" }
+            : !result.checked
+                ? { ...check, state: "skipped", detail: "could not read the live network; starting the fork as it is" }
+                : result.changes.length
+                    ? { ...check, state: "done", detail: `changed live: ${result.changes.map((change) => chainLabel(change.chain)).join(", ")}` }
+                    : { ...check, state: "done", detail: `match live${Object.keys(result.unreachable).length ? `; could not read ${Object.keys(result.unreachable).map(chainLabel).join(", ")}` : ""}` });
+        return result;
+    });
+    checked.catch((error) => {
+        log.warn(`Could not compare the fork with the live network: ${error instanceof Error ? error.message : String(error)}`);
+        phase({ ...check, state: "skipped", detail: "the live read failed; starting the fork as it is" });
+    });
+    let stopping = false;
+    const current = () => forkState(directory, engine.workspace, network, system.files);
+    const upgradeDeps = (signal) => ({
+        engine,
+        network,
+        rpc: system.rpc,
+        files: system.files,
+        environment: system.environment,
+        logger: log,
+        clock,
+        signal,
+        fetchCode: options.fetchCode,
+        ...(sudo !== undefined ? { sudo } : {}),
+        ...(options.commands ? { commands: options.commands } : {}),
+        ...(options.upgrade ? { upgrade: options.upgrade } : {}),
+        ...(options.settleBlocks !== undefined ? { settleBlocks: options.settleBlocks } : {}),
+    });
+    return {
+        ...(refresh ? { refresh } : {}),
+        notices: () => [notices.freshness, notices.newer].filter((text) => !!text),
+        async started(target) {
+            let upgraded = [];
+            if (updateRuntime) {
+                const update = { id: "fork-update", title: "Runtime update" };
+                phase({ ...update, state: "active", detail: "waiting for the live read" });
+                try {
+                    const fresh = await checked;
+                    if (fresh.changes.length)
+                        phase({ ...update, state: "active", detail: `${fresh.changes.map((change) => chainLabel(change.chain)).join(", ")}: waiting for enactment (several minutes)` });
+                    upgraded = await updateForkRuntimes(target, fresh, upgradeDeps(options.signal));
+                }
+                catch (error) {
+                    phase({ ...update, state: "failed", detail: options.signal.aborted ? "stopped" : "see the message" });
+                    throw error;
+                }
+                phase(upgraded.length ? { ...update, state: "done", detail: `${upgraded.map((entry) => `${chainLabel(entry.chain)} ${entry.after.specVersion}`).join(", ")} = live` } : { ...update, state: "skipped", detail: "already live" });
+            }
+            refresh?.commit();
+            void checked
+                .then(() => {
+                const now = current();
+                if (now && lastLive)
+                    notices.freshness = freshness(now, lastLive, clock.date(), updateRuntimeCommand(options.commands)).line;
+            }, 
+            () => undefined)
+                .catch((error) => log.warn(`Could not update the freshness line: ${error instanceof Error ? error.message : String(error)}`));
+            await recordForkRuntimes(target, system.rpc, clock.date()).catch((error) => log.warn(`Could not record the fork's runtimes: ${error instanceof Error ? error.message : String(error)}`));
+            const bite = current();
+            if (options.published === false)
+                return upgraded;
+            void prefetchNewerState(bite?.bittenAt ? { bittenAt: bite.bittenAt } : undefined, {
+                engine,
+                network,
+                registry: target.registry,
+                environment: system.environment,
+                files: system.files,
+                logger: log,
+                ...(options.fetch ? { fetch: options.fetch } : {}),
+                ...(options.commands ? { commands: options.commands } : {}),
+                notice: (text) => {
+                    if (text)
+                        notices.newer = text;
+                    else
+                        delete notices.newer;
+                },
+                stopping: () => stopping,
+            }).catch((error) => log.warn(`The check for a newer published state failed: ${error instanceof Error ? error.message : String(error)}`));
+            return upgraded;
+        },
+        async upgradeToLive(target, signal) {
+            const live = await options.readLive(endpoints, { network, clock, timeoutMs: 30_000 });
+            const fork = current();
+            const fresh = freshness(fork, live, clock.date(), updateRuntimeCommand(options.commands));
+            log.info(`Upgrading the restored fork to the live runtimes: ${fresh.line}`);
+            const upgraded = await updateForkRuntimes(target, fresh, upgradeDeps(signal));
+            await recordForkRuntimes(target, system.rpc, clock.date()).catch((error) => log.warn(`Could not record the fork's runtimes: ${error instanceof Error ? error.message : String(error)}`));
+            const changed = new Set(upgraded.map((entry) => entry.chain));
+            return {
+                upgraded: upgraded.map((entry) => ({
+                    chain: entry.chain,
+                    from: { spec: `${entry.before.specName} ${entry.before.specVersion}`, codeHash: entry.before.codeHash },
+                    to: { spec: `${entry.after.specName} ${entry.after.specVersion}`, codeHash: entry.after.codeHash },
+                    migrated: entry.migrated,
+                })),
+                current: [...fresh.same, ...fresh.changes.map((change) => change.chain).filter((chain) => !changed.has(chain))],
+            };
+        },
+        failed() {
+            if (!refresh)
+                return;
+            refresh.rollback();
+            log.warn(`--refresh did not complete; ${refresh.setAside ? "the old fork and its identities are back as they were" : "nothing was kept of the new fork"}.`);
+        },
+        stopping() {
+            stopping = true;
+        },
+    };
+}

package/adapters/environment/engine/src/engine/ipfs-isolation.d.ts

@@ -0,0 +1,38 @@
+import type { SyncCommandRunner } from "@parity/product-lab/ports/system";
+/** Every address but loopback (127.0.0.0/8 and ::1). */
+export declare const LOOPBACK_ONLY_ADDRESS_FILTERS: string[];
+/**
+ * An IPFS (kubo) repository config, isolated: Engine's template joins the public
+ * IPFS network (`Bootstrap: ["auto"]`, default routing) with one identity that
+ * every fork copies. Engine only uses IPFS locally (pinning, `swarm connect` to
+ * this fork's Bulletin collator on 127.0.0.1), so isolation removes bootstrap
+ * peers and routing and keeps mDNS off. Kubo 0.39 still dialled public peers
+ * with those gone (verified live), so unless `expose` the swarm is bound to
+ * loopback and filtered to loopback addresses in both directions. Pure.
+ */
+export declare function isolateIpfsConfig(config: Record<string, unknown>, expose: boolean): Record<string, unknown>;
+/** Written into an IPFS repository once its identity is its own (the peer id). */
+export declare const IPFS_IDENTITY_MARKER = "product-lab-identity";
+/**
+ * Fail closed (backlog 144): a start the lab isolates refuses to run when Engine's IPFS repository does not exist yet.
+ * Isolation sets that repository's ports and loopback addresses before Engine runs; Engine's start would otherwise
+ * create a default one afterwards (`ipfs init --profile server`: every interface, port 4001, public bootstrap peers),
+ * which a light fork's first boot ran with on 5 October 2026. `fix` is what creates it.
+ */
+export declare function requireIpfsRepository(repository: string, fix: string): void;
+/**
+ * isolateIpfsConfig on a repository, and once per repository (when `rotate`
+ * is given) a fresh identity, so forks copied from one template stop sharing
+ * an IPFS peer id. The template identity is kept in the repository's keystore
+ * as `product-lab-previous-self` (`ipfs key rotate` requires a backup name).
+ * Returns undefined when the repository does not exist.
+ */
+export declare function isolateIpfsRepository(repository: string, options: {
+    expose: boolean;
+    rotate?: (repository: string) => void;
+}): {
+    peerId: string;
+    rotated: boolean;
+} | undefined;
+/** A fresh IPFS identity through kubo's `ipfs key rotate` (the daemon must be stopped). */
+export declare function ipfsIdentityRotation(ipfs: string, commands: SyncCommandRunner): (repository: string) => void;