@parity/product-lab 0.0.1-placeholder → 0.1.1

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

@@ -0,0 +1,236 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { resolve } from "node:path";
+import { z } from "zod";
+import { NETWORK_CHAINS, TOPOLOGY_SERVICES, TopologyIssues, capabilityReasons, localEndpoints, orderedChains, sameChains, stateKind, topologyOffer, } from "@parity/product-lab/domain";
+import { topologyOptionsSchema } from "./topology-options-schema.js";
+export const ENGINE_KIND = "engine";
+export const DEFAULT_ENGINE_PORTS = {
+    people: 10010,
+    "asset-hub": 10020,
+    bulletin: 10030,
+    "web3-storage": 10040,
+    ethRpc: 8545,
+    identityBackend: 8092,
+    dashboard: 8090,
+};
+export const ENGINE_P2P_PORTS = {
+    people: 30336,
+    "asset-hub": 30335,
+    bulletin: 30333,
+    "web3-storage": 30337,
+};
+const engineSection = z
+    .strictObject({
+    extraArgs: z.array(z.string()).optional(),
+    toml: z.string().min(1).optional(),
+    env: z.record(z.string(), z.string()).optional(),
+});
+export const engineOptionsSchema = topologyOptionsSchema
+    .extend({
+    provider: z.literal(ENGINE_KIND).optional(),
+    relay: z.literal(true).default(true),
+    engine: engineSection.optional(),
+})
+    .strict();
+export function acceptsEngine(options) {
+    return options.relay !== false;
+}
+export const ENGINE_FLAGS = [
+    { name: "engine-arg", type: "string", multiple: true, value: "<arg>", description: "raw Engine argument (repeatable; recorded)" },
+    { name: "engine-env", type: "string", multiple: true, value: "<KEY=VALUE>", description: "Engine environment variable (repeatable; recorded, shown by key)" },
+    { name: "engine-toml", type: "string", value: "<file>", description: "zombienet TOML replacing the generated one" },
+];
+const list = (value) => (Array.isArray(value) ? [...value] : typeof value === "string" ? [value] : []);
+export function engineFlagOptions(values, options) {
+    const args = list(values["engine-arg"]);
+    const env = list(values["engine-env"]);
+    const toml = typeof values["engine-toml"] === "string" ? values["engine-toml"] : undefined;
+    if (!args.length && !env.length && !toml)
+        return options;
+    const engine = { ...(options.engine ?? {}) };
+    if (args.length)
+        engine.extraArgs = [...(engine.extraArgs ?? []), ...args];
+    for (const item of env) {
+        const index = item.indexOf("=");
+        if (index <= 0)
+            throw new Error(`--engine-env expects KEY=VALUE, got ${item}`);
+        engine.env = { ...(engine.env ?? {}), [item.slice(0, index)]: item.slice(index + 1) };
+    }
+    if (toml)
+        engine.toml = resolve(toml);
+    return { ...options, engine };
+}
+function resolveCapabilities(t) {
+    const hub = t.chains.includes("asset-hub");
+    return {
+        contracts: hub,
+        evm: hub && t.services.ethRpc,
+        dotns: hub,
+        bulletin: t.chains.includes("bulletin"),
+        statementStore: t.statementStore,
+        devAuthority: true,
+    };
+}
+export function resolveEngineTopology(options) {
+    const input = engineOptionsSchema.parse(options);
+    const { network } = input;
+    const declared = NETWORK_CHAINS[network];
+    const chains = orderedChains(input.chains ?? declared);
+    const has = (id) => chains.includes(id);
+    const resolvedState = input.state ?? { fork: "snapshot" };
+    const kind = stateKind(resolvedState);
+    const full = sameChains(chains, declared);
+    const profile = kind === "workspace" ? "workspace" : kind === "fork" ? (full ? "full-fork" : "fork-subset") : full ? "genesis" : "genesis-subset";
+    const defaultServices = { identityBackend: has("people"), ethRpc: has("asset-hub") };
+    const services = {
+        identityBackend: input.services?.identityBackend ?? defaultServices.identityBackend,
+        ethRpc: input.services?.ethRpc ?? defaultServices.ethRpc,
+    };
+    const statementStore = has("people") && (input.statementStore ?? true);
+    const runtimes = {};
+    for (const id of chains)
+        runtimes[id] = input.runtimes?.[id] ?? "locked";
+    const binaries = { ...(input.binaries ?? {}) };
+    const nodeArgs = {};
+    for (const [id, args] of Object.entries(input.nodeArgs ?? {}))
+        if (args.length)
+            nodeArgs[id] = args;
+    const genesis = { ...(input.genesisEdits ?? {}) };
+    const ports = {};
+    for (const id of chains)
+        ports[id] = input.ports?.[id] ?? DEFAULT_ENGINE_PORTS[id];
+    if (services.ethRpc)
+        ports.ethRpc = input.ports?.ethRpc ?? DEFAULT_ENGINE_PORTS.ethRpc;
+    if (services.identityBackend)
+        ports.identityBackend = input.ports?.identityBackend ?? DEFAULT_ENGINE_PORTS.identityBackend;
+    ports.dashboard = input.ports?.dashboard ?? DEFAULT_ENGINE_PORTS.dashboard;
+    const engine = input.engine
+        ? { extraArgs: input.engine.extraArgs ?? [], ...(input.engine.toml ? { toml: input.engine.toml } : {}), env: input.engine.env ?? {} }
+        : undefined;
+    const capabilities = resolveCapabilities({ chains, services, statementStore });
+    const endpoints = localEndpoints(chains, ports, (id) => ENGINE_P2P_PORTS[id]);
+    if (services.ethRpc)
+        endpoints.services.ethRpc = `http://127.0.0.1:${ports.ethRpc}`;
+    if (services.identityBackend)
+        endpoints.services.identityBackend = `http://127.0.0.1:${ports.identityBackend}/api/v1`;
+    const customizations = [];
+    const custom = (option, value, sensitive) => customizations.push({ option, value, ...(sensitive ? { sensitive } : {}) });
+    for (const [id, source] of Object.entries(runtimes))
+        if (source !== "locked")
+            custom(`runtimes.${id}`, source);
+    for (const [name, source] of Object.entries(input.binaries ?? {}))
+        if (source !== "locked")
+            custom(`binaries.${name}`, source);
+    for (const [id, args] of Object.entries(nodeArgs))
+        custom(`nodeArgs.${id}`, args);
+    if (input.blockTime !== undefined)
+        custom("blockTime", input.blockTime);
+    for (const [id, edits] of Object.entries(genesis))
+        custom(`genesisEdits.${id}`, edits);
+    if (has("people") && !statementStore)
+        custom("statementStore", false);
+    for (const name of ["identityBackend", "ethRpc"])
+        if (services[name] !== defaultServices[name])
+            custom(`services.${name}`, services[name]);
+    for (const [key, value] of Object.entries(input.ports ?? {}))
+        if (DEFAULT_ENGINE_PORTS[key] !== value)
+            custom(`ports.${key}`, value);
+    if (engine)
+        custom("engine", engine, Object.keys(engine.env).length > 0);
+    const issues = new TopologyIssues();
+    issues.chainsInNetwork(network, chains);
+    if (kind === "fork" && !full)
+        issues.error("fork-subset-unsupported", `Engine fork mode spawns every parachain of ${network} (${declared.join(", ")}); fork subsets need an Engine change (forkParachains requires an exact match)`);
+    if (kind === "fork" && typeof resolvedState.fork === "object")
+        issues.error("fork-block-unsupported", "Engine forks its published bundle or bites the live network now (--fresh-bite); a pinned fork block is not supported");
+    if (kind === "genesis" && network !== "previewnet")
+        issues.error("genesis-previewnet-only", `${network} is fork-only in Engine; genesis and genesis subsets exist only for previewnet`);
+    if (kind === "genesis" && !full)
+        issues.note("genesis-subset", `Engine genesis subset: ppn genesis-toml --parachains ${chains.join(",")}, then ppn start previewnet --toml`);
+    if (input.blockTime !== undefined)
+        issues.loss("block-time-relay", "blockTime applies only to the local dev chain (Omni Node); relay-backed block time is set by the relay and runtime (ignored)");
+    for (const id of Object.keys(nodeArgs))
+        issues.error("node-args-engine", `per-chain node arguments (${id}) are not passed to Engine; use engine.toml`);
+    for (const id of Object.keys(genesis))
+        issues.error("genesis-edits-engine", kind === "fork"
+            ? `genesis edits (${id}) do not apply to forked state; Engine applies its own fork overrides`
+            : `genesis edits (${id}) are not wired to Engine; use engine.toml or Engine's generate --profile`);
+    for (const [id, source] of Object.entries(runtimes))
+        if (source && typeof source === "object" && "spec" in source)
+            issues.error("runtime-spec-engine", `runtimes.${id} as { spec } is for the local dev chain (Omni Node) only; Engine takes { wasm } (--upgrade) or { release } (--runtime)`);
+        else if (kind === "fork" && source && typeof source === "object" && "release" in source)
+            issues.error("runtime-release-fork", `runtimes.${id} as { release } applies to genesis; forks take { wasm } through --upgrade`);
+        else if (kind === "genesis" && source && typeof source === "object" && "wasm" in source)
+            issues.error("runtime-wasm-genesis", `runtimes.${id} as { wasm } applies to forks (--upgrade); genesis takes { release } through --runtime`);
+    for (const [name, source] of Object.entries(binaries))
+        if (typeof source === "object" && "path" in source)
+            issues.error("binary-path-engine", `binaries.${name} as { path } is for the local dev chain (Omni Node) only; Engine takes { release } (--binary name=owner/repo@tag)`);
+    if (!statementStore && has("people"))
+        issues.loss("statement-store-engine", "Engine always runs People with --enable-statement-store; statementStore: false is recorded but not enforced");
+    if (engine?.toml)
+        issues.note("engine-toml", "engine.toml replaces the generated zombienet config: chains, ports and services come from that file");
+    issues.serviceChains(input, chains);
+    if (services.identityBackend && has("people") && !has("asset-hub"))
+        issues.loss("identity-backend-degraded", "Engine starts the identity backend with People, but its Asset Hub URL (DotNS gateway) is dead without asset-hub");
+    const hostable = ["people", "asset-hub", "bulletin"].every(has) && services.identityBackend;
+    if (!hostable)
+        issues.loss("no-host-routing", "hosted SPA runs need people, asset-hub, bulletin and the identity backend together (truAPI host local routing); this topology serves chain-level scenarios only");
+    if (has("people") && !has("asset-hub"))
+        issues.loss("no-fee-seed", "a People-only Engine network cannot fund fixtures: the fee seed arrives by XCM from Asset Hub");
+    issues.portConflicts(Object.entries(ports).map(([key, value]) => [value, key]));
+    return {
+        kind: "product-lab-topology",
+        schemaVersion: 1,
+        profile,
+        provider: ENGINE_KIND,
+        label: customizations.length ? "custom" : "standard",
+        network,
+        chains,
+        relay: true,
+        state: resolvedState,
+        runtimes,
+        binaries,
+        nodeArgs,
+        blockTime: {},
+        genesisEdits: genesis,
+        statementStore,
+        services,
+        ports,
+        ...(engine ? { engine } : {}),
+        capabilities,
+        capabilityReasons: capabilityReasons(capabilities, chains),
+        offer: topologyOffer(chains, [...(services.identityBackend ? [TOPOLOGY_SERVICES.identityBackend] : []), ...(services.ethRpc ? [TOPOLOGY_SERVICES.ethRpc] : [])], capabilities),
+        endpoints,
+        customizations,
+        issues: issues.list,
+        retention: "workspace" in resolvedState
+            ? { retention: "persistent", reason: `workspace ${resolvedState.workspace} keeps its chain databases when stopped and resumes on the next start` }
+            : { retention: "disposable", reason: "an owned Engine network without a workspace is deleted when it stops" },
+        presentation: {
+            relay: "yes",
+            binaries: "Engine-managed",
+            ...(engine ? { details: [{ label: "engine", value: JSON.stringify({ ...engine, env: Object.keys(engine.env) }) }] } : {}),
+        },
+        options: structuredClone(options),
+    };
+}
+export const engineProfiles = {
+    fullFork: (options = {}) => resolveEngineTopology({ state: { fork: "snapshot" }, ...options, relay: true }),
+    genesisSubset: (options) => resolveEngineTopology({ ...options, network: "previewnet", relay: true, state: { genesis: true } }),
+};
+export function engineProfileOptions(name, options) {
+    const { relay: _relay, state: _state, ...rest } = options;
+    switch (name) {
+        case "full-fork": {
+            const { chains: _chains, ...fork } = rest;
+            return { ...fork, relay: true, state: options.state ?? { fork: "snapshot" } };
+        }
+        case "genesis-subset": {
+            const { network: _network, ...subset } = rest;
+            return { ...subset, network: "previewnet", relay: true, state: { genesis: true }, chains: options.chains ?? ["people"] };
+        }
+        default:
+            throw new Error(`The Engine adapter has no profile ${name} (full-fork, genesis-subset)`);
+    }
+}

