@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/environment/engine/src/engine/checkout-lock.js

@@ -0,0 +1,136 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+export const checkoutPortsLock = (checkout) => {
+    let canonical = resolve(checkout);
+    try {
+        canonical = realpathSync(checkout);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    return join(canonical, "config", "ports.env.lock");
+};
+export class CheckoutLockTimeout extends Error {
+    lock;
+    waitedMs;
+    owner;
+    constructor(lock, waitedMs, owner) {
+        super(`Engine checkout exclusivity refused at ${lock}${owner?.network ? ` (${String(owner.network)}${owner.pid ? `, pid ${owner.pid}` : ""})` : ""}: stock Engine has a shared-checkout sweep gap during finishGroup; use a separate cache or checkout for each live network. A live lock is never broken`);
+        this.lock = lock;
+        this.waitedMs = waitedMs;
+        this.owner = owner;
+        this.name = "CheckoutLockTimeout";
+    }
+}
+export async function acquireCheckoutPorts(locks, checkout, options) {
+    options.signal?.throwIfAborted();
+    if (!checkout)
+        return undefined;
+    if (!locks)
+        throw new Error(`Engine checkout exclusivity requires a LockManager for ${checkout}; stock Engine's shared-checkout sweep gap requires a separate cache or checkout for each live network`);
+    const path = checkoutPortsLock(checkout);
+    const registry = options.registry ?? options.own?.directory;
+    const request = { path, record: { network: options.network, ...(registry ? { registries: [registry] } : {}), purpose: "exclusive checkout through Engine finishGroup" }, onStale: "report", ownerless: "report" };
+    let attempt = locks.tryAcquire(request);
+    const fingerprint = !attempt.acquired ? attempt.owner?.process : undefined;
+    const recorded = fingerprint && Number.isSafeInteger(fingerprint.pid) && fingerprint.pid > 0
+        && Number.isSafeInteger(fingerprint.parent) && fingerprint.parent >= 0
+        && Number.isSafeInteger(fingerprint.group) && fingerprint.group > 0
+        && typeof fingerprint.started === "string" && fingerprint.started.length > 0;
+    if (!attempt.acquired && attempt.reason === "stale" && recorded) {
+        requireGoneMembers(path, attempt.owner, options);
+        attempt = locks.tryAcquire({ ...request, onStale: "reclaim" });
+    }
+    if (!attempt.acquired) {
+        options.waiting?.(attempt.owner);
+        throw new CheckoutLockTimeout(path, 0, attempt.owner);
+    }
+    if (attempt.lock.reclaimed)
+        options.recovered?.(attempt.lock.reclaimed);
+    return attempt.lock;
+}
+const canonical = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+};
+function requireGoneMembers(lock, owner, options) {
+    const workspace = typeof owner.network === "string" ? owner.network : "unknown";
+    const holder = `its holder (pid ${String(owner.process?.pid ?? owner.pid ?? "?")}) is gone`;
+    const refuse = (reason) => {
+        throw new Error(`Engine checkout recovery refused at ${lock}: ${holder}, but ${reason}. Stop the workspace ${workspace} (start its lab again, which stops what it left, or stop the recorded processes), then retry; a separate cache or checkout avoids the wait. Stock Engine's cleanup sweeps every service of its checkout`);
+    };
+    const directories = owner.registries;
+    if (!Array.isArray(directories) || !directories.length || directories.some((path) => typeof path !== "string" || !path))
+        return refuse(`its record names no process registry to check (written by an older lab, or by a holder that recorded none); remove ${lock} once nothing of that workspace runs`);
+    for (const directory of directories) {
+        const mine = options.own && canonical(options.own.directory) === canonical(directory) ? options.own : undefined;
+        if (!mine && !existsSync(directory))
+            continue;
+        const registry = mine ?? options.inspect?.open(directory);
+        if (!registry)
+            return refuse(`no process port here can read its registry ${directory}`);
+        const allowed = mine && options.survivors === "own";
+        let live;
+        let commands = [];
+        try {
+            live = registry.status().filter((entry) => entry.processes > 0);
+            if (live.length && !allowed)
+                commands = live.flatMap((entry) => registry.commands(entry.id));
+        }
+        finally {
+            if (!mine)
+                registry.close();
+        }
+        if (!live.length || allowed)
+            continue;
+        const running = `members it recorded in ${directory} still run (${live.map((entry) => `${entry.id}: ${entry.processes}`).join(", ")})`;
+        if (workspace !== "unknown" && canonical(directory) === canonical(join(workspace, "processes")))
+            refuse(running);
+        throw new Error(`Engine checkout recovery refused at ${lock}: ${holder}, but ${running}. No later start reads that registry, so nothing stops them by itself: stop ${commands.length ? `these processes (${commands.map((command) => `\`${command.length > 160 ? `${command.slice(0, 157)}...` : command}\``).join(", ")})` : "the processes it records"}, then retry; a separate cache or checkout avoids the wait. Stock Engine's cleanup sweeps every service of its checkout`);
+    }
+}
+export async function stopWorkspaceSurvivors(directory, system, named, signal) {
+    const supervisor = system.processes;
+    const live = supervisor.status().filter((entry) => entry.processes > 0);
+    if (!live.length)
+        return;
+    const checkouts = [...new Map(named.filter((path) => !!path).map((path) => [checkoutPortsLock(path), path])).values()];
+    const held = [];
+    try {
+        for (const checkout of checkouts) {
+            const lock = await acquireCheckoutPorts(system.locks, checkout, {
+                network: directory, waitMs: 0, own: supervisor, survivors: "own", ...(system.registries ? { inspect: system.registries } : {}), ...(signal ? { signal } : {}),
+                recovered: (owner) => system.logger.warn(`Recovered the Engine checkout lock at ${checkout} from ${String(owner.network ?? "an exited lab")}, which exited without stopping its network`),
+            });
+            if (lock)
+                held.push(lock);
+        }
+    }
+    catch (error) {
+        for (const lock of held)
+            lock.release();
+        throw error;
+    }
+    system.logger.warn(`${directory}: stopping what an earlier lab left running (${live.map((entry) => `${entry.id}: ${entry.processes}`).join(", ")})${checkouts.length ? ` while holding ${checkouts.join(", ")}` : ""}`);
+    await supervisor.stopAll();
+    for (const lock of held)
+        lock.release();
+}
+export function namedCheckout(files, engineConfig) {
+    try {
+        const checkout = engineConfig ? files.readJson(resolve(engineConfig))?.checkout : undefined;
+        return typeof checkout === "string" ? checkout : undefined;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return undefined;
+        throw error;
+    }
+}

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

