@parity/product-lab 0.0.1-placeholder → 0.1.1

package/adapters/environment/engine/src/errors.d.ts

@@ -0,0 +1,140 @@
+export interface ReadinessOptions {
+    /** How long a chain that must finalize may stand without finalizing a block (each finalized block restarts it). */
+    timeoutMs?: number;
+    pollMs?: number;
+    /**
+     * The chains that must show their finalized head advancing (the lab's required chains, `EnvironmentStartContext
+     * .requiredChains`); every other chain needs only to answer: its genesis, finalized head and runtime are read once.
+     * Absent: every chain. Names that are not Engine chains are ignored.
+     */
+    finality?: readonly string[];
+    /**
+     * Backlog 141: the best head each chain stood at when this start first read it, by endpoint, kept across the start's
+     * checks. Given, a chain that must finalize is ready only once its finalized head passes that head: it builds blocks
+     * again, not only finalizes the ones it had (a fork's parachains pause while the validators prepare their PVFs, which
+     * every node start does again). Absent: ready once its finalized head advances.
+     */
+    firstBest?: Map<string, string>;
+}
+/** An error's message, with its cause's when the message alone says nothing (fetch's "fetch failed"). */
+export declare function errorMessage(error: unknown): string;
+/** The first system error code (`ECONNREFUSED`, `ECONNRESET`, …) on `error` or its causes: fetch's TypeError("fetch failed") carries the socket's in `cause`. */
+export declare function systemErrorCode(error: unknown): string | undefined;
+/** An HTTP endpoint (the Engine dashboard, the identity backend) that did not answer: refused, reset or timed out. */
+export declare class EndpointUnansweredError extends Error {
+    readonly url: string;
+    /** The cause's system error code, when it has one (`ECONNREFUSED` for a port nothing listens on). */
+    readonly systemCode: string | undefined;
+    constructor(url: string, cause: unknown);
+}
+/** Whether `error` is a request under `base` (the dashboard's URL) that the port refused: nothing listens there. */
+export declare function refusedUnder(error: unknown, base: string | undefined): boolean;
+/** A port the network needs is taken; the lab never stops a process by port. */
+export declare class PortOccupiedError extends Error {
+    readonly port: number;
+    /** What the network would run there (a process id or an Engine port name), when known. */
+    readonly owner?: string | undefined;
+    constructor(port: number, 
+    /** What the network would run there (a process id or an Engine port name), when known. */
+    owner?: string | undefined);
+}
+/** One piece of a persisted network that is not on disk. */
+export interface MissingPersistedData {
+    /** The network process it belongs to (`Collator-1502`, `postgres`, `ipfs`). */
+    readonly process: string;
+    readonly data: "chain database" | "identity database" | "IPFS repository";
+    /** Where it was looked for. */
+    readonly path: string | undefined;
+    /** The sentence the refusal prints. */
+    readonly text: string;
+}
+/** A persisted network whose saved data is incomplete: resuming it would not resume its history. */
+export declare class IncompleteNetworkError extends Error {
+    readonly directory: string;
+    readonly missing: readonly MissingPersistedData[];
+    constructor(directory: string, missing: readonly MissingPersistedData[]);
+}
+/** One path of a saved network's Engine tooling that is not on this machine, and the process that needs it. */
+export interface MissingToolingPath {
+    readonly process: string;
+    readonly path: string;
+}
+/**
+ * A saved network whose Engine tooling is gone: its plan runs binaries and scripts from the tooling it was created with,
+ * and that tooling's cache was deleted or moved, or another cache is configured. Nothing was started.
+ */
+export declare class MissingEngineToolingError extends Error {
+    readonly directory: string;
+    readonly missing: readonly MissingToolingPath[];
+    /** The Engine checkout the saved plan runs from. */
+    readonly savedCheckout?: string | undefined;
+    /** The Engine checkout this lab uses now, when it is another one. */
+    readonly currentCheckout?: string | undefined;
+    constructor(directory: string, missing: readonly MissingToolingPath[], 
+    /** The Engine checkout the saved plan runs from. */
+    savedCheckout?: string | undefined, 
+    /** The Engine checkout this lab uses now, when it is another one. */
+    currentCheckout?: string | undefined);
+}
+/** A chain answered, but its finalized head did not advance within the check's time. */
+export declare class FinalityNotAdvancingError extends Error {
+    readonly ws: string;
+    /** The finalized block number it stood at. */
+    readonly from: string;
+    constructor(ws: string, 
+    /** The finalized block number it stood at. */
+    from: string);
+}
+/** One readiness check's failures, by chain: what `attachEngine` throws when any chain is not ready. */
+export declare class ChainsNotReadyError extends Error {
+    readonly failures: readonly {
+        readonly chain: string;
+        readonly error: unknown;
+    }[];
+    constructor(failures: readonly {
+        readonly chain: string;
+        readonly error: unknown;
+    }[]);
+    /** The finalized number each chain stood at, when every failure is a finalized head that did not advance. */
+    standing(): Readonly<Record<string, string>> | undefined;
+}
+/** Why one start of a saved network was called stalled, and where its logs were kept. */
+export interface FinalityStall {
+    /** The start within this `start()`: 1 is the first, 2 the first restart. */
+    readonly attempt: number;
+    readonly at: string;
+    /** From the attempt's first process start to the verdict. */
+    readonly afterMs: number;
+    /**
+     * `lost-approvals`: the validators' logs show approval checks lost at the restart; `standing`: no finalized head
+     * advanced; `pinned`: the relay finalizes, but stays at approval-distribution's threshold behind its best head after a
+     * session change (backlog 239, approval-pin.ts).
+     */
+    readonly kind: "lost-approvals" | "standing" | "pinned";
+    readonly reason: string;
+    /** The directory holding what every process logged during the attempt, and `stall.json`. */
+    readonly evidence: string;
+}
+/** A saved network whose finality did not advance in any of its starts (the first and every restart). */
+export declare class FinalityStalledError extends Error {
+    readonly directory: string;
+    /** Every stalled start, in order; the last is the one that ended the recovery. */
+    readonly stalls: readonly FinalityStall[];
+    constructor(directory: string, 
+    /** Every stalled start, in order; the last is the one that ended the recovery. */
+    stalls: readonly FinalityStall[]);
+    /** How many times the network was started. */
+    get attempts(): number;
+}
+/**
+ * A saved network whose relay finality stayed pinned at the approval threshold after a session change, also after the one
+ * restart that clears it (backlog 239, approval-pin.ts): no further restart, the start fails.
+ */
+export declare class FinalityPinnedError extends Error {
+    readonly directory: string;
+    /** Every start's verdict: the pin that was restarted, then the one that ended the start. */
+    readonly stalls: readonly FinalityStall[];
+    constructor(directory: string, 
+    /** Every start's verdict: the pin that was restarted, then the one that ended the start. */
+    stalls: readonly FinalityStall[]);
+}