package/adapters/environment/engine/src/topology/topology-options-schema.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+/** The shared topology options, not strict: this adapter extends them with its own section and makes the result strict. */
+export declare const topologyOptionsSchema: z.ZodObject<{
+    provider: z.ZodOptional<z.ZodString>;
+    network: z.ZodDefault<z.ZodEnum<{
+        "paseo-next-v2": "paseo-next-v2";
+        previewnet: "previewnet";
+    }>>;
+    chains: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }>>>;
+    relay: z.ZodOptional<z.ZodBoolean>;
+    state: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        fork: z.ZodUnion<readonly [z.ZodLiteral<"snapshot">, z.ZodLiteral<"deployed">, z.ZodObject<{
+            block: z.ZodNumber;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodObject<{
+        genesis: z.ZodLiteral<true>;
+    }, z.core.$strict>, z.ZodObject<{
+        workspace: z.ZodString;
+    }, z.core.$strict>]>>;
+    runtimes: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodUnion<readonly [z.ZodLiteral<"locked">, z.ZodLiteral<"deployed">, z.ZodObject<{
+        wasm: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        spec: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        release: z.ZodString;
+    }, z.core.$strict>]>>>;
+    binaries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"locked">, z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        release: z.ZodString;
+    }, z.core.$strict>]>>>;
+    nodeArgs: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodArray<z.ZodString>>>;
+    blockTime: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodNumber>]>>;
+    genesisEdits: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+    }> & z.core.$partial, z.ZodObject<{
+        sudo: z.ZodOptional<z.ZodString>;
+        endow: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        patch: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        storage: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>>;
+    statementStore: z.ZodOptional<z.ZodBoolean>;
+    services: z.ZodOptional<z.ZodObject<{
+        identityBackend: z.ZodOptional<z.ZodBoolean>;
+        ethRpc: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    ports: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        bulletin: "bulletin";
+        people: "people";
+        "asset-hub": "asset-hub";
+        "web3-storage": "web3-storage";
+        ethRpc: "ethRpc";
+        identityBackend: "identityBackend";
+        dashboard: "dashboard";
+    }> & z.core.$partial, z.ZodNumber>>;
+}, z.core.$strip>;