@@ -0,0 +1,54 @@
+import type { JsonRpcClient, Logger } from "@parity/product-lab/ports/system";
+/** How long the relay may take to include and finalize the collators' last candidates. */
+export declare const DRAIN_TIMEOUT_MS = 120000;
+/** Relay blocks without any parachain head changing before nothing is taken to be pending inclusion. */
+export declare const DRAIN_QUIET_BLOCKS = 3;
+/** twox128("Paras") ++ twox128("Heads"): the prefix of every `Paras.Heads(paraId)` key. */
+export declare const PARAS_HEADS_PREFIX = "0xcd710b30bd2eab0352ddcc26417aa1941b3c252fcb29d88eff4f3de5de4476c3";
+export interface DrainPlan {
+    /** The saved processes that produce parachain blocks (their arguments carry `--collator`). */
+    collators: readonly string[];
+    /** A relay validator's RPC endpoint (`ws://127.0.0.1:<rpc port>`). */
+    relay: string;
+}
+export interface DrainSystem {
+    stop(ids: readonly string[]): Promise<void>;
+    rpc: JsonRpcClient;
+    logger: Pick<Logger, "info" | "warn">;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export interface DrainResult {
+    /** True when every candidate included after the collators stopped was finalized, and none was pending, before the bound. */
+    drained: boolean;
+    /** The relay's best block when the collators had stopped. */
+    best?: number;
+    /** The relay block in which a parachain head last changed (the last inclusion seen). */
+    lastInclusion?: number;
+    /** The relay's best and finalized blocks when the drain ended. */
+    endBest?: number;
+    finalized?: number;
+    ms: number;
+    /** Why the drain did not complete (the network is stopped anyway). */
+    reason?: string;
+}
+/** Where the relay answers: the first relay validator's RPC (`ws://127.0.0.1:<rpc port>`); undefined when the plan has none. */
+export declare function relayEndpoint(processes: readonly {
+    id: string;
+    plan: {
+        args: readonly string[];
+    };
+}[]): string | undefined;
+/** Which saved processes are collators and where the relay answers; undefined when the plan has neither (nothing to drain). */
+export declare function drainPlan(processes: readonly {
+    id: string;
+    plan: {
+        args: readonly string[];
+    };
+}[]): DrainPlan | undefined;
+/** Stop the collators, then wait (bounded) until their last candidates are included and finalized. */
+export declare function drainCollators(plan: DrainPlan, system: DrainSystem, options?: {
+    timeoutMs?: number;
+    pollMs?: number;
+    quietBlocks?: number;
+}): Promise<DrainResult>;

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

@@ -0,0 +1,74 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { rpc } from "../session/readiness.js";
+export const DRAIN_TIMEOUT_MS = 120_000;
+export const DRAIN_QUIET_BLOCKS = 3;
+const DRAIN_POLL_MS = 1000;
+export const PARAS_HEADS_PREFIX = "0xcd710b30bd2eab0352ddcc26417aa1941b3c252fcb29d88eff4f3de5de4476c3";
+export function relayEndpoint(processes) {
+    const validator = processes.find((entry) => entry.plan.args.includes("--validator") && !entry.plan.args.includes("--collator"));
+    const port = validator ? validator.plan.args[validator.plan.args.indexOf("--rpc-port") + 1] : undefined;
+    return port && /^\d+$/.test(port) ? `ws://127.0.0.1:${port}` : undefined;
+}
+export function drainPlan(processes) {
+    const collators = processes.filter((entry) => entry.plan.args.includes("--collator")).map((entry) => entry.id);
+    const relay = relayEndpoint(processes);
+    if (!collators.length || !relay)
+        return undefined;
+    return { collators, relay };
+}
+const blockNumber = (header) => Number(BigInt(header.number));
+const errorText = (error) => (error instanceof Error ? error.message : String(error));
+export async function drainCollators(plan, system, options = {}) {
+    const now = system.now ?? Date.now;
+    const sleep = system.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const timeoutMs = options.timeoutMs ?? DRAIN_TIMEOUT_MS;
+    const pollMs = options.pollMs ?? DRAIN_POLL_MS;
+    const quiet = options.quietBlocks ?? DRAIN_QUIET_BLOCKS;
+    const started = now();
+    await system.stop(plan.collators);
+    const call = (method, params = []) => rpc(system.rpc, plan.relay, method, params);
+    let best;
+    let keys;
+    try {
+        best = blockNumber(await call("chain_getHeader"));
+        keys = await call("state_getKeysPaged", [PARAS_HEADS_PREFIX, 64, PARAS_HEADS_PREFIX]);
+    }
+    catch (error) {
+        const reason = `the relay did not answer at ${plan.relay}: ${errorText(error)}`;
+        system.logger.warn(`Draining before the stop was skipped: ${reason}; the next resume relies on its stall recovery`);
+        return { drained: false, ms: now() - started, reason };
+    }
+    let lastInclusion = best;
+    let seen;
+    let heads;
+    let endBest = best;
+    let finalized;
+    for (;;) {
+        try {
+            endBest = blockNumber(await call("chain_getHeader"));
+            if (endBest !== seen) {
+                const at = await call("chain_getBlockHash", [endBest]);
+                const current = (await Promise.all(keys.map((key) => call("state_getStorageHash", [key, at])))).join(",");
+                if (heads !== undefined && current !== heads)
+                    lastInclusion = Math.max(lastInclusion, endBest);
+                heads = current;
+                seen = endBest;
+            }
+            finalized = blockNumber(await call("chain_getHeader", [await call("chain_getFinalizedHead")]));
+        }
+        catch {
+        }
+        if (finalized !== undefined && endBest >= lastInclusion + quiet && finalized >= lastInclusion) {
+            const ms = now() - started;
+            system.logger.info(`Drained before the stop in ${ms} ms: the parachains' last inclusion (#${lastInclusion}) is final (relay finalized #${finalized}, best #${endBest}; best #${best} when the collators stopped)`);
+            return { drained: true, best, lastInclusion, endBest, finalized, ms };
+        }
+        if (now() - started + pollMs > timeoutMs) {
+            const reason = `the parachains' last inclusion seen was #${lastInclusion}; the relay was at best #${endBest}, finalized ${finalized === undefined ? "unknown" : `#${finalized}`}, after ${Math.round(timeoutMs / 1000)} s`;
+            system.logger.warn(`Draining before the stop did not complete: ${reason}; the network stops anyway and the next resume relies on its stall recovery`);
+            return { drained: false, best, lastInclusion, endBest, ...(finalized !== undefined ? { finalized } : {}), ms: now() - started, reason };
+        }
+        await sleep(pollMs);
+    }
+}

package/adapters/environment/engine/src/engine/engine-config.d.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import type { CommandRunner, EnvironmentVariables, JsonRpcClient, LockManager, Logger, OwnedProcesses, PortAllocator, ProcessRunner, StopPolicy, SyncCommandRunner, SystemPorts } from "@parity/product-lab/ports/system";
+import type { RunManifestStore } from "@parity/product-lab/ports/storage";
+/**
+ * What an owned Engine takes from the machine (Node implementations:
+ * `@parity/product-lab/system-node`; the caller constructs them).
+ */
+export interface EngineSystem {
+    /**
+     * Where Engine's process tree is recorded: a `ProcessRunner` (a registry
+     * is opened in the reports directory and Engine recorded as
+     * `engine-<time>`), or an open registry (a persistent network's workspace
+     * registry, Engine recorded as `engine-bootstrap`).
+     */
+    processes: ProcessRunner | OwnedProcesses;
+    /** Bounded one-shot setup commands. */
+    commands: CommandRunner;
+    /** Bounded synchronous checks before a network starts. */
+    syncCommands: SyncCommandRunner;
+    /** The dashboard port check (the lab never takes over a port another process holds). */
+    ports: PortAllocator;
+    /** Readiness and progress diagnostics. */
+    rpc: JsonRpcClient;
+    /** The environment `ppn` and `dot` inherit (`PATH` is extended with `extraPath`). */
+    environment: EnvironmentVariables;
+    /** Diagnostics that do not fail a start. */
+    logger: Logger;
+    /**
+     * Required at owned start: enforces one live network per checkout through completed stop.
+     * Also serializes the fork bundle's check and download (`<bundle>.lock`).
+     * Optional in the type for existing attached callers; owned starts fail closed when absent.
+     */
+    locks?: LockManager;
+    /**
+     * With `processes` one registry: reads the registries a dead checkout-lock holder recorded, so its lock is recovered
+     * only once every member it recorded is gone. Without it such a lock is refused.
+     */
+    registries?: Pick<ProcessRunner, "open">;
+}
+/** What an Engine topology environment takes: the owned Engine's system and where it writes its run manifest. */
+export interface EngineTopologySystem extends EngineSystem {
+    runManifests: RunManifestStore;
+}
+/** The Engine system from a lab's system ports; refuses a lab that supplies too few. */
+export declare function requireEngineSystem(deps: Partial<SystemPorts>): EngineTopologySystem;
+/**
+ * How Engine's tree is stopped: SIGINT (stock Engine makes `ppn`
+ * clean up its own process groups), 20 s for that, then SIGKILL to whatever
+ * is left, and a failed stop when a member survives 5 s more.
+ */
+export declare const ENGINE_STOP: StopPolicy;
+export { NODE_VERIFIER_OPTION, nodeVerifierArgs, type NodeVerifier } from "../setup/engine-build.js";
+export declare const engineConfiguration: z.ZodObject<{
+    checkout: z.ZodString;
+    workspace: z.ZodString;
+    network: z.ZodEnum<{
+        "paseo-next-v2": "paseo-next-v2";
+        previewnet: "previewnet";
+    }>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        fork: "fork";
+        genesis: "genesis";
+    }>>;
+    dashboard: z.ZodDefault<z.ZodString>;
+    extraPath: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    enginePatch: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        "owned-processes": "owned-processes";
+    }>>;
+    recordProgress: z.ZodDefault<z.ZodBoolean>;
+    nodeSupervision: z.ZodDefault<z.ZodBoolean>;
+    pinProducts: z.ZodDefault<z.ZodBoolean>;
+    forkTopology: z.ZodDefault<z.ZodEnum<{
+        faithful: "faithful";
+        light: "light";
+    }>>;
+    isolate: z.ZodDefault<z.ZodBoolean>;
+    expose: z.ZodDefault<z.ZodBoolean>;
+    txpoolLog: z.ZodDefault<z.ZodEnum<{
+        debug: "debug";
+        trace: "trace";
+    }>>;
+    bulletinAuthoring: z.ZodDefault<z.ZodEnum<{
+        lookahead: "lookahead";
+        "slot-based": "slot-based";
+    }>>;
+    ports: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    nodePorts: z.ZodOptional<z.ZodObject<{
+        from: z.ZodNumber;
+        to: z.ZodNumber;
+    }, z.core.$strict>>;
+    template: z.ZodDefault<z.ZodBoolean>;
+    seed: z.ZodOptional<z.ZodString>;
+    runsDirectory: z.ZodDefault<z.ZodString>;
+    startupTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type EngineConfiguration = z.infer<typeof engineConfiguration>;