package/adapters/environment/engine/src/errors.js

@@ -0,0 +1,131 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function errorMessage(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause instanceof Error ? error.cause.message : undefined;
+    return cause && !error.message.includes(cause) ? `${error.message} (${cause})` : error.message;
+}
+export function systemErrorCode(error) {
+    let current = error;
+    for (let depth = 0; current && typeof current === "object" && depth < 5; depth++) {
+        const code = current.code;
+        if (typeof code === "string")
+            return code;
+        current = current.cause;
+    }
+    return undefined;
+}
+export class EndpointUnansweredError extends Error {
+    url;
+    systemCode;
+    constructor(url, cause) {
+        super(`${url} did not answer: ${errorMessage(cause)}`, { cause });
+        this.url = url;
+        this.name = "EndpointUnansweredError";
+        this.systemCode = systemErrorCode(cause);
+    }
+}
+export function refusedUnder(error, base) {
+    return !!base && error instanceof EndpointUnansweredError && error.url.startsWith(`${base}/`) && error.systemCode === "ECONNREFUSED";
+}
+export class PortOccupiedError extends Error {
+    port;
+    owner;
+    constructor(port, 
+    owner) {
+        super(`Port ${port} is occupied${owner ? ` (${owner})` : ""}. Stop its known owner; the lab will not kill by port.`);
+        this.port = port;
+        this.owner = owner;
+        this.name = "PortOccupiedError";
+    }
+}
+export class IncompleteNetworkError extends Error {
+    directory;
+    missing;
+    constructor(directory, missing) {
+        super(`Persisted network ${directory} is incomplete: ${missing.map((item) => item.text).join("; ")}. Refusing to start it: a node without its database would not resume this network's history. Restore the missing data, or reset the workspace to create a new network.`);
+        this.directory = directory;
+        this.missing = missing;
+        this.name = "IncompleteNetworkError";
+    }
+}
+export class MissingEngineToolingError extends Error {
+    directory;
+    missing;
+    savedCheckout;
+    currentCheckout;
+    constructor(directory, missing, 
+    savedCheckout, 
+    currentCheckout) {
+        const shown = missing.slice(0, 3).map((item) => `${item.path} (${item.process})`).join(", ");
+        const more = missing.length > 3 ? ` and ${missing.length - 3} more` : "";
+        const why = currentCheckout
+            ? `This lab now uses the Engine checkout ${currentCheckout}: PRODUCT_LAB_CACHE_DIR names another cache than the one the network was created with, or that cache was moved.`
+            : `The cache that held ${savedCheckout ?? "it"} was deleted or moved, or PRODUCT_LAB_CACHE_DIR names another cache.`;
+        super(`Saved network ${directory} cannot start: the Engine tooling it was created with is not on this machine (missing: ${shown}${more}). ${why} Nothing was started. Make that tooling available again (set PRODUCT_LAB_CACHE_DIR to the cache that holds it), or make a new saved network (\`product-lab dev --refresh\`, or a reset), which discards the identities created on this one.`);
+        this.directory = directory;
+        this.missing = missing;
+        this.savedCheckout = savedCheckout;
+        this.currentCheckout = currentCheckout;
+        this.name = "MissingEngineToolingError";
+    }
+}
+export class FinalityNotAdvancingError extends Error {
+    ws;
+    from;
+    constructor(ws, 
+    from) {
+        super(`Finality did not advance from ${from} at ${ws}`);
+        this.ws = ws;
+        this.from = from;
+        this.name = "FinalityNotAdvancingError";
+    }
+}
+export class ChainsNotReadyError extends Error {
+    failures;
+    constructor(failures) {
+        super(failures.map((failure) => `${failure.chain}: ${failure.error instanceof Error ? failure.error.message : String(failure.error)}`).join("\n"));
+        this.failures = failures;
+        this.name = "ChainsNotReadyError";
+    }
+    standing() {
+        const entries = [];
+        for (const failure of this.failures) {
+            if (!(failure.error instanceof FinalityNotAdvancingError))
+                return undefined;
+            entries.push([failure.chain, failure.error.from]);
+        }
+        return Object.fromEntries(entries);
+    }
+}
+export class FinalityStalledError extends Error {
+    directory;
+    stalls;
+    constructor(directory, 
+    stalls) {
+        const last = stalls.at(-1);
+        const starts = stalls.length;
+        super(`The saved network ${directory} did not finalize in ${starts} start${starts === 1 ? "" : "s"} (${starts - 1} restart${starts === 2 ? "" : "s"} after a stall): ${last?.reason ?? "finality did not advance"}. ` +
+            `Its processes were stopped and its data kept. What every process logged in each stalled start: ${stalls.map((stall) => stall.evidence).join(", ")}`);
+        this.directory = directory;
+        this.stalls = stalls;
+        this.name = "FinalityStalledError";
+    }
+    get attempts() {
+        return this.stalls.length;
+    }
+}
+export class FinalityPinnedError extends Error {
+    directory;
+    stalls;
+    constructor(directory, 
+    stalls) {
+        const last = stalls.at(-1);
+        super(`The saved network ${directory} did not become ready: ${last?.reason ?? "finality pinned at the approval threshold after a session change"}. ` +
+            `Its processes were stopped and its data kept. What every process logged in each start: ${stalls.map((stall) => stall.evidence).join(", ")}`);
+        this.directory = directory;
+        this.stalls = stalls;
+        this.name = "FinalityPinnedError";
+    }
+}