package/adapters/environment/engine/src/topology/topology-options-schema.js

@@ -0,0 +1,57 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { z } from "zod";
+import { TOPOLOGY_CHAINS, TOPOLOGY_NETWORKS, TOPOLOGY_PORT_KEYS } from "@parity/product-lab/domain";
+const chain = z.enum(TOPOLOGY_CHAINS);
+const releaseRef = z.string().regex(/^[\w.-]+\/[\w.-]+@[\w.+-]+$/, "expected owner/repo@tag");
+const hex = z.string().regex(/^0x([\da-fA-F]{2})*$/, "expected 0x-prefixed hex");
+const state = z.union([
+    z
+        .strictObject({
+        fork: z.union([z.literal("snapshot"), z.literal("deployed"), z.strictObject({ block: z.number().int().nonnegative() })]),
+    }),
+    z.strictObject({ genesis: z.literal(true) }),
+    z
+        .strictObject({
+        workspace: z
+            .string()
+            .regex(/^[\w.-]{1,64}$/)
+            .refine((name) => name !== "." && name !== "..", "a workspace name, not . or .."),
+    }),
+]);
+const runtime = z.union([
+    z.literal("locked"),
+    z.literal("deployed"),
+    z.strictObject({ wasm: z.string().min(1) }),
+    z.strictObject({ spec: z.string().min(1) }),
+    z.strictObject({ release: releaseRef }),
+]);
+const binary = z.union([
+    z.literal("locked"),
+    z.strictObject({ path: z.string().min(1) }),
+    z.strictObject({ release: releaseRef }),
+]);
+const genesisEdits = z
+    .strictObject({
+    sudo: z.string().min(1).optional(),
+    endow: z.record(z.string(), z.string().regex(/^\d+$/)).optional(),
+    patch: z.record(z.string(), z.unknown()).optional(),
+    storage: z.record(hex, hex, { error: (issue) => (issue.code === "invalid_key" ? "expected 0x-prefixed hex" : undefined) }).optional(),
+});
+const port = z.number().int().min(1024).max(65535);
+const blockTimeMs = z.number().int().min(100).max(60_000);
+export const topologyOptionsSchema = z.object({
+    provider: z.string().min(1).optional(),
+    network: z.enum(TOPOLOGY_NETWORKS).default("paseo-next-v2"),
+    chains: z.array(chain).min(1).optional(),
+    relay: z.boolean().optional(),
+    state: state.optional(),
+    runtimes: z.partialRecord(chain, runtime).optional(),
+    binaries: z.record(z.string().regex(/^[\w.-]+$/), binary).optional(),
+    nodeArgs: z.partialRecord(chain, z.array(z.string().min(1))).optional(),
+    blockTime: z.union([blockTimeMs, z.partialRecord(chain, blockTimeMs)]).optional(),
+    genesisEdits: z.partialRecord(chain, genesisEdits).optional(),
+    statementStore: z.boolean().optional(),
+    services: z.strictObject({ identityBackend: z.boolean().optional(), ethRpc: z.boolean().optional() }).optional(),
+    ports: z.partialRecord(z.enum(TOPOLOGY_PORT_KEYS), port).optional(),
+});

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

