@parity/product-lab 0.0.1-placeholder → 0.1.0

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

@@ -0,0 +1,154 @@
+import type { Clock, EnvironmentVariables, FileSystem, JsonRpcClient, Logger, OwnedProcesses } from "@parity/product-lab/ports/system";
+import { upgradeRuntime, type RuntimeUpgradeResult, type UpgradableChain } from "./runtime-upgrade.js";
+/** The chains of a relay-backed fork, in the order upgrades apply (the relay first: parachains need its go-ahead). */
+export declare const FORKED_CHAINS: readonly ["relay", "people", "asset-hub", "bulletin"];
+export type ForkedChain = UpgradableChain;
+export declare const chainLabel: (chain: string) => string;
+/** How a person asks a lab start for each update (printed in lines and refusals). */
+export interface ForkUpdateCommands {
+    /** Default `product-lab lab --update-runtime`. */
+    readonly updateRuntime?: string;
+    /** Default `product-lab lab --refresh`. */
+    readonly refresh?: string;
+}
+export declare const updateRuntimeCommand: (commands?: ForkUpdateCommands) => string;
+export declare const refreshCommand: (commands?: ForkUpdateCommands) => string;
+/** A saved JSON object, or undefined when the file does not exist; a damaged or unreadable file is an error, never absence. */
+export declare function readSavedJson<T extends object>(file: string): T | undefined;
+/**
+ * A network file's `rpc` as a WebSocket URL. next-v2 names absolute endpoints; previewnet names paths under its
+ * `bite.source` (`relay/alice` → `wss://previewnet.substrate.dev/relay/alice`), as Engine's bite resolves them.
+ */
+export declare function resolveNetworkRpc(rpc: string, source: string | undefined): string;
+/** The public RPC of every forked chain, from Engine's network file (the same endpoints its bite reads), and whether its fork has a sudo key. */
+export declare function liveEndpoints(engine: {
+    readonly checkout: string;
+}, network: string): Partial<Record<ForkedChain, string>> & {
+    sudo?: boolean;
+};
+export interface ChainRuntime {
+    spec: string;
+    specVersion?: number;
+    codeHash?: string;
+}
+/** What the fork runs (or, before its first boot, the bundle it will start from) and when it was bitten. */
+export interface ForkState {
+    kind: "saved" | "bundle";
+    bittenAt?: string;
+    blocks: Readonly<Record<string, number>>;
+    runtimes: Partial<Record<ForkedChain, ChainRuntime>>;
+}
+/** The runtimes the fork ran when it last started (`runtimes.json`, written after every start and upgrade). */
+export declare const FORK_RUNTIMES_FILE = "runtimes.json";
+/**
+ * The fork's runtimes: the saved session (the parachains: code and spec, checked on every resume), the relay from the
+ * last start's observation (else the bite's spec), and the bite from the network's own snapshot record. Without a
+ * saved network: the Engine bundle a first start forks.
+ */
+export declare function forkState(directory: string, workspace: string, network: string, files: Pick<FileSystem, "exists" | "readJson" | "listDirectory" | "remove" | "rename">): ForkState | undefined;
+/** What one live chain runs now (a `deployed` resolution). */
+export interface LiveRuntime extends ChainRuntime {
+    codeHash: string;
+    specVersion: number;
+    block: {
+        number: number;
+        hash: string;
+    };
+    endpoint: string;
+}
+export interface LiveRead {
+    runtimes: Partial<Record<ForkedChain, LiveRuntime>>;
+    /** Chains that could not be read, with why. */
+    failed: Partial<Record<ForkedChain, string>>;
+    durationMs: number;
+}
+/**
+ * Reads what every live chain runs now, all at once, each within `timeoutMs`; never rejects (an unreachable chain is
+ * listed in `failed`). The composition root's reads the `deployed` version source over the public endpoints.
+ */
+export type LiveRuntimeReader = (endpoints: Partial<Record<ForkedChain, string>>, input: {
+    network: string;
+    clock: Clock;
+    timeoutMs?: number;
+}) => Promise<LiveRead>;
+/** A live chain's runtime code at the block it was resolved at, checked to hash (blake2-256) to its code hash before it returns. */
+export type LiveCodeFetcher = (chain: ForkedChain, live: LiveRuntime) => Promise<Uint8Array>;
+export declare function shortError(error: unknown): string;
+export interface RuntimeChange {
+    chain: ForkedChain;
+    fork: ChainRuntime;
+    live: LiveRuntime;
+    /** Same spec version, other code (a rebuild or a patch without a spec bump). */
+    codeOnly: boolean;
+}
+export interface Freshness {
+    checked: boolean;
+    /** The fork's age from its bite, when known. */
+    ageMs?: number;
+    changes: RuntimeChange[];
+    /** Chains compared and found the same. */
+    same: ForkedChain[];
+    unreachable: Partial<Record<ForkedChain, string>>;
+    /** No fork on this machine yet (nothing was compared). */
+    firstStart?: true;
+    line: string;
+}
+/**
+ * Compare the fork with the live read and say it in one line (a start prints it, the lab window lists it). Pure.
+ * `command` ends a line that names a change (default: the generic update command).
+ */
+export declare function freshness(fork: ForkState | undefined, live: LiveRead | undefined, now: Date, command?: string): Freshness;
+export interface ForkUpgradeTarget {
+    directory: string;
+    sessionFile: string;
+    /** The running network's session (updated in place after an upgrade). */
+    session: {
+        chains: Record<string, {
+            ws: string;
+            codeHash: string;
+            runtime: {
+                specName: string;
+                specVersion: number;
+                transactionVersion: number;
+            };
+        }>;
+    };
+    /** Loopback WebSocket of the relay's first validator. */
+    relayWs: string;
+    registry: OwnedProcesses;
+}
+export interface UpgradeDeps {
+    engine: {
+        readonly checkout: string;
+        readonly workspace: string;
+        readonly extraPath: readonly string[];
+    };
+    network: string;
+    rpc: JsonRpcClient;
+    files: FileSystem;
+    environment: EnvironmentVariables;
+    logger: Pick<Logger, "info" | "warn">;
+    clock: Clock;
+    signal?: AbortSignal;
+    /** Fetches and checks each live runtime's code (the composition root's downloads it from the live chain's endpoint). */
+    fetchCode: LiveCodeFetcher;
+    upgrade?: typeof upgradeRuntime;
+    /** Finalized blocks to wait after an upgrade before clients connect (polkadot-api's post-upgrade window); default 16. */
+    settleBlocks?: number;
+    /** Skip the chains' version checks (a deliberate downgrade). */
+    withoutChecks?: boolean;
+    /** The fork has a sudo key (Engine's network file); false refuses: the upgrade path needs one. */
+    sudo?: boolean;
+    commands?: ForkUpdateCommands;
+}
+export type UpgradedRuntime = Extract<RuntimeUpgradeResult, {
+    outcome: "upgraded";
+}>;
+/**
+ * Apply every changed live runtime to the running fork, one chain at a time (the relay first), through the chain's own
+ * upgrade path. Each is checked on the chain afterwards and recorded; the first failure stops and throws, saying
+ * whether the fork changed. Returns what was upgraded.
+ */
+export declare function updateForkRuntimes(target: ForkUpgradeTarget, fresh: Freshness, deps: UpgradeDeps): Promise<UpgradedRuntime[]>;
+/** Record what the fork runs after a start (the relay is not in the session): the next freshness line compares code, not only specs. */
+export declare function recordForkRuntimes(target: Pick<ForkUpgradeTarget, "directory" | "session" | "relayWs">, rpc: JsonRpcClient, at: Date): Promise<void>;

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