package/adapters/environment/engine/src/evidence/engine-logs.d.ts

@@ -0,0 +1,4 @@
+/** Preserve process diagnostics before deleting a disposable Zombienet directory.
+ * Only regular process logs are copied, never chain databases, keys or symlinks.
+ */
+export declare function preserveEngineLogs(directory: string, reports: string): void;

package/adapters/environment/engine/src/evidence/engine-logs.js

@@ -0,0 +1,20 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { copyFileSync, mkdirSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
+export function preserveEngineLogs(directory, reports) {
+    const destination = join(reports, "engine-logs", basename(directory));
+    const copyLogs = (source, target) => {
+        for (const entry of readdirSync(source, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith(".log"))
+                continue;
+            mkdirSync(target, { recursive: true });
+            copyFileSync(join(source, entry.name), join(target, entry.name));
+        }
+    };
+    copyLogs(directory, destination);
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        if (entry.isDirectory())
+            copyLogs(join(directory, entry.name), join(destination, entry.name));
+    }
+}

package/adapters/environment/engine/src/evidence/engine-progress.d.ts

@@ -0,0 +1,18 @@
+import type { JsonRpcClient } from "@parity/product-lab/ports/system";
+/** Select only names/endpoints: zombie.json also contains keys and launch args. */
+export declare function progressEndpoints(raw: unknown): {
+    name: string;
+    relay: boolean;
+    url: string;
+}[];
+export declare function readNodeProgress(client: JsonRpcClient, endpoint: ReturnType<typeof progressEndpoints>[number], signal: AbortSignal): Promise<{
+    name: string;
+    best: {};
+    finalized: {};
+    finalizedHeader: {};
+    grandpa: {} | undefined;
+}>;
+/** Best-effort evidence, independent of readiness and health gates. No chain writes.
+ * Starts before provisioning completes; stopping aborts every pending request.
+ */
+export declare function recordEngineProgress(client: JsonRpcClient, spawnFile: string, output: string, signal: AbortSignal): Promise<void>;

package/adapters/environment/engine/src/evidence/engine-progress.js

@@ -0,0 +1,102 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { appendFileSync, readFileSync } from "node:fs";
+import { availableParallelism, freemem, loadavg, totalmem } from "node:os";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+import { localUrl } from "../session/session.js";
+const node = z.object({ name: z.string(), ws_uri: z.string() });
+const topology = z.object({
+    relay: z.object({ nodes: z.array(node) }),
+    parachains: z.record(z.string(), z.array(z.object({ collators: z.array(node) }))),
+});
+export function progressEndpoints(raw) {
+    const parsed = topology.parse(raw);
+    return [
+        ...parsed.relay.nodes.map((entry) => ({ ...entry, relay: true })),
+        ...Object.values(parsed.parachains).flatMap((groups) => groups.flatMap((group) => group.collators.map((entry) => ({ ...entry, relay: false })))),
+    ].map(({ name, ws_uri, relay }) => ({
+        name,
+        relay,
+        url: localUrl(ws_uri, ["ws:", "wss:"]).replace(/^ws/, "http"),
+    }));
+}
+export async function readNodeProgress(client, endpoint, signal) {
+    const request = async (method, params = []) => {
+        const result = await client.request(localUrl(endpoint.url), method, params, { timeoutMs: 2000, signal });
+        if (result == null)
+            throw new Error(`${method}: no result`);
+        return result;
+    };
+    const observe = async (method, params = []) => {
+        try {
+            return await request(method, params);
+        }
+        catch (error) {
+            return { error: String(error) };
+        }
+    };
+    const finalized = await observe("chain_getFinalizedHead");
+    const [best, finalizedHeader, grandpa] = await Promise.all([
+        observe("chain_getHeader"),
+        typeof finalized === "string"
+            ? observe("chain_getHeader", [finalized])
+            : finalized,
+        endpoint.relay ? observe("grandpa_roundState") : undefined,
+    ]);
+    return { name: endpoint.name, best, finalized, finalizedHeader, grandpa };
+}
+function resourceSnapshot() {
+    const linux = {};
+    if (process.platform === "linux") {
+        for (const path of [
+            "/proc/pressure/cpu",
+            "/proc/pressure/memory",
+            "/sys/fs/cgroup/cpu.stat",
+            "/sys/fs/cgroup/cpu.max",
+            "/sys/fs/cgroup/cpu.pressure",
+            "/sys/fs/cgroup/memory.events",
+            "/sys/fs/cgroup/memory.current",
+            "/sys/fs/cgroup/memory.max",
+            "/sys/fs/cgroup/memory.pressure",
+        ]) {
+            try {
+                linux[path] = readFileSync(path, "utf8");
+            }
+            catch {
+            }
+        }
+    }
+    return {
+        parallelism: availableParallelism(),
+        load: loadavg(),
+        freeBytes: freemem(),
+        totalBytes: totalmem(),
+        linux,
+    };
+}
+export async function recordEngineProgress(client, spawnFile, output, signal) {
+    while (!signal.aborted) {
+        let observation;
+        try {
+            const endpoints = progressEndpoints(JSON.parse(readFileSync(spawnFile, "utf8")));
+            observation = {
+                nodes: await Promise.all(endpoints.map((entry) => readNodeProgress(client, entry, signal))),
+            };
+        }
+        catch (error) {
+            observation = { discoveryError: String(error) };
+        }
+        if (signal.aborted)
+            break;
+        appendFileSync(output, JSON.stringify({
+            at: new Date().toISOString(),
+            resources: resourceSnapshot(),
+            observation,
+        }) + "\n");
+        await delay(15_000, undefined, { signal }).catch((error) => {
+            if (!signal.aborted)
+                throw error;
+        });
+    }
+}