package/adapters/environment/engine/src/engine/engine-config.js

@@ -0,0 +1,55 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { isAbsolute } from "node:path";
+import { z } from "zod";
+import { enginePortsSchema } from "./engine-ports.js";
+import { portRangeSchema } from "./plan-ports.js";
+import { FORK_TOPOLOGIES } from "./fork-topology.js";
+import { BULLETIN_AUTHORING, TXPOOL_LOG_LEVELS } from "./node-isolation.js";
+export function requireEngineSystem(deps) {
+    const { processes, commands, syncCommands, ports, rpc, environment, logger, runManifests, locks } = deps;
+    if (processes && commands && syncCommands && ports && rpc && environment && logger && runManifests)
+        return { processes, commands, syncCommands, ports, rpc, environment, logger, runManifests, ...(locks ? { locks } : {}) };
+    const missing = Object.entries({ processes, commands, syncCommands, ports, rpc, environment, logger, runManifests })
+        .filter(([, value]) => value === undefined)
+        .map(([name]) => name);
+    throw new Error(`The Engine environment needs the lab's system ports (${missing.join(", ")} missing): pass them as defineLab({ system })`);
+}
+export const ENGINE_STOP = { signal: "SIGINT", graceMs: 20_000, killGraceMs: 5_000 };
+export { NODE_VERIFIER_OPTION, nodeVerifierArgs } from "../setup/engine-build.js";
+import { ENGINE_PATCHES } from "../setup/engine-build.js";
+export const engineConfiguration = z
+    .strictObject({
+    checkout: z.string().refine(isAbsolute),
+    workspace: z.string().refine(isAbsolute),
+    network: z.enum(["paseo-next-v2", "previewnet"]),
+    mode: z.enum(["fork", "genesis"]).default("fork"),
+    dashboard: z.string().default("http://127.0.0.1:8090"),
+    extraPath: z.array(z.string().refine(isAbsolute)).default([]),
+    enginePatch: z.enum(ENGINE_PATCHES).default("none"),
+    recordProgress: z.boolean().default(false),
+    nodeSupervision: z.boolean().default(true),
+    pinProducts: z.boolean().default(false),
+    forkTopology: z.enum(FORK_TOPOLOGIES).default("faithful"),
+    isolate: z.boolean().default(true),
+    expose: z.boolean().default(false),
+    txpoolLog: z.enum(TXPOOL_LOG_LEVELS).default("debug"),
+    bulletinAuthoring: z.enum(BULLETIN_AUTHORING).default("slot-based"),
+    ports: enginePortsSchema.default({}),
+    nodePorts: portRangeSchema.optional(),
+    template: z.boolean().default(false),
+    seed: z.string().refine(isAbsolute).optional(),
+    runsDirectory: z
+        .string()
+        .regex(/^[\w.-]+$/)
+        .refine((name) => name !== "." && name !== "..")
+        .default("product-lab-runs"),
+    startupTimeoutMs: z
+        .number()
+        .int()
+        .min(10_000)
+        .max(7_200_000)
+        .default(600_000),
+})
+    .refine((config) => config.network !== "paseo-next-v2" || config.mode === "fork", "Paseo Next V2 requires fork mode")
+    .refine((config) => config.forkTopology === "faithful" || (config.mode === "fork" && config.isolate), "A fork topology other than faithful needs fork mode and isolation (isolate: true)");