@@ -0,0 +1,90 @@
+import type { ForkSnapshot } from "@parity/product-lab/domain";
+import { type NotApplicableComponent, VersionResolution, type ResolvedRuntime } from "@parity/product-lab/domain/versions";
+import type { RuntimeDependency } from "../session/runtime-dependency.js";
+import { type EngineSession } from "../session/session.js";
+import type { EngineTopology } from "../topology/engine-topology.js";
+/** A `deployed` resolution accepts a published fork bundle bitten at most this long ago (24 h), when it runs the same runtimes. */
+export declare const DEFAULT_MAX_SNAPSHOT_AGE_MS: number;
+export interface EngineVersionPlan {
+    /** Runtimes the fork must run: checked after start and after every reset. */
+    runtimes: readonly ResolvedRuntime[];
+    notApplicable: readonly NotApplicableComponent[];
+    /** Non-empty: the run must not start. */
+    refusals: readonly string[];
+    notes: readonly string[];
+}
+export interface EngineVersionPlanOptions {
+    /** The fork bundle Engine would start from (`state: { fork: "snapshot" }` with a bundle present). */
+    snapshot?: ForkSnapshot;
+    now: Date;
+    /** For `deployed` runtimes on a published bundle; default DEFAULT_MAX_SNAPSHOT_AGE_MS. */
+    maxSnapshotAgeMs?: number;
+}
+/** What Engine will do with `resolution` for topology `t`, decided before anything starts. Pure. */
+export declare function engineVersionPlan(t: EngineTopology, resolution: VersionResolution, options: EngineVersionPlanOptions): EngineVersionPlan;
+/**
+ * The plan for a persistent Engine network (`persistentNetwork`): its chains
+ * are Engine's session chains, created once from a fork or a Previewnet
+ * genesis. Runtimes read from the network are checked by code hash when it is
+ * created; anything else is refused as above.
+ */
+export declare function workspaceVersionPlan(resolution: VersionResolution, network: string, mode: "fork" | "genesis"): EngineVersionPlan;
+/** One resolved runtime against the running fork, as recorded in the run manifest and provenance. */
+export interface EngineRuntimeRow {
+    id: string;
+    chain: string;
+    selector: string;
+    version: string;
+    resolved: ReturnType<ResolvedRuntime["toJSON"]>;
+    observed?: {
+        codeHash: string;
+        genesis: string;
+        spec: string;
+        finalized: number;
+    };
+    /** The block Engine bit this chain at (its bundle's `biteBlocks`), when known. */
+    forkBlock?: number;
+    sameGenesis?: boolean;
+    ok: boolean;
+    problems: string[];
+}
+export interface EngineVersionCheck {
+    ok: boolean;
+    runtimes: EngineRuntimeRow[];
+    problems: string[];
+}
+/** Compare the started fork (its session's observations) with the plan's runtimes. Pure. */
+export declare function engineVersionCheck(session: EngineSession, plan: EngineVersionPlan, snapshot?: ForkSnapshot): EngineVersionCheck;
+/** What a run manifest and the provenance record about versions: the run's resolution, each runtime against the fork, what did not apply and why, and what Engine could not pin. */
+export declare function engineVersionsRecord(resolution: VersionResolution, plan: EngineVersionPlan, check?: EngineVersionCheck): {
+    resolution: import("@parity/product-lab/domain").VersionResolutionData;
+    runtimes: EngineRuntimeRow[];
+    notApplicable: readonly NotApplicableComponent[];
+    notes: readonly string[];
+};
+/** Thrown when a started fork does not run the resolved runtimes; the network was stopped first. */
+export declare class EngineVersionMismatch extends Error {
+    readonly check: EngineVersionCheck;
+    constructor(check: EngineVersionCheck);
+}
+/**
+ * An Engine dependency held to a version plan: every start and every reset
+ * (a new network, a new generation) is checked against the resolved
+ * runtimes; a mismatch stops what was started and refuses.
+ */
+export declare class VersionedEngineDependency implements RuntimeDependency<EngineSession> {
+    private readonly inner;
+    readonly plan: EngineVersionPlan;
+    /** The fork bundle after start (a `--fresh-bite` start rewrites it). */
+    private readonly snapshot;
+    /** The check of the current (or last) start or reset. */
+    check?: EngineVersionCheck;
+    constructor(inner: RuntimeDependency<EngineSession>, plan: EngineVersionPlan, 
+    /** The fork bundle after start (a `--fresh-bite` start rewrites it). */
+    snapshot?: () => ForkSnapshot | undefined);
+    get isolation(): "shared-attached" | "fresh-network-per-scenario";
+    start(signal?: AbortSignal): Promise<EngineSession>;
+    reset(signal?: AbortSignal): Promise<EngineSession>;
+    stop(): Promise<void>;
+    private verified;
+}

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