package/adapters/environment/engine/src/index.d.ts

@@ -0,0 +1,52 @@
+export * from "./session/session.js";
+export * from "./session/readiness.js";
+export * from "./session/engine-networks.js";
+export * from "./session/runtime-dependency.js";
+export { chainSchema } from "./session/chain-observation.js";
+export { acquireScenarioLock, networkLockIdentity, NetworkLockError, RECLAIM_STALE_LOCK_ENV, type LockableSession, type NetworkLockOptions, } from "./session/network-lock.js";
+export { ChainsNotReadyError, EndpointUnansweredError, errorMessage, FinalityNotAdvancingError, FinalityPinnedError, FinalityStalledError, IncompleteNetworkError, MissingEngineToolingError, PortOccupiedError, systemErrorCode, type FinalityStall, type MissingPersistedData, type MissingToolingPath, type ReadinessOptions, } from "./errors.js";
+export { ForkSetupError, ensurePeopleLiteAttestationAllowance, type PeopleLiteAllowance } from "./engine/fork-setup.js";
+export { NETWORK_SEED_RECORD, NetworkSeedRefused, adoptNetworkSeed, networkSeedDirectory, networkSeedProblems, publishNetworkSeed, readNetworkSeed, type AdoptedSeed, type NetworkSeedRecord, type NetworkSeedTarget } from "./engine/network-seed.js";
+export { FORK_TOPOLOGIES, LIGHT_BUNDLE_SOURCE, applyForkLayoutDescriptor, forkLayout, forkTopologyWorkspace, mergeDescriptor, publishesLayout, type ForkLayout, type ForkTopologyName, type LayoutBundleSource } from "./engine/fork-topology.js";
+export { STALL_EVIDENCE, describeLostApprovals, keepStallEvidence, lostApprovalChecks, unapprovable, type LostApprovalCheck } from "./engine/finality-stall.js";
+export { APPROVAL_PIN_GAP, APPROVAL_PIN_HOLD_MS, APPROVAL_PIN_RESTARTS, ApprovalPinWatch, describeApprovalPin, relayHeads, type ApprovalPin, type PinState, type RelayHeads } from "./engine/approval-pin.js";
+export { CHAIN_CLOCK_MAX_LAG_MS, CHAIN_CLOCK_TIMEOUT_MS, ChainClockBehindError, TIMESTAMP_NOW_KEY, chainTime, waitForChainClocks, type ChainClockOptions, type ChainLag, type ChainTime, type ClockedChain } from "./engine/chain-clock.js";
+export * from "./engine/owned-engine.js";
+export * from "./engine/engine-health.js";
+export * from "./engine/drain.js";
+export { ENGINE_PHASES, EngineStartPhases, readServiceHealth, zombienetNodes, type EnginePhase, type ServiceHealth } from "./engine/engine-start-phases.js";
+export { applyEnginePorts, applyIpfsPorts, enginePortsSchema, type EnginePorts, } from "./engine/engine-ports.js";
+export { hasChainDatabase, isolatedPlan, PERSISTED_PHASES, phaseReporter, missingPersistedData, missingPersistedParts, persistentNetwork, stopTogether, requirePersistedData, restateEngineLocalEnv, restateEnginePorts, engineCheckout, portNames, resumePlan, requireFreePorts, WORKSPACE_VERSIONS_FILE, ENGINE_PORTS_FILE, completePlan, planFacts, probeEthRpc, type EthRpcStatus, type NetworkPlan, type NetworkStartRecovery, type PersistentNetworkOptions, type PersistentNetworkSystem, type PlanFacts, type StallRecoveryOptions, } from "./engine/persistent-network.js";
+export { missingSavedTooling, requireSavedTooling } from "./engine/saved-tooling.js";
+export { CheckoutLockTimeout, acquireCheckoutPorts, checkoutPortsLock, type CheckoutLockOptions } from "./engine/checkout-lock.js";
+export { ETH_RPC_PROCESS, containPlanPorts, ethRpcBinary, ethRpcProcess, listenedPorts, planPorts, portRangeSchema, remapBootNodePorts, remapSpecBootNodePorts, withEthRpc, type PortRange, } from "./engine/plan-ports.js";
+export { NETWORK_TEMPLATE, NETWORK_TEMPLATE_RECORD, cloneTree, hasNetworkTemplate, readNetworkTemplate, restoreNetworkTemplate, saveNetworkTemplate, type CopyMethod, type NetworkTemplateRecord, type RestoredNetwork, } from "./engine/network-template.js";
+export { resetPersistentNetwork, type NetworkReset } from "./engine/network-reset.js";
+export { ENGINE_NETWORK_SNAPSHOT, networkLineage, networkSnapshots, networkSnapshotsUnsupported, type NetworkSnapshotControl, type NetworkSnapshotSubject, } from "./engine/network-snapshots.js";
+export { ADOPTED_LINEAGE, applyNetworkAdoption, planNetworkAdoption, readAdoptedLineage, rewriteText, type NetworkAdoptionInput, type NetworkAdoptionPlan } from "./engine/network-adoption.js";
+export { AUTHORITY_DISCOVERY_CACHE, COLLATOR_WRAPPER, IPFS_IDENTITY_MARKER, LOOPBACK_ONLY_ADDRESS_FILTERS, assignForkTomlPorts, chainSpecFiles, planForkTomlPorts, type RelaySidePorts, collatorWrapperScript, moveForkTomlPorts, NODE_WRAPPER_DIRECTORY, nodeWrapperScript, nonLoopbackListeners, forkIsolationSchema, inspectIsolation, ipfsIdentityRotation, isolateForkToml, isolateIpfsConfig, isolateIpfsRepository, requireIpfsRepository, isolateNodeArgs, TXPOOL_LOG_LEVELS, nodeLogTargets, withNodeLogTargets, BULLETIN_AUTHORING, withBulletinAuthoring, type BulletinAuthoring, type TxpoolLog, isolatePersistedNetwork, nodeKeyTool, renameBootNodes, writeIsolatedForkToml, zombieNodes, type ForkIsolation, type ForkTomlIsolation, type NodeKeys, type PersistedIsolation, type ZombieNode, } from "./engine/fork-isolation.js";
+export { forkBundleManifestPath, forkSnapshotFrom, readForkSnapshot, } from "./engine/fork-snapshot.js";
+export { publishedNetworkEndpoints, type PublicNetworkEndpoint, type PublishedNetwork } from "./engine/live-network.js";
+export { AUTHORIZED_UPGRADE_KEY, LAST_RUNTIME_UPGRADE_KEY, PENDING_VALIDATION_CODE_KEY, RUNTIME_UPGRADES_FILE, UPGRADABLE_CHAINS, decodeLastRuntimeUpgrade, observeRuntime, recordRuntimeUpgrade, upgradeRuntime, type RecordedRuntimeUpgrade, type RuntimeState, type RuntimeUpgradeRequest, type RuntimeUpgradeResult, type UpgradableChain, } from "./engine/runtime-upgrade.js";
+export { backgroundPriority, bittenAfter, bundleLocations, completePrefetch, currentBundle, finishPrefetch, discardPrevious, engineReleaseSettings, installStagedBundle, manifestFromTarHead, MANIFEST_SEARCH_BYTES, TarManifestScanner, prefetchActive, publishedBundle, restorePrevious, stagedBundle, startPrefetch, type PublishedBundle, } from "./engine/published-bundle.js";
+export { acquireForkBundleLock, BUNDLE_MARKER, forkBundleLock, forkBundleState, incomingBundle, installIncomingBundle, markedComplete, markForkBundle, verifyForkBundle, type BundleCheck, type BundleState, } from "./engine/fork-bundle.js";
+export { ownedEngineEnvironment, type OwnedEngineEnvironmentOptions, } from "./engine/owned-environment.js";
+export { DEFAULT_MAX_SNAPSHOT_AGE_MS, EngineVersionMismatch, VersionedEngineDependency, engineVersionCheck, engineVersionPlan, engineVersionsRecord, workspaceVersionPlan, type EngineRuntimeRow, type EngineVersionCheck, type EngineVersionPlan, type EngineVersionPlanOptions, } from "./versions/engine-versions.js";
+export { preserveEngineLogs } from "./evidence/engine-logs.js";
+export { progressEndpoints, readNodeProgress, recordEngineProgress, } from "./evidence/engine-progress.js";
+export { defaultEngineRepository, defaultStateDirectory, enginePatch, EngineNotPrepared, engineRepository, prepareEngine, preparedEngine, recordedPatch, setupPaths, testedEngineRef, type EngineBuildRecord, type EngineSource, type PreparedEngine, type PreparedEnginePatch, } from "./setup/prepare-engine.js";
+export { ENGINE_PATCHES, engineBuildIssue, type EnginePatch } from "./setup/engine-build.js";
+export { CHECKOUT_ENGINE_SETUP, engineSetupCommand } from "./setup/setup-command.js";
+export { engineBuildWords, savedForkEngine, savedForkEngineState, savedForkSetupCommand, savedForkTooling } from "./saved-fork/saved-fork-tooling.js";
+export { ENGINE_PATCHES_REPOSITORY_ONLY, EnginePatchesNotInstalled, patchesDirectory, patchesInstalled, readPatchManifest, resolvePatch, type PatchEntry, } from "./setup/patches.js";
+export { DESCRIPTOR_OVERLAYS, LIGHT_TOPOLOGY_OVERLAY, OWNED_PROCESSES_PATCH } from "./setup/patch-catalogue.js";
+export { engineLaunchPlan, type EngineCommand, type EngineLaunchPlan, } from "./topology/engine-plan.js";
+export { DEFAULT_ENGINE_DASHBOARD, enginePortOverrides, engineRun, type EngineIsolationInput, type EngineRun, type EngineRunIsolation, } from "./topology/engine-run.js";
+export { ENGINE_TIME_UNSUPPORTED, describeEngine, engineEnvironment, type EngineEnvironmentSettings, } from "./topology/engine-provider.js";
+export { EngineEnvironmentFactory } from "./topology/engine-environment-factory.js";
+export { DEFAULT_ENGINE_PORTS, ENGINE_FLAGS, ENGINE_KIND, ENGINE_P2P_PORTS, acceptsEngine, engineFlagOptions, engineOptionsSchema, engineProfileOptions, engineProfiles, resolveEngineTopology, type EngineSettings, type EngineTopology, type EngineTopologyOptions, } from "./topology/engine-topology.js";
+export { chainLabel, FORK_RUNTIMES_FILE, FORKED_CHAINS, forkState, freshness, liveEndpoints, resolveNetworkRpc, readSavedJson, recordForkRuntimes, refreshCommand, shortError, updateForkRuntimes, updateRuntimeCommand, type ChainRuntime, type ForkedChain, type ForkState, type ForkUpdateCommands, type ForkUpgradeTarget, type Freshness, type LiveCodeFetcher, type LiveRead, type LiveRuntime, type LiveRuntimeReader, type RuntimeChange, type UpgradeDeps, type UpgradedRuntime, } from "./engine/fork-freshness.js";
+export { newerStateNotice, prefetchNewerState, prepareRefresh, PUBLISHED_CHECK_MS, type PrefetchDeps, type RefreshCarry, type RefreshDeps, type RefreshHandle, } from "./engine/fork-refresh.js";
+export { savedForkUpdates, type SavedForkUpdates, type SavedForkUpdatesOptions } from "./engine/fork-updates.js";
+export { ETURNAL_BREW_INSTALL, TURN_OFF_RECORD, TURN_PORT_OFFSETS, applyTurnRelayChoice, chooseTurnRelay, eturnalControl, eturnalProcesses, networkRunsTurnRelay, otherTurnRelays, refuseSecondTurnRelay, runsTurnRelay, turnPorts, turnRelayAvailable, turnRelayOffNotice, type EturnalLookup, type TurnRelayChoice } from "./engine/turn-relay.js";
+export { SAVED_FORK_LAYOUTS, SAVED_FORK_STARTUP_MS, requireFreshForkBlock, savedForkBlock, savedForkEnvironment, savedForkFor, savedForkPorts, savedForkReset, type SavedFork, type SavedForkSettings } from "./saved-fork/saved-fork.js";