package/adapters/environment/engine/src/engine/engine-health.d.ts

@@ -0,0 +1,99 @@
+/** One node to supervise: its zombie.json name, its metrics URL and, on a resume, the registry id of its process. */
+export interface EngineNodeEndpoint {
+    readonly name: string;
+    readonly url: string;
+    /** The process the lab started for it (a persistent network's `network-<name>`); absent when zombie-cli runs it. */
+    readonly process?: string;
+}
+/** What a node reported: its name and its process start time (seconds since the epoch). */
+export interface EngineNodeHealth {
+    readonly name: string;
+    readonly startedAt: number;
+}
+/** The node inventory cannot be supervised (missing, malformed, a duplicate name, a node without metrics). */
+export declare class EngineNodeInventoryRefused extends Error {
+    constructor(reason: string);
+}
+/** One or more nodes were lost: killed or exited, unreachable, or restarted. Names each node and why. */
+export declare class EngineNodeLost extends Error {
+    readonly nodes: readonly {
+        readonly name: string;
+        readonly reason: string;
+    }[];
+    constructor(nodes: readonly {
+        name: string;
+        reason: string;
+    }[], when?: string);
+    /** The first node lost. */
+    get node(): string;
+}
+/** The saved plan's processes a resume starts (network.json): a node's own `--prometheus-port`, before any `--`. */
+export interface InventoryPlan {
+    readonly processes: readonly {
+        readonly id: string;
+        readonly plan: {
+            readonly args: readonly string[];
+        };
+    }[];
+}
+/**
+ * Every node of an Engine network, from zombie.json (`raw`, parsed). With `plan` (a persistent network's resume)
+ * each node is the saved process `network-<name>` and its metrics port is the one its saved arguments give (a plan
+ * may have moved it). Refuses (EngineNodeInventoryRefused) a missing or malformed inventory, a duplicate node name,
+ * a non-loopback metrics endpoint, a node the plan does not start, and one whose metrics are switched off.
+ */
+export declare function engineNodeInventory(raw: unknown, plan?: InventoryPlan): EngineNodeEndpoint[];
+/** The inventory of the network whose zombie.json is `file`; a missing or unreadable file is refused. */
+export declare function readEngineNodeInventory(file: string, plan?: InventoryPlan): EngineNodeEndpoint[];
+/** Same health signal as zombie-cli; avoid parsing every unrelated metric. */
+export declare function processStartTime(metrics: string): number;
+/** How long one metrics request may take (zombie-cli's first check allows 20 s). */
+export declare const NODE_METRICS_TIMEOUT_MS = 20000;
+/** Every node's health at once; any node that cannot be read fails the whole check, naming each such node. */
+export declare function readEngineHealth(endpoints: readonly EngineNodeEndpoint[], signal: AbortSignal, options?: {
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}): Promise<EngineNodeHealth[]>;
+export declare function assertSameNodeProcesses(initial: readonly EngineNodeHealth[], current: readonly EngineNodeHealth[]): void;
+/** How a network's nodes are supervised; every field has a default. */
+export interface EngineNodeSupervisionOptions {
+    /** Stops the supervision (and cancels the first check). */
+    signal?: AbortSignal;
+    /** Between checks (default 5 s, zombie-cli's own interval). */
+    intervalMs?: number;
+    /** One metrics request's bound (default NODE_METRICS_TIMEOUT_MS). */
+    timeoutMs?: number;
+    /** Consecutive failed reads before an unreachable node is lost (default 2: one slow answer is not a loss). */
+    misses?: number;
+    /**
+     * What the caller's process registry knows is gone, checked before every read: a node's own process (by its
+     * `process` id) or the process that runs them all. Each entry is lost at once.
+     */
+    liveness?: (endpoints: readonly EngineNodeEndpoint[]) => readonly {
+        name: string;
+        reason: string;
+    }[];
+    fetch?: typeof fetch;
+}
+/** A running supervision: started once every node answered (`nodes`). */
+export interface EngineNodeSupervision {
+    readonly endpoints: readonly EngineNodeEndpoint[];
+    readonly nodes: readonly EngineNodeHealth[];
+    /** Rejects with EngineNodeLost when a node is lost, or with the abort reason once stopped. */
+    readonly completion: Promise<never>;
+    /** The loss, once there was one. */
+    readonly lost: EngineNodeLost | undefined;
+    /** Called once with the loss (at once when it already happened); returns the unsubscribe. */
+    onLost(listener: (error: EngineNodeLost) => void): () => void;
+    /** Stop checking and wait until no check is in progress. */
+    stop(): Promise<void>;
+}
+/**
+ * Supervise `endpoints` for the network's lifetime. Every node must answer first (otherwise it throws
+ * EngineNodeLost naming each that did not). Then every `intervalMs`: a node the registry reports gone and a node
+ * whose start time changed are lost at once, one that cannot be read `misses` times in a row is lost. The first
+ * loss ends the supervision; `stop()` ends it without one, after the check in progress has been cancelled.
+ */
+export declare function superviseEngineNodes(endpoints: readonly EngineNodeEndpoint[], options?: EngineNodeSupervisionOptions): Promise<EngineNodeSupervision>;
+/** Compatibility: supervise the nodes of zombie.json `spawnFile` until `signal` aborts (see superviseEngineNodes). */
+export declare function monitorEngineNodes(spawnFile: string, signal: AbortSignal, options?: Omit<EngineNodeSupervisionOptions, "signal">): Promise<EngineNodeSupervision>;