@@ -0,0 +1,138 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { EnvironmentVersions, SnapshotFreshness, VersionResolution, } from "@parity/product-lab/domain/versions";
+import { CHAIN_IDS } from "../session/session.js";
+export const DEFAULT_MAX_SNAPSHOT_AGE_MS = 24 * 60 * 60 * 1000;
+export function engineVersionPlan(t, resolution, options) {
+    const split = EnvironmentVersions.split({ resolution, chains: t.chains, network: t.network, adapter: "Engine" });
+    const refusals = [...split.refusals];
+    const notes = [];
+    const state = t.state;
+    for (const runtime of split.runtimes) {
+        const override = t.runtimes[runtime.chain];
+        if (override && typeof override === "object")
+            refusals.push(`${runtime.id}: the topology replaces ${runtime.chain}'s runtime (runtimes.${runtime.chain} ${JSON.stringify(override)}); a resolved runtime and an override cannot both hold`);
+        else if (!runtime.fromNetwork)
+            refusals.push(`${runtime.id} ${runtime.version} comes from a ${runtime.source.type} source; Engine runs the forked network's own runtimes or its descriptor's release, so it cannot apply it (unsupported). Declare runtimes.${runtime.chain}: { wasm } (fork) or { release } (genesis) instead`);
+        else if (!("fork" in state))
+            refusals.push(`${runtime.id} was read from ${runtime.network} at #${runtime.block.number}; ${"genesis" in state ? "an Engine genesis" : "a resumed workspace"} does not run that network's runtime and state. Use state { fork: "deployed" }`);
+    }
+    if ("fork" in state && split.runtimes.length) {
+        const blocks = split.runtimes.map((runtime) => `${runtime.chain} #${runtime.block?.number ?? "?"}`).join(", ");
+        if (state.fork === "deployed")
+            notes.push(`Engine bites ${t.network} now and cannot pin the resolved blocks (${blocks}): the bite lands at the live head; each chain's code hash is compared with the resolution after start`);
+        else if (state.fork === "snapshot") {
+            const snapshot = options.snapshot;
+            if (!snapshot)
+                notes.push(`Engine fetches its published bundle at start; its runtimes are compared with the resolution (${blocks}) after start`);
+            else {
+                const deployed = split.runtimes.filter((runtime) => runtime.selector.kind === "deployed");
+                if (deployed.length) {
+                    const ids = new Set(deployed.map((runtime) => runtime.id.toString()));
+                    const own = VersionResolution.create({ resolvedAt: resolution.resolvedAt, components: resolution.components().filter((entry) => ids.has(entry.id.toString())) });
+                    const { reasons } = SnapshotFreshness.check({ snapshot, deployed: own, now: options.now, maxAgeMs: options.maxSnapshotAgeMs ?? DEFAULT_MAX_SNAPSHOT_AGE_MS });
+                    if (reasons.length)
+                        refusals.push(`The fork bundle (bitten ${snapshot.bittenAt}) does not represent the deployed resolution: ${reasons.join("; ")}. Use state { fork: "deployed" } to bite the live network now`);
+                }
+                for (const runtime of split.runtimes.filter((entry) => entry.selector.kind !== "deployed")) {
+                    const forked = snapshot.runtimes?.[runtime.chain];
+                    if (runtime.spec && forked !== undefined && forked !== runtime.spec)
+                        refusals.push(`The fork bundle runs ${runtime.chain} ${forked}; the resolution (${runtime.selector}) has ${runtime.spec}`);
+                }
+                notes.push(`Engine starts from its published bundle (bitten ${snapshot.bittenAt}), not the resolved blocks (${blocks}); code hashes are compared after start`);
+            }
+        }
+    }
+    return { runtimes: split.runtimes, notApplicable: split.notApplicable, refusals, notes };
+}
+export function workspaceVersionPlan(resolution, network, mode) {
+    const split = EnvironmentVersions.split({ resolution, chains: [...CHAIN_IDS], network, adapter: "Engine" });
+    const refusals = [...split.refusals];
+    for (const runtime of split.runtimes)
+        if (!runtime.fromNetwork)
+            refusals.push(`${runtime.id} ${runtime.version} comes from a ${runtime.source.type} source; Engine cannot apply it (unsupported)`);
+        else if (mode === "genesis")
+            refusals.push(`${runtime.id} was read from ${runtime.network}; an Engine genesis does not run that network's runtime and state`);
+    return { runtimes: split.runtimes, notApplicable: split.notApplicable, refusals, notes: [] };
+}
+export function engineVersionCheck(session, plan, snapshot) {
+    const runtimes = plan.runtimes.map((runtime) => {
+        const base = { id: runtime.id.toString(), chain: runtime.chain, selector: runtime.selector.toString(), version: runtime.version, resolved: runtime.toJSON() };
+        const forkBlock = snapshot?.blocks[runtime.chain];
+        const observed = session.chains[runtime.chain];
+        if (!observed)
+            return {
+                ...base,
+                ...(forkBlock !== undefined ? { forkBlock } : {}),
+                ok: false,
+                problems: [`${runtime.chain} is not observed by the Engine session (people, asset-hub, bulletin), so its code cannot be compared`],
+            };
+        const comparison = runtime.compare({
+            codeHash: observed.codeHash,
+            specName: observed.runtime.specName,
+            specVersion: observed.runtime.specVersion,
+            genesis: observed.genesis,
+        });
+        return {
+            ...base,
+            observed: {
+                codeHash: observed.codeHash,
+                genesis: observed.genesis,
+                spec: `${observed.runtime.specName} ${observed.runtime.specVersion}`,
+                finalized: Number(observed.finalized.number),
+            },
+            ...(forkBlock !== undefined ? { forkBlock } : {}),
+            ...(comparison.genesis.same !== undefined ? { sameGenesis: comparison.genesis.same } : {}),
+            ok: comparison.ok,
+            problems: [...comparison.problems],
+        };
+    });
+    const problems = runtimes.flatMap((row) => row.problems);
+    return { ok: problems.length === 0, runtimes, problems };
+}
+export function engineVersionsRecord(resolution, plan, check) {
+    return { resolution: resolution.toJSON(), runtimes: check?.runtimes ?? [], notApplicable: plan.notApplicable, notes: plan.notes };
+}
+export class EngineVersionMismatch extends Error {
+    check;
+    constructor(check) {
+        super(`The Engine fork does not run the resolved runtimes, so it was stopped: ${check.problems.join("; ")}`);
+        this.check = check;
+        this.name = "EngineVersionMismatch";
+    }
+}
+export class VersionedEngineDependency {
+    inner;
+    plan;
+    snapshot;
+    check;
+    constructor(inner, plan, 
+    snapshot = () => undefined) {
+        this.inner = inner;
+        this.plan = plan;
+        this.snapshot = snapshot;
+        if (plan.refusals.length)
+            throw new Error(`Engine cannot honour this version resolution:\n${plan.refusals.map((item) => `- ${item}`).join("\n")}`);
+    }
+    get isolation() {
+        return this.inner.isolation;
+    }
+    async start(signal) {
+        return this.verified(await this.inner.start(signal));
+    }
+    async reset(signal) {
+        return this.verified(await this.inner.reset(signal));
+    }
+    stop() {
+        return this.inner.stop();
+    }
+    async verified(session) {
+        const check = engineVersionCheck(session, this.plan, this.snapshot());
+        this.check = check;
+        if (!check.ok) {
+            await this.inner.stop();
+            throw new EngineVersionMismatch(check);
+        }
+        return session;
+    }
+}