package/adapters/environment/engine/src/index.js

@@ -0,0 +1,54 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export * from "./session/session.js";
+export * from "./session/readiness.js";
+export * from "./session/engine-networks.js";
+export * from "./session/runtime-dependency.js";
+export { chainSchema } from "./session/chain-observation.js";
+export { acquireScenarioLock, networkLockIdentity, NetworkLockError, RECLAIM_STALE_LOCK_ENV, } from "./session/network-lock.js";
+export { ChainsNotReadyError, EndpointUnansweredError, errorMessage, FinalityNotAdvancingError, FinalityPinnedError, FinalityStalledError, IncompleteNetworkError, MissingEngineToolingError, PortOccupiedError, systemErrorCode, } from "./errors.js";
+export { ForkSetupError, ensurePeopleLiteAttestationAllowance } from "./engine/fork-setup.js";
+export { NETWORK_SEED_RECORD, NetworkSeedRefused, adoptNetworkSeed, networkSeedDirectory, networkSeedProblems, publishNetworkSeed, readNetworkSeed } from "./engine/network-seed.js";
+export { FORK_TOPOLOGIES, LIGHT_BUNDLE_SOURCE, applyForkLayoutDescriptor, forkLayout, forkTopologyWorkspace, mergeDescriptor, publishesLayout } from "./engine/fork-topology.js";
+export { STALL_EVIDENCE, describeLostApprovals, keepStallEvidence, lostApprovalChecks, unapprovable } from "./engine/finality-stall.js";
+export { APPROVAL_PIN_GAP, APPROVAL_PIN_HOLD_MS, APPROVAL_PIN_RESTARTS, ApprovalPinWatch, describeApprovalPin, relayHeads } from "./engine/approval-pin.js";
+export { CHAIN_CLOCK_MAX_LAG_MS, CHAIN_CLOCK_TIMEOUT_MS, ChainClockBehindError, TIMESTAMP_NOW_KEY, chainTime, waitForChainClocks } from "./engine/chain-clock.js";
+export * from "./engine/owned-engine.js";
+export * from "./engine/engine-health.js";
+export * from "./engine/drain.js";
+export { ENGINE_PHASES, EngineStartPhases, readServiceHealth, zombienetNodes } from "./engine/engine-start-phases.js";
+export { applyEnginePorts, applyIpfsPorts, enginePortsSchema, } from "./engine/engine-ports.js";
+export { hasChainDatabase, isolatedPlan, PERSISTED_PHASES, phaseReporter, missingPersistedData, missingPersistedParts, persistentNetwork, stopTogether, requirePersistedData, restateEngineLocalEnv, restateEnginePorts, engineCheckout, portNames, resumePlan, requireFreePorts, WORKSPACE_VERSIONS_FILE, ENGINE_PORTS_FILE, completePlan, planFacts, probeEthRpc, } from "./engine/persistent-network.js";
+export { missingSavedTooling, requireSavedTooling } from "./engine/saved-tooling.js";
+export { CheckoutLockTimeout, acquireCheckoutPorts, checkoutPortsLock } from "./engine/checkout-lock.js";
+export { ETH_RPC_PROCESS, containPlanPorts, ethRpcBinary, ethRpcProcess, listenedPorts, planPorts, portRangeSchema, remapBootNodePorts, remapSpecBootNodePorts, withEthRpc, } from "./engine/plan-ports.js";
+export { NETWORK_TEMPLATE, NETWORK_TEMPLATE_RECORD, cloneTree, hasNetworkTemplate, readNetworkTemplate, restoreNetworkTemplate, saveNetworkTemplate, } from "./engine/network-template.js";
+export { resetPersistentNetwork } from "./engine/network-reset.js";
+export { ENGINE_NETWORK_SNAPSHOT, networkLineage, networkSnapshots, networkSnapshotsUnsupported, } from "./engine/network-snapshots.js";
+export { ADOPTED_LINEAGE, applyNetworkAdoption, planNetworkAdoption, readAdoptedLineage, rewriteText } from "./engine/network-adoption.js";
+export { AUTHORITY_DISCOVERY_CACHE, COLLATOR_WRAPPER, IPFS_IDENTITY_MARKER, LOOPBACK_ONLY_ADDRESS_FILTERS, assignForkTomlPorts, chainSpecFiles, planForkTomlPorts, collatorWrapperScript, moveForkTomlPorts, NODE_WRAPPER_DIRECTORY, nodeWrapperScript, nonLoopbackListeners, forkIsolationSchema, inspectIsolation, ipfsIdentityRotation, isolateForkToml, isolateIpfsConfig, isolateIpfsRepository, requireIpfsRepository, isolateNodeArgs, TXPOOL_LOG_LEVELS, nodeLogTargets, withNodeLogTargets, BULLETIN_AUTHORING, withBulletinAuthoring, isolatePersistedNetwork, nodeKeyTool, renameBootNodes, writeIsolatedForkToml, zombieNodes, } from "./engine/fork-isolation.js";
+export { forkBundleManifestPath, forkSnapshotFrom, readForkSnapshot, } from "./engine/fork-snapshot.js";
+export { publishedNetworkEndpoints } from "./engine/live-network.js";
+export { AUTHORIZED_UPGRADE_KEY, LAST_RUNTIME_UPGRADE_KEY, PENDING_VALIDATION_CODE_KEY, RUNTIME_UPGRADES_FILE, UPGRADABLE_CHAINS, decodeLastRuntimeUpgrade, observeRuntime, recordRuntimeUpgrade, upgradeRuntime, } from "./engine/runtime-upgrade.js";
+export { backgroundPriority, bittenAfter, bundleLocations, completePrefetch, currentBundle, finishPrefetch, discardPrevious, engineReleaseSettings, installStagedBundle, manifestFromTarHead, MANIFEST_SEARCH_BYTES, TarManifestScanner, prefetchActive, publishedBundle, restorePrevious, stagedBundle, startPrefetch, } from "./engine/published-bundle.js";
+export { acquireForkBundleLock, BUNDLE_MARKER, forkBundleLock, forkBundleState, incomingBundle, installIncomingBundle, markedComplete, markForkBundle, verifyForkBundle, } from "./engine/fork-bundle.js";
+export { ownedEngineEnvironment, } from "./engine/owned-environment.js";
+export { DEFAULT_MAX_SNAPSHOT_AGE_MS, EngineVersionMismatch, VersionedEngineDependency, engineVersionCheck, engineVersionPlan, engineVersionsRecord, workspaceVersionPlan, } from "./versions/engine-versions.js";
+export { preserveEngineLogs } from "./evidence/engine-logs.js";
+export { progressEndpoints, readNodeProgress, recordEngineProgress, } from "./evidence/engine-progress.js";
+export { defaultEngineRepository, defaultStateDirectory, enginePatch, EngineNotPrepared, engineRepository, prepareEngine, preparedEngine, recordedPatch, setupPaths, testedEngineRef, } from "./setup/prepare-engine.js";
+export { ENGINE_PATCHES, engineBuildIssue } from "./setup/engine-build.js";
+export { CHECKOUT_ENGINE_SETUP, engineSetupCommand } from "./setup/setup-command.js";
+export { engineBuildWords, savedForkEngine, savedForkEngineState, savedForkSetupCommand, savedForkTooling } from "./saved-fork/saved-fork-tooling.js";
+export { ENGINE_PATCHES_REPOSITORY_ONLY, EnginePatchesNotInstalled, patchesDirectory, patchesInstalled, readPatchManifest, resolvePatch, } from "./setup/patches.js";
+export { DESCRIPTOR_OVERLAYS, LIGHT_TOPOLOGY_OVERLAY, OWNED_PROCESSES_PATCH } from "./setup/patch-catalogue.js";
+export { engineLaunchPlan, } from "./topology/engine-plan.js";
+export { DEFAULT_ENGINE_DASHBOARD, enginePortOverrides, engineRun, } from "./topology/engine-run.js";
+export { ENGINE_TIME_UNSUPPORTED, describeEngine, engineEnvironment, } from "./topology/engine-provider.js";
+export { EngineEnvironmentFactory } from "./topology/engine-environment-factory.js";
+export { DEFAULT_ENGINE_PORTS, ENGINE_FLAGS, ENGINE_KIND, ENGINE_P2P_PORTS, acceptsEngine, engineFlagOptions, engineOptionsSchema, engineProfileOptions, engineProfiles, resolveEngineTopology, } from "./topology/engine-topology.js";
+export { chainLabel, FORK_RUNTIMES_FILE, FORKED_CHAINS, forkState, freshness, liveEndpoints, resolveNetworkRpc, readSavedJson, recordForkRuntimes, refreshCommand, shortError, updateForkRuntimes, updateRuntimeCommand, } from "./engine/fork-freshness.js";
+export { newerStateNotice, prefetchNewerState, prepareRefresh, PUBLISHED_CHECK_MS, } from "./engine/fork-refresh.js";
+export { savedForkUpdates } from "./engine/fork-updates.js";
+export { ETURNAL_BREW_INSTALL, TURN_OFF_RECORD, TURN_PORT_OFFSETS, applyTurnRelayChoice, chooseTurnRelay, eturnalControl, eturnalProcesses, networkRunsTurnRelay, otherTurnRelays, refuseSecondTurnRelay, runsTurnRelay, turnPorts, turnRelayAvailable, turnRelayOffNotice } from "./engine/turn-relay.js";
+export { SAVED_FORK_LAYOUTS, SAVED_FORK_STARTUP_MS, requireFreshForkBlock, savedForkBlock, savedForkEnvironment, savedForkFor, savedForkPorts, savedForkReset } from "./saved-fork/saved-fork.js";