@@ -0,0 +1,238 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { currentBundle } from "./published-bundle.js";
+import { observeRuntime, recordRuntimeUpgrade, upgradeRuntime, UPGRADABLE_CHAINS } from "./runtime-upgrade.js";
+export const FORKED_CHAINS = UPGRADABLE_CHAINS;
+const LABELS = { relay: "relay", people: "People", "asset-hub": "Asset Hub", bulletin: "Bulletin" };
+export const chainLabel = (chain) => LABELS[chain] ?? chain;
+export const updateRuntimeCommand = (commands) => commands?.updateRuntime ?? "product-lab lab --update-runtime";
+export const refreshCommand = (commands) => commands?.refresh ?? "product-lab lab --refresh";
+export function readSavedJson(file) {
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new Error(`Cannot read ${file} (${error instanceof Error ? error.message : String(error)}). Nothing was changed. Fix: check its permissions, or restore it.`, { cause: error });
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${file} is damaged (${error instanceof Error ? error.message : String(error)}). Nothing was changed. Fix: repair or restore it.`, { cause: error });
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${file} is damaged (expected a JSON object). Nothing was changed. Fix: repair or restore it.`);
+    return value;
+}
+export function resolveNetworkRpc(rpc, source) {
+    const absolute = /^(wss?|https?):\/\//.test(rpc) ? rpc : source ? `${source.replace(/\/+$/, "")}/${rpc.replace(/^\/+/, "")}` : undefined;
+    if (!absolute)
+        throw new Error(`Engine's network file names the relative endpoint "${rpc}" but no bite.source to resolve it against`);
+    return absolute.replace(/^http(s?):\/\//, "ws$1://");
+}
+export function liveEndpoints(engine, network) {
+    const spec = JSON.parse(readFileSync(join(engine.checkout, "networks", `${network}.json`), "utf8"));
+    const source = spec.bite?.source;
+    const endpoints = {};
+    if (spec.relay?.rpc)
+        endpoints.relay = resolveNetworkRpc(spec.relay.rpc, source);
+    for (const chain of spec.parachains ?? [])
+        if (chain.key && chain.rpc && FORKED_CHAINS.includes(chain.key))
+            endpoints[chain.key] = resolveNetworkRpc(chain.rpc, source);
+    if (spec.sudo !== undefined)
+        endpoints.sudo = spec.sudo;
+    return endpoints;
+}
+export const FORK_RUNTIMES_FILE = "runtimes.json";
+const specOf = (value) => {
+    const version = Number(value.split(" ").at(-1));
+    return Number.isInteger(version) ? version : undefined;
+};
+export function forkState(directory, workspace, network, files) {
+    const plan = readSavedJson(join(directory, "network.json"));
+    if (!plan?.session?.chains) {
+        const bundle = currentBundle(files, workspace, network);
+        if (!bundle)
+            return undefined;
+        return { kind: "bundle", bittenAt: bundle.bittenAt, blocks: bundle.blocks, runtimes: runtimesOf(bundle) };
+    }
+    const snapshot = readSavedJson(join(directory, "network", "fork-snapshot.json"));
+    const recorded = readSavedJson(join(directory, FORK_RUNTIMES_FILE));
+    const runtimes = { ...(snapshot ? runtimesOf(snapshot) : {}), ...(recorded?.chains ?? {}) };
+    for (const [chain, observed] of Object.entries(plan.session.chains)) {
+        if (!FORKED_CHAINS.includes(chain) || !observed.runtime?.specName)
+            continue;
+        runtimes[chain] = { spec: `${observed.runtime.specName} ${observed.runtime.specVersion}`, specVersion: observed.runtime.specVersion, ...(observed.codeHash ? { codeHash: observed.codeHash } : {}) };
+    }
+    return { kind: "saved", ...(snapshot?.bittenAt ? { bittenAt: snapshot.bittenAt } : {}), blocks: snapshot?.blocks ?? {}, runtimes };
+}
+function runtimesOf(snapshot) {
+    const runtimes = {};
+    for (const [chain, spec] of Object.entries(snapshot.runtimes ?? {}))
+        if (FORKED_CHAINS.includes(chain))
+            runtimes[chain] = { spec, ...(specOf(spec) !== undefined ? { specVersion: specOf(spec) } : {}) };
+    return runtimes;
+}
+export function shortError(error) {
+    const message = error instanceof Error ? (error.cause instanceof Error ? error.cause.message : error.message) : String(error);
+    return message.length > 120 ? `${message.slice(0, 117)}...` : message;
+}
+const ago = (ms) => {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${minutes} min`;
+    const hours = Math.round(ms / 3_600_000);
+    if (hours < 48)
+        return `${hours} h`;
+    return `${Math.round(ms / 86_400_000)} days`;
+};
+const short = (hash) => `${hash.slice(0, 10)}…`;
+const specVersionOf = (runtime) => runtime.specVersion ?? specOf(runtime.spec);
+export function freshness(fork, live, now, command = updateRuntimeCommand()) {
+    const ageMs = fork?.bittenAt ? now.getTime() - Date.parse(fork.bittenAt) : undefined;
+    const people = fork?.blocks.people;
+    const behind = people !== undefined && live?.runtimes.people ? live.runtimes.people.block.number - people : undefined;
+    const subject = fork?.kind === "bundle" ? "Fork state to boot" : "Fork";
+    const age = ageMs !== undefined
+        ? `${subject}: ${ago(ageMs)} old (bitten ${fork.bittenAt.slice(0, 16).replace("T", " ")} UTC${people !== undefined ? `, People #${people}${behind !== undefined ? `, ${behind} blocks behind live` : ""}` : ""})`
+        : `${subject}: age unknown (no bite recorded)`;
+    if (!fork)
+        return { checked: false, firstStart: true, changes: [], same: [], unreachable: {}, line: "First start: no fork on this machine yet, so there is nothing to compare with the live runtimes" };
+    if (!live || !Object.keys(live.runtimes).length) {
+        const why = live ? Object.values(live.failed)[0] : undefined;
+        return { checked: false, ...(ageMs !== undefined ? { ageMs } : {}), changes: [], same: [], unreachable: live?.failed ?? {}, line: `${age} · could not check the live runtimes${why ? ` (${why})` : ""}; starting it as it is` };
+    }
+    const changes = [];
+    const same = [];
+    for (const chain of FORKED_CHAINS) {
+        const current = live.runtimes[chain];
+        const forked = fork.runtimes[chain];
+        if (!current || !forked)
+            continue;
+        const specSame = forked.spec === current.spec;
+        const codeSame = forked.codeHash ? forked.codeHash.toLowerCase() === current.codeHash : specSame;
+        if (specSame && codeSame)
+            same.push(chain);
+        else
+            changes.push({ chain, fork: forked, live: current, codeOnly: specSame });
+    }
+    const unreachable = Object.keys(live.failed).length ? ` · could not check ${Object.keys(live.failed).map(chainLabel).join(", ")}` : "";
+    if (!changes.length)
+        return { checked: true, ...(ageMs !== undefined ? { ageMs } : {}), changes, same, unreachable: live.failed, line: `${age} · runtimes match live (${same.map(chainLabel).join(", ")})${unreachable}` };
+    const described = changes.map((change) => change.codeOnly
+        ? `${chainLabel(change.chain)} runtime code changed live (same spec ${specVersionOf(change.live)}, code ${short(change.fork.codeHash ?? "?")} → ${short(change.live.codeHash)})`
+        : `${chainLabel(change.chain)} runtime changed live (${specVersionOf(change.fork) ?? change.fork.spec} → ${change.live.specVersion})`);
+    return { checked: true, ...(ageMs !== undefined ? { ageMs } : {}), changes, same, unreachable: live.failed, line: `${age} · ${described.join("; ")}: ${command}${unreachable}` };
+}
+export async function updateForkRuntimes(target, fresh, deps) {
+    const log = deps.logger;
+    if (!fresh.checked)
+        throw new Error(`--update-runtime needs the live network, and it could not be read (${Object.values(fresh.unreachable)[0] ?? "no answer"}). Nothing was changed. Fix: connect to the internet and run it again, or start without --update-runtime.`);
+    if (!fresh.changes.length) {
+        log.info(`--update-runtime: every forked chain already runs the live runtime (${fresh.same.map(chainLabel).join(", ")}); nothing to upgrade.`);
+        return [];
+    }
+    if (deps.sudo === false)
+        throw new Error(`--update-runtime cannot upgrade this fork in place: Engine's ${deps.network} network has no sudo key on its fork, and the chains' upgrade path needs one. Fix: ${refreshCommand(deps.commands)} (a new fork from the newest published state).`);
+    const directory = join(target.directory, "runtime-upgrades");
+    deps.files.makeDirectory(directory);
+    const upgraded = [];
+    for (const change of fresh.changes) {
+        const label = chainLabel(change.chain);
+        const ws = change.chain === "relay" ? target.relayWs : target.session.chains[change.chain]?.ws;
+        if (!ws)
+            throw new Error(`--update-runtime: the fork's session has no ${label} endpoint; nothing was changed for it.`);
+        log.info(`Updating ${label} in place: ${change.fork.spec} → ${change.live.spec} (live code ${short(change.live.codeHash)} at #${change.live.block.number}). A parachain waits for the relay's go-ahead: several minutes.`);
+        const code = await deps.fetchCode(change.chain, change.live);
+        const started = deps.clock.now();
+        const result = await (deps.upgrade ?? upgradeRuntime)({
+            engine: deps.engine,
+            network: deps.network,
+            chain: change.chain,
+            ws,
+            code,
+            codeHash: change.live.codeHash,
+            specVersion: change.live.specVersion,
+            ...(deps.withoutChecks ? { withoutChecks: true } : {}),
+            registry: target.registry,
+            rpc: deps.rpc,
+            environment: deps.environment,
+            files: deps.files,
+            directory,
+            ...(deps.signal ? { signal: deps.signal } : {}),
+        });
+        if (result.outcome === "already-running") {
+            log.info(`${label} already runs the live code ${short(change.live.codeHash)}; nothing submitted.`);
+            continue;
+        }
+        if (result.outcome === "failed") {
+            const state = result.unchanged
+                ? `The fork is unchanged: ${label} still runs ${result.before.specName} ${result.before.specVersion} (code ${short(result.before.codeHash)}).`
+                : result.after
+                    ? `${label} now runs ${result.after.specName} ${result.after.specVersion} (code ${short(result.after.codeHash)}), which is neither its old nor the live code: inspect it before using this fork.`
+                    : `${label} could not be read afterwards: inspect the fork before using it.`;
+            throw new Error(`${label} upgrade failed: ${result.reason}. ${state}${result.log ? ` Engine's output: ${result.log}` : ""}${upgraded.length ? ` Upgraded before it: ${upgraded.map((entry) => chainLabel(entry.chain)).join(", ")} (recorded).` : ""}`);
+        }
+        const session = recordRuntimeUpgrade(deps.files, {
+            directory: target.directory,
+            sessionFile: target.sessionFile,
+            chain: change.chain,
+            before: result.before,
+            after: result.after,
+            source: `${change.live.endpoint} #${change.live.block.number} ${change.live.block.hash}`,
+            at: deps.clock.date(),
+        });
+        if (session && change.chain !== "relay")
+            target.session.chains[change.chain] = session.chains[change.chain];
+        upgraded.push(result);
+        log.info(`${label} upgraded in place in ${Math.round((deps.clock.now() - started) / 1000)} s: ${result.before.specName} ${result.before.specVersion} → ${result.after.specName} ${result.after.specVersion}, code ${short(result.after.codeHash)} = live, ` +
+            (result.migrated
+                ? `migrations ran (System.LastRuntimeUpgrade ${result.before.lastUpgrade?.specVersion ?? "unset"} → ${result.after.lastUpgrade.specVersion})`
+                : `System.LastRuntimeUpgrade ${result.before.lastUpgrade?.specVersion ?? "unset"} → ${result.after.lastUpgrade?.specVersion ?? "unset"}`) +
+            `, finalized #${result.after.block.number}.`);
+        if (!result.migrated)
+            log.warn(result.before.lastUpgrade?.specVersion === result.after.specVersion
+                ? `${label}: the chain had already recorded ${result.after.specVersion} as its last upgrade (it was downgraded from it), so the executive did not run the new runtime's migrations.`
+                : `${label}: the executive did not record the new runtime's upgrade (LastRuntimeUpgrade); its migrations did not run.`);
+    }
+    await settle(target, upgraded, deps);
+    return upgraded;
+}
+async function settle(target, upgraded, deps) {
+    const blocks = deps.settleBlocks ?? 16;
+    if (blocks <= 0)
+        return;
+    for (const result of upgraded) {
+        const ws = result.chain === "relay" ? target.relayWs : target.session.chains[result.chain].ws;
+        const until = result.after.block.number + blocks;
+        for (;;) {
+            deps.signal?.throwIfAborted();
+            const now = await observeRuntime(deps.rpc, ws);
+            if (now.block.number >= until)
+                break;
+            await delay(3000);
+        }
+    }
+    if (upgraded.length)
+        deps.logger.info(`Upgraded chains finalized ${blocks} blocks past their new runtime; starting identities.`);
+}
+export async function recordForkRuntimes(target, rpc, at) {
+    const chains = {};
+    try {
+        const relay = await observeRuntime(rpc, target.relayWs);
+        chains.relay = { spec: `${relay.specName} ${relay.specVersion}`, specVersion: relay.specVersion, codeHash: relay.codeHash };
+    }
+    catch {
+    }
+    for (const [chain, observed] of Object.entries(target.session.chains))
+        if (FORKED_CHAINS.includes(chain))
+            chains[chain] = { spec: `${observed.runtime.specName} ${observed.runtime.specVersion}`, specVersion: observed.runtime.specVersion, codeHash: observed.codeHash };
+    writeFileSync(join(target.directory, FORK_RUNTIMES_FILE), JSON.stringify({ observedAt: at.toISOString(), chains }, null, 2) + "\n", { mode: 0o600 });
+}

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

@@ -0,0 +1,19 @@
+export { AUTHORITY_DISCOVERY_CACHE, isolatePersistedNetwork, nodeKeyTool, type NodeKeys, type PersistedIsolation, } from "./persisted-isolation.js";
+export { COLLATOR_WRAPPER, chainSpecFiles, forkIsolationSchema, isolateNodeArgs, TXPOOL_LOG_LEVELS, nodeLogTargets, withNodeLogTargets, BULLETIN_AUTHORING, withBulletinAuthoring, type BulletinAuthoring, type TxpoolLog, renameBootNodes, zombieNodes, type ForkIsolation, type ZombieNode, } from "./node-isolation.js";
+export { NODE_WRAPPER_DIRECTORY, assignForkTomlPorts, collatorWrapperScript, isolateForkToml, moveForkTomlPorts, nodeWrapperScript, planForkTomlPorts, writeIsolatedForkToml, type ForkTomlIsolation, type RelaySidePorts, } from "./fork-toml.js";
+export { IPFS_IDENTITY_MARKER, LOOPBACK_ONLY_ADDRESS_FILTERS, ipfsIdentityRotation, isolateIpfsConfig, isolateIpfsRepository, requireIpfsRepository } from "./ipfs-isolation.js";
+/**
+ * What zombienet actually ran (zombie.json), for evidence and for refusing a
+ * half-isolated start: `--no-mdns` on every node, and on a collator's relay
+ * side either in its arguments (resumed) or through the product-lab launcher
+ * (bootstrap).
+ */
+export declare function inspectIsolation(directory: string, options?: {
+    expose?: boolean;
+    wrappers?: string;
+}): {
+    isolated: boolean;
+    problems: string[];
+};
+/** What in a node's arguments listens beyond loopback: external flags, wildcard listen addresses, a bare `--port`. */
+export declare function nonLoopbackListeners(args: readonly string[]): string[];

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

@@ -0,0 +1,44 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { COLLATOR_WRAPPER, EXTERNAL_FLAGS, zombieNodes } from "./node-isolation.js";
+export { AUTHORITY_DISCOVERY_CACHE, isolatePersistedNetwork, nodeKeyTool, } from "./persisted-isolation.js";
+export { COLLATOR_WRAPPER, chainSpecFiles, forkIsolationSchema, isolateNodeArgs, TXPOOL_LOG_LEVELS, nodeLogTargets, withNodeLogTargets, BULLETIN_AUTHORING, withBulletinAuthoring, renameBootNodes, zombieNodes, } from "./node-isolation.js";
+export { NODE_WRAPPER_DIRECTORY, assignForkTomlPorts, collatorWrapperScript, isolateForkToml, moveForkTomlPorts, nodeWrapperScript, planForkTomlPorts, writeIsolatedForkToml, } from "./fork-toml.js";
+export { IPFS_IDENTITY_MARKER, LOOPBACK_ONLY_ADDRESS_FILTERS, ipfsIdentityRotation, isolateIpfsConfig, isolateIpfsRepository, requireIpfsRepository } from "./ipfs-isolation.js";
+export function inspectIsolation(directory, options = {}) {
+    const problems = [];
+    for (const node of zombieNodes(directory)) {
+        const split = node.inner.args.indexOf("--");
+        const own = split === -1 ? node.inner.args : node.inner.args.slice(0, split);
+        if (!own.includes("--no-mdns"))
+            problems.push(`${node.name}: no --no-mdns`);
+        if (split !== -1 &&
+            !node.inner.args.slice(split + 1).includes("--no-mdns") &&
+            !node.inner.program.endsWith(`/${COLLATOR_WRAPPER}`))
+            problems.push(`${node.name}: relay side without --no-mdns`);
+        if (options.expose === false) {
+            const open = nonLoopbackListeners(node.inner.args);
+            const wrapped = !!options.wrappers && node.inner.program.startsWith(`${options.wrappers}/`);
+            if (open.length && !wrapped)
+                problems.push(`${node.name}: listens beyond loopback (${open.join(", ")})`);
+        }
+    }
+    return { isolated: problems.length === 0, problems };
+}
+export function nonLoopbackListeners(args) {
+    const open = [];
+    const sides = args.indexOf("--") === -1 ? [args] : [args.slice(0, args.indexOf("--")), args.slice(args.indexOf("--") + 1)];
+    for (const side of sides) {
+        const listens = side.some((arg) => arg === "--listen-addr" || arg.startsWith("--listen-addr="));
+        side.forEach((arg, index) => {
+            if (EXTERNAL_FLAGS.has(arg))
+                open.push(arg);
+            const address = arg === "--listen-addr" ? side[index + 1] : arg.startsWith("--listen-addr=") ? arg.slice("--listen-addr=".length) : undefined;
+            if (address !== undefined && !/^\/ip4\/127\.\d+\.\d+\.\d+\/|^\/ip6\/::1\//.test(address))
+                open.push(address);
+            if (!listens && arg === "--port")
+                open.push(`--port ${side[index + 1]} (every interface)`);
+        });
+    }
+    return open;
+}

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

@@ -0,0 +1,75 @@
+import type { ForkSnapshot } from "@parity/product-lab/domain/versions";
+import type { EnvironmentVariables, FileSystem, Logger, OwnedProcesses } from "@parity/product-lab/ports/system";
+import { type ForkUpdateCommands } from "./fork-freshness.js";
+import { type PublishedBundle } from "./published-bundle.js";
+/**
+ * How long the check for a newer published state may take: it streams the bundle until its manifest (the 27
+ * September bundle: 8.8 MB read, 67 s at the 180 KB/s one machine had then). It runs in the background.
+ */
+export declare const PUBLISHED_CHECK_MS = 300000;
+/** What a lab start tells about the published state (the CLI line and the lab window's notice). */
+export declare function newerStateNotice(snapshot: Pick<ForkSnapshot, "bittenAt">, ready: boolean, commands?: ForkUpdateCommands): string;
+type PreparedEngineDirectories = {
+    readonly checkout: string;
+    readonly workspace: string;
+    readonly extraPath: readonly string[];
+};
+export interface PrefetchDeps {
+    engine: PreparedEngineDirectories;
+    network: string;
+    registry: OwnedProcesses;
+    environment: EnvironmentVariables;
+    files: FileSystem;
+    logger: Pick<Logger, "info" | "warn">;
+    fetch?: typeof fetch;
+    /** Called with each notice to show in the lab window (replacing the previous one). */
+    notice: (text: string | undefined) => void;
+    /** True once the lab is stopping: a download stopped by it is not a failure. */
+    stopping: () => boolean;
+    commands?: ForkUpdateCommands;
+}
+/**
+ * While the lab runs: if Engine publishes a state newer than the fork's bite, make it ready for a refresh (already
+ * staged or installed: say so; otherwise download it in the background). Never throws; returns when it has decided (the
+ * download itself continues).
+ */
+export declare function prefetchNewerState(forkBite: Pick<ForkSnapshot, "bittenAt"> | undefined, deps: PrefetchDeps): Promise<PublishedBundle | undefined>;
+/** A refresh in progress: the old fork set aside and the newer bundle installed, until the new fork is up. */
+export interface RefreshHandle {
+    /** The state the new fork boots from. */
+    bundle: Pick<ForkSnapshot, "bittenAt" | "blocks">;
+    /** Where the old fork waits until `commit` deletes it. */
+    setAside?: string;
+    /** The new fork is up: delete the old one and the replaced bundle. */
+    commit(): void;
+    /** The new fork failed: put the old fork and the old bundle back. */
+    rollback(): void;
+}
+/** A record a lab keeps beside its fork and carries into the new one (for example its port block). */
+export interface RefreshCarry<T> {
+    /** Read before anything changes; a damaged record throws (nothing is changed), absence is undefined. */
+    read(directory: string): T | undefined;
+    /** Write it into the new fork's (empty) directory. */
+    write(directory: string, record: T, refreshedFrom: string | undefined): void;
+}
+export interface RefreshDeps<T = unknown> {
+    engine: PreparedEngineDirectories;
+    network: string;
+    environment: EnvironmentVariables;
+    files: FileSystem;
+    logger: Pick<Logger, "info" | "warn">;
+    /** Opens a process registry (the old fork's own, for its survivors and the download). */
+    processes: {
+        open(directory: string): OwnedProcesses;
+    };
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    carry?: RefreshCarry<T>;
+}
+/**
+ * `--refresh`: set the saved fork aside and install the newest published state as the bundle a first start boots,
+ * downloading it now unless a background download staged it. Returns undefined, changing nothing, when the fork already
+ * runs the newest published state.
+ */
+export declare function prepareRefresh<T>(directory: string, deps: RefreshDeps<T>): Promise<RefreshHandle | undefined>;
+export {};