package/adapters/environment/engine/src/saved-fork/saved-fork-tooling.d.ts

@@ -0,0 +1,20 @@
+import type { EnvironmentTooling } from "@parity/product-lab/ports/environment";
+import type { SyncCommandRunner } from "@parity/product-lab/ports/system";
+import { type PreparedEngine, type PreparedEnginePatch } from "../setup/prepare-engine.js";
+import type { SavedFork, SavedForkSettings } from "./saved-fork.js";
+type EngineSettings = Pick<SavedForkSettings, "cacheDir" | "setupCommand">;
+/** Where the saved forks' Engine is prepared: the cache's `engine/` folder, as its own state directory. */
+export declare const savedForkEngineState: (cacheDir: string) => string;
+/** The command that prepares the fork's Engine where this runs (the lab's, else `engineSetupCommand`). */
+export declare const savedForkSetupCommand: (fork: SavedFork, settings: Pick<SavedForkSettings, "setupCommand">) => string;
+/**
+ * The prepared Engine a saved fork starts from, or `EngineNotPrepared` naming the command that prepares it. A start
+ * takes the recorded stock build (`as-prepared`), including an explicitly selected ref. Retired patched records
+ * are refused. `ref`: when supplied, also check that commit.
+ */
+export declare function savedForkEngine(fork: SavedFork, settings: EngineSettings, commands: SyncCommandRunner, patch?: PreparedEnginePatch, ref?: string): PreparedEngine;
+/** One line for a prepared build: which Engine, from where, whether it is the tested release, and where it is. */
+export declare function engineBuildWords(engine: PreparedEngine): string;
+/** The saved fork's Engine checkout as an environment's tooling. */
+export declare function savedForkTooling(fork: SavedFork, settings: EngineSettings): EnvironmentTooling;
+export {};

package/adapters/environment/engine/src/saved-fork/saved-fork-tooling.js

@@ -0,0 +1,66 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { join } from "node:path";
+import { defaultEngineRepository, EngineNotPrepared, prepareEngine, preparedEngine, recordedPatch, testedEngineRef } from "../setup/prepare-engine.js";
+import { engineSetupCommand } from "../setup/setup-command.js";
+export const savedForkEngineState = (cacheDir) => join(cacheDir, "engine");
+export const savedForkSetupCommand = (fork, settings) => settings.setupCommand ?? engineSetupCommand(fork.startAs.environment);
+export function savedForkEngine(fork, settings, commands, patch = "as-prepared", ref) {
+    return preparedEngine(savedForkEngineState(settings.cacheDir), { stateDirectory: ".", fix: savedForkSetupCommand(fork, settings), commands, patch, ...(ref ? { ref } : {}) });
+}
+export function engineBuildWords(engine) {
+    const { build } = engine;
+    const ref = build.resolvedRef.slice(0, 12);
+    const from = build.repository && build.repository !== defaultEngineRepository ? ` from ${build.repository}` : "";
+    const tested = build.resolvedRef === testedEngineRef ? "" : ` (not the tested ${testedEngineRef.slice(0, 12)}: \`product-lab fetch\` without --engine-ref prepares it)`;
+    return recordedPatch(build) === "none"
+        ? `stock Engine ${ref}${from}${tested}, ${engine.checkout}`
+        : `retired patched Engine ${ref}${from}; prepare stock Engine again, ${engine.checkout}`;
+}
+function syncCommands(system) {
+    if (!system.syncCommands)
+        throw new Error("The Engine checkout is checked through the lab's sync command adapter (SystemPorts.syncCommands), which this lab lacks");
+    return system.syncCommands;
+}
+export function savedForkTooling(fork, settings) {
+    const state = savedForkEngineState(settings.cacheDir);
+    const fix = savedForkSetupCommand(fork, settings);
+    const status = (commands, patch, ref) => {
+        try {
+            return { ready: true, detail: engineBuildWords(savedForkEngine(fork, settings, commands, patch, ref)) };
+        }
+        catch (error) {
+            if (!(error instanceof EngineNotPrepared))
+                throw error;
+            return { ready: false, detail: error.reason, fix };
+        }
+    };
+    return {
+        id: `engine:${state}`,
+        kind: "engine",
+        label: "Engine checkout",
+        check: (system) => status(syncCommands(system), "as-prepared"),
+        async prepare(request) {
+            const commands = syncCommands(request.system);
+            const source = request.source ?? {};
+            const patch = source.patched === true ? "owned-processes" : "none";
+            const ref = source.ref ?? testedEngineRef;
+            const pinned = /^[0-9a-f]{40}$/i.test(ref);
+            const already = pinned ? status(commands, patch, ref) : undefined;
+            if (already?.ready) {
+                request.log?.(`Engine checkout: already prepared (${already.detail})`);
+                return { ...already, prepared: false };
+            }
+            request.log?.(`Engine ${ref.slice(0, 12)} from ${source.repository ?? defaultEngineRepository}, ${patch === "none" ? "stock (no lab patch)" : "retired patch request (refused)"}, into ${state}: ` +
+                "clone, pnpm install and build, Engine's fetch of the network's binaries, the pinned dot CLI (the first time: a few minutes and about 900 MB)");
+            const homebrewPrefix = request.system.environment?.get("HOMEBREW_PREFIX");
+            prepareEngine(state, ref, fork.network, commands, ".", { platform: process.platform, ...(homebrewPrefix ? { homebrewPrefix } : {}) }, {
+                ...(source.repository ? { repository: source.repository } : {}),
+                patch,
+                ...(request.output ? { output: request.output } : {}),
+            });
+            const after = status(commands, "as-prepared", pinned ? ref : undefined);
+            return { ...after, prepared: after.ready };
+        },
+    };
+}