@parity/product-lab 0.1.2 → 0.3.0

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

@@ -231,7 +231,7 @@ export function savedForkEnvironment(fork, settings) {
                     dashboard: `http://127.0.0.1:${ports.DASHBOARD_PORT}`, extraPath: engine.extraPath,
                     startupTimeoutMs: SAVED_FORK_STARTUP_MS, ports, nodePorts: { from: block.base + 900, to: block.base + 949 },
                     template: true, isolate: true, expose: false, ...(fork.topology ? { forkTopology: fork.topology } : {}),
-                    ...(recordedPatch(prepared.build) === "none" ? { enginePatch: "none" } : {}),
+                    enginePatch: recordedPatch(prepared.build),
                     ...(settings.txpoolLog ? { txpoolLog: settings.txpoolLog } : {}), ...(settings.bulletinAuthoring ? { bulletinAuthoring: settings.bulletinAuthoring } : {}),
                     seed: networkSeedDirectory(settings.seedsDir, { network: NETWORK, checkout: engine.checkout, ...(fork.topology ? { topology: fork.topology } : {}) }),
                 });

package/adapters/environment/engine/src/setup/engine-build.d.ts

@@ -3,11 +3,11 @@ import type { SyncCommandRunner } from "@parity/product-lab/ports/system";
 export declare const NODE_VERIFIER_OPTION = "--node-verifier";
 export type NodeVerifier = "metric" | "none";
 export declare function nodeVerifierArgs(verifier: NodeVerifier | undefined): string[];
-/** The old value is recognized only to refuse stale configurations with a repair command. */
-export declare const ENGINE_PATCHES: readonly ["owned-processes", "none"];
+/** Stock and the optional shipped fix (node-workspace); owned-processes is recognized only to refuse stale configurations. */
+export declare const ENGINE_PATCHES: readonly ["owned-processes", "none", "node-workspace"];
 export type EnginePatch = (typeof ENGINE_PATCHES)[number];
 export declare const ENGINE_PATCH_RETIRED = "the owned-processes Engine patch is retired; prepare stock Engine v0.11.0 instead";
 /** The build must exist. The prepared checkout's pin and record are checked by preparedEngine. */
-export declare function engineBuildIssue(checkout: string, _commands: SyncCommandRunner, patch?: EnginePatch): string | undefined;
-/** Before every start, refuse retired patched configurations and incomplete builds. */
+export declare function engineBuildIssue(checkout: string, commands: SyncCommandRunner, patch?: EnginePatch): string | undefined;
+/** Before every start, verify the optional patch and refuse retired configurations and incomplete builds. */
 export declare function requireEngineBuild(checkout: string, commands: SyncCommandRunner, patch?: EnginePatch): void;

package/adapters/environment/engine/src/setup/engine-build.js

@@ -2,19 +2,29 @@
 // SPDX-License-Identifier: Apache-2.0
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { shippedEnginePatch } from "./patches.js";
+import { NODE_WORKSPACE_PATCH } from "./patch-catalogue.js";
 import { engineSetupCommand } from "./setup-command.js";
 export const NODE_VERIFIER_OPTION = "--node-verifier";
 export function nodeVerifierArgs(verifier) {
     return verifier ? [NODE_VERIFIER_OPTION, verifier] : [];
 }
-export const ENGINE_PATCHES = ["owned-processes", "none"];
+export const ENGINE_PATCHES = ["owned-processes", "none", "node-workspace"];
 export const ENGINE_PATCH_RETIRED = "the owned-processes Engine patch is retired; prepare stock Engine v0.11.0 instead";
-export function engineBuildIssue(checkout, _commands, patch = "none") {
-    if (patch !== "none")
+export function engineBuildIssue(checkout, commands, patch = "none") {
+    if (patch !== "none" && patch !== "node-workspace")
         return ENGINE_PATCH_RETIRED;
+    if (patch === "node-workspace") {
+        const resolved = shippedEnginePatch(patch);
+        if (resolved.sha256 !== NODE_WORKSPACE_PATCH.sha256 || resolved.base !== NODE_WORKSPACE_PATCH.base)
+            return "node-workspace patch differs from its tested catalogue";
+        const check = commands.run({ command: "git", args: ["apply", "--reverse", "--check", resolved.path], cwd: checkout, timeoutMs: 30_000 });
+        if (check.code !== 0)
+            return "node-workspace patch is missing or changed in the Engine checkout";
+    }
     for (const file of ["packages/cli/dist/commands/start.js", "packages/cli/dist/cli.js"])
         if (!existsSync(join(checkout, file)))
-            return `the stock Engine checkout at ${checkout} is not built (no ${file})`;
+            return `the ${patch === "none" ? "stock" : "patched"} Engine checkout at ${checkout} is not built (no ${file})`;
     return undefined;
 }
 export function requireEngineBuild(checkout, commands, patch = "none") {

package/adapters/environment/engine/src/setup/engine-tooling.d.ts

@@ -0,0 +1,33 @@
+import type { EnvironmentTooling } from "@parity/product-lab/ports/environment";
+import type { SyncCommandRunner } from "@parity/product-lab/ports/system";
+import type { EnginePatch } from "./engine-build.js";
+import { type PreparedEngine, type PreparedEnginePatch } from "./prepare-engine.js";
+/** What an Engine checkout tooling prepares, and where. */
+export interface EngineCheckoutSettings {
+    /** The state directory it is prepared in (engine-build.json, engine.json and `tooling/<key>/`): its own. */
+    readonly state: string;
+    /** Engine's network whose binaries its fetch downloads. */
+    readonly network: "previewnet" | "paseo-next-v2";
+    /** The build an environment starts from: stock (`none`) or with the shipped node-workspace patch. */
+    readonly patch: Exclude<EnginePatch, "owned-processes">;
+    /** The lab's id of the environment that starts from it, for the command that prepares it. */
+    readonly environment: string;
+    /** The command that prepares it, as messages name it. Default: `engineFetchCommand(environment)`. */
+    readonly setupCommand?: string;
+}
+/**
+ * The command that prepares an environment's own tooling: `product-lab fetch --environment <id>`, through the checkout's
+ * CLI script there (`bun run setup` prepares only the copies' stock Engine), through npx in a product.
+ */
+export declare function engineFetchCommand(environment: string, checkout?: boolean): string;
+/**
+ * The prepared checkout in `settings.state`, as `patch` names it (default `settings.patch`), or `EngineNotPrepared`
+ * naming the fix. `ref`: also check that commit (default the tested release; `as-prepared` takes the recorded one).
+ */
+export declare function preparedEngineCheckout(settings: EngineCheckoutSettings, commands: SyncCommandRunner, patch?: PreparedEnginePatch, ref?: string): PreparedEngine;
+/**
+ * The Engine checkout `settings` names, as an environment's tooling: always the build `settings.patch` names, which is
+ * the one its environment starts from (`preparedEngineCheckout(settings, commands, settings.patch)`). Another repository
+ * or ref may be asked for; another build may not (`--no-engine-patch` for a patched one is refused, naming why).
+ */
+export declare function engineCheckoutTooling(settings: EngineCheckoutSettings): EnvironmentTooling;

package/adapters/environment/engine/src/setup/engine-tooling.js

@@ -0,0 +1,59 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { defaultEngineRepository, EngineNotPrepared, prepareEngine, preparedEngine, testedEngineRef } from "./prepare-engine.js";
+import { engineBuildWords } from "../saved-fork/saved-fork-tooling.js";
+import { insideProductLabCheckout } from "./setup-command.js";
+export function engineFetchCommand(environment, checkout = insideProductLabCheckout()) {
+    return checkout ? `bun run product-lab fetch --config <lab.config.ts> --environment ${environment}` : `npx --no-install product-lab fetch --environment ${environment}`;
+}
+const fixOf = (settings) => settings.setupCommand ?? engineFetchCommand(settings.environment);
+export function preparedEngineCheckout(settings, commands, patch = settings.patch, ref) {
+    return preparedEngine(settings.state, { stateDirectory: ".", fix: fixOf(settings), commands, patch, ...(ref ? { ref } : {}) });
+}
+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 engineCheckoutTooling(settings) {
+    const status = (commands, patch, ref) => {
+        try {
+            return { ready: true, detail: engineBuildWords(preparedEngineCheckout(settings, commands, patch, ref)) };
+        }
+        catch (error) {
+            if (!(error instanceof EngineNotPrepared))
+                throw error;
+            return { ready: false, detail: error.reason, fix: fixOf(settings) };
+        }
+    };
+    return {
+        id: `engine:${settings.state}`,
+        kind: "engine",
+        label: `Engine checkout${settings.patch === "none" ? "" : ` (${settings.patch} patch)`}`,
+        check: (system) => status(syncCommands(system), settings.patch),
+        async prepare(request) {
+            const commands = syncCommands(request.system);
+            const source = request.source ?? {};
+            const patch = settings.patch;
+            if (source.patched === false && patch !== "none")
+                throw new Error(`The ${settings.environment} environment starts from Engine with the ${patch} patch, so it cannot be prepared without it (--no-engine-patch)`);
+            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)" : `with the ${patch} patch`}, into ${settings.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(settings.state, ref, settings.network, commands, ".", { platform: process.platform, ...(homebrewPrefix ? { homebrewPrefix } : {}) }, {
+                ...(source.repository ? { repository: source.repository } : {}),
+                patch,
+                ...(request.output ? { output: request.output } : {}),
+            });
+            const after = status(commands, patch, pinned ? ref : undefined);
+            return { ...after, prepared: after.ready };
+        },
+    };
+}

package/adapters/environment/engine/src/setup/node-workspace.patch

@@ -0,0 +1,403 @@
+diff --git a/packages/cli/src/lib/spawn-env.ts b/packages/cli/src/lib/spawn-env.ts
+index 90205fb..ae56253 100644
+--- a/packages/cli/src/lib/spawn-env.ts
++++ b/packages/cli/src/lib/spawn-env.ts
+@@ -1,169 +1,178 @@
+ // The spawn environment `ppn start` states, in one place.
+ //
+ // zombienet forwards no environment to custom processes, so everything the dashboard,
+ // eth-rpc, the dub stack and the storage provider cannot derive has to be *stated*.
+ // `ppn start` states it three times: config/ports.local.env (read by custom processes),
+ // zombie-cli's child environment (which the configs' {{BIN}} and {{SCRIPTS}} are filled from),
+ // and each custom process's own `env` in the config it spawns (customProcessEnv), the only
+ // environment zombie-cli hands them. A deployment that spawns zombie-cli directly never runs
+ // `ppn start`, so it has to restate the same facts itself.
+ //
+ // This module is the canonical statement, and the contract a deployment implements: it is
+ // exported as `@parity/ppn/spawn-env` so the restating side can assert against the key lists
+ // rather than keeping its own copy in step by hand.
+ 
+ import path from 'node:path';
+ 
+ /** Facts config/ports.local.env states for zombienet's custom processes. */
+ export interface LocalEnvFacts {
+   /** The network this run resolved to, so every service resolves the same one. */
+   network: string;
+   /** The data dir this run writes to — per-mode (data/ vs data-fork/). */
+   dataDir: string;
+   ephemeral: boolean;
+   /** Where the identity postgres cluster keeps its data. */
+   identityDataDir: string;
+ }
+ 
+ /** The gitignored file `ppn start` writes; every service overlays it on top of ports.env. */
+ export function localEnvContent(f: LocalEnvFacts): string {
+   return (
+     '# Generated by `ppn start` — gitignored, do not edit.\n' +
+     `WEB3_STORAGE_PROVIDER_STORAGE_MODE=${f.ephemeral ? 'inmemory' : 'disk'}\n` +
+     `DUB_POSTGRES_DATA_DIR=${f.identityDataDir}\n` +
+     `PPN_NETWORK=${f.network}\n` +
+     // An ephemeral run keeps its chains in a temp dir, so PPN_DATA_DIR below holds an earlier
+     // run's files, which the services that read the data dir must not take for this one's.
+     `PPN_EPHEMERAL=${f.ephemeral ? '1' : '0'}\n` +
+     // zombienet forwards no env to custom processes, and the data dir is per-mode
+     // (data/ vs data-fork/): without this the dashboard reads the *other* mode's
+     // spawn stamp and logs — a fork reporting itself as yesterday's genesis.
+     `PPN_DATA_DIR=${f.dataDir}\n`
+   );
+ }
+ 
+ /** Facts `ppn start` puts into zombie-cli's environment (inherited by node-level procs). */
+ export interface ChildEnvFacts {
+   binDir: string;
+   /** The workspace this run resolved to, so the launchers do not resolve it again. */
+   workspace: string;
+   scriptsDir: string;
+   dataDir: string;
+   ephemeral: boolean;
+ }
+ 
+ export function childEnv(f: ChildEnvFacts): Record<string, string> {
+   return {
+     BIN: f.binDir,
+     // zombienet forwards node-level env but gives custom processes no HOME, which is the
+     // one thing the shell fallback would need — so the resolved workspace travels here.
+     PPN_HOME: f.workspace,
+     SCRIPTS: f.scriptsDir,
+     DATA_DIR: f.dataDir,
+     EPHEMERAL: f.ephemeral ? '1' : '',
+   };
+ }
+ 
+ /**
+  * Facts every custom process is handed in its own `env` (custom-process-env): zombie-cli starts
+  * nodes and custom processes with an empty environment but TZ, LANG, PATH and what the TOML
+  * gives each one, so neither zombie-cli's environment (childEnv) nor the shell's reaches them.
+  * Without PPN_HOME a launcher falls back to the checkout it sits in, or ~/.ppn
+  * (scripts/lib/workspace.sh), and reads that workspace's ports.local.env, binaries and data
+  * instead of this run's.
+  */
+ export function customProcessEnv(f: { workspace: string; network: string; dataDir: string }): Record<string, string> {
+   return { PPN_HOME: f.workspace, PPN_NETWORK: f.network, PPN_DATA_DIR: f.dataDir };
+ }
+ 
+ const SECTION = /^\s*\[\[?\s*([\w.-]+)\s*\]\]?\s*(#.*)?$/;
+ 
+ /**
+  * `toml` with `env` added to every `[[custom_processes]]` block, before any entry the block
+  * already has; an entry the block names itself is kept, not repeated. Other sections are left
+  * alone. Line-based, for the configs this repository generates and any hand-written one in the
+  * same shape: one key per line, `env = [` opening its array on the key's own line.
+  */
+ export function withCustomProcessEnv(toml: string, env: Record<string, string>): string {
++  return withProcessEnv(toml, env, ['custom_processes']);
++}
++
++/** Node processes also start with a stripped environment; preserve each node's explicit overrides. */
++export function withNodeProcessEnv(toml: string, env: Record<string, string>): string {
++  return withProcessEnv(toml, env, ['relaychain.nodes', 'parachains.collators']);
++}
++
++function withProcessEnv(toml: string, env: Record<string, string>, sections: string[]): string {
+   const lines = toml.split('\n');
+   const out: string[] = [];
+   const entry = (name: string, value: string) => `{ name = ${JSON.stringify(name)}, value = ${JSON.stringify(value)} }`;
+   let i = 0;
+   while (i < lines.length) {
+     const header = SECTION.exec(lines[i]);
+     out.push(lines[i++]);
+-    if (!header || header[1] !== 'custom_processes' || !lines[i - 1].trim().startsWith('[[')) continue;
++    if (!header || !sections.includes(header[1]) || !lines[i - 1].trim().startsWith('[[')) continue;
+     // The block runs to the next section header.
+     const start = i;
+     while (i < lines.length && !SECTION.test(lines[i])) i++;
+     const block = lines.slice(start, i);
+     const named = new Set([...block.join('\n').matchAll(/\{\s*name\s*=\s*"([^"]+)"/g)].map((m) => m[1]));
+     const missing = Object.entries(env).filter(([name]) => !named.has(name)).map(([n, v]) => entry(n, v));
+     const at = block.findIndex((line) => /^\s*env\s*=\s*\[/.test(line));
+     if (missing.length === 0) {
+       out.push(...block);
+     } else if (at === -1) {
+-      // No env yet: after the block's last key, before the blank lines that separate it.
++      // No env yet: after the last key, before trailing comments for the next section.
+       let last = block.length;
+-      while (last > 0 && block[last - 1].trim() === '') last--;
++      while (last > 0 && /^\s*(?:#.*)?$/.test(block[last - 1])) last--;
+       out.push(...block.slice(0, last), `env = [${missing.join(', ')}]`, ...block.slice(last));
+     } else {
+       const open = block[at].indexOf('[') + 1;
+       const rest = block[at].slice(open).trim();
+       if (rest === '') {
+         // Multi-line array: one entry per line, as the generators write them.
+         out.push(...block.slice(0, at + 1), ...missing.map((e) => `  ${e},`), ...block.slice(at + 1));
+       } else {
+         const joined = rest.startsWith(']') ? missing.join(', ') : `${missing.join(', ')}, `;
+         out.push(...block.slice(0, at), `${block[at].slice(0, open)}${joined}${rest}`, ...block.slice(at + 1));
+       }
+     }
+   }
+   return out.join('\n');
+ }
+ 
+ /** Where `ppn start` writes the config it spawns: beside the one it was made from, so relative paths still resolve. */
+ export function spawnTomlFor(source: string): string {
+   return path.join(path.dirname(source), `${path.basename(source, '.toml')}.spawn.toml`);
+ }
+ 
+ const DUMMY_LOCAL: LocalEnvFacts = { network: 'x', dataDir: 'x', ephemeral: false, identityDataDir: 'x' };
+ const DUMMY_CHILD: ChildEnvFacts = { binDir: 'x', workspace: 'x', scriptsDir: 'x', dataDir: 'x', ephemeral: false };
+ 
+ /** Keys `ppn start` writes into config/ports.local.env, derived from the real writer. */
+ export function localEnvKeys(): string[] {
+   return [...localEnvContent(DUMMY_LOCAL).matchAll(/^([A-Z_][A-Z0-9_]*)=/gm)].map((m) => m[1]);
+ }
+ 
+ /** Keys `ppn start` puts into zombie-cli's environment, derived from the real builder. */
+ export function childEnvKeys(): string[] {
+   return Object.keys(childEnv(DUMMY_CHILD));
+ }
+ 
+ /** Every key a spawn receives through `ppn start`, deduplicated. */
+ export function spawnEnvKeys(): string[] {
+   return [...new Set([...localEnvKeys(), ...childEnvKeys()])];
+ }
+ 
+ /**
+  * Keys the server path deliberately does not supply. Each needs a reason, and the reason has
+  * to be about the *server*, not about effort.
+  */
+ export const WAIVED: Record<string, string> = {
+   // A server persists by definition; ephemeral is a laptop mode. Nothing reads it there.
+   EPHEMERAL: 'ephemeral is a local-only mode; a deployment always persists',
+ 
+   // KNOWN GAP, deliberately recorded rather than silently waived.
+   //
+   // `ppn start` sets it so every service resolves the network the user asked for.
+   // On a server nothing sets it, and currentNetworkName() (network-config/src/networks.ts)
+   // falls back to previewnet. Staging and prod run previewnet, so this is *accidentally*
+   // correct today and breaks nothing — but the first non-previewnet deployment would have
+   // every service resolve previewnet's chains, ports and bin directory instead.
+   //
+   // Not fixed here because the fix belongs with `ppn start --server` (see docs/DASHBOARD.md,
+   // "Why a server does not run `ppn start`"), which makes one path the sole author of all of
+   // this. Until then it is written down, and the conformance test keeps it from being
+   // forgotten.
+   PPN_NETWORK: 'KNOWN GAP: falls back to previewnet, which is what servers run today',
+ };
+diff --git a/scripts/lib/workspace.sh b/scripts/lib/workspace.sh
+index acb15c9..2ae2002 100755
+--- a/scripts/lib/workspace.sh
++++ b/scripts/lib/workspace.sh
+@@ -1,47 +1,67 @@
+ #!/usr/bin/env bash
+ # Where the workspace is — the one rule, shared by every launcher. Mirrors workspaceRoot()
+ # in @parity/ppn-network-config: $PPN_HOME, else the nearest ancestor of the cwd with
+ # networks/, else a checkout this script sits in, else the per-user home. In a checkout all
+ # of these agree; installed from npm the script lives in node_modules, whose bin/ does not
+ # exist — five launchers each grew their own partial copy of this logic and each broke a
+ # different way, which is why it now lives here once.
+ #
+ # zombienet runs custom processes with a stripped environment (no HOME), so the last resort
+ # derives the home from the owner of this file — the user whose `ppn fetch` filled ~/.ppn.
+ #
+ # Usage:  source "$(dirname "${BASH_SOURCE[0]}")/lib/workspace.sh"   (adjust depth)
+ # Sets:   PPN_WS       the workspace root
+ #         PPN_WS_BIN   its bin/ (callers append /<network> for non-previewnet binaries)
+ 
+ ppn_workspace_root() {
+     if [[ -n "${PPN_HOME:-}" ]]; then
+         echo "$PPN_HOME"; return
+     fi
++    # A native node can be launched outside `ppn start` with no environment at all.
++    # zombienet's absolute base path is <workspace>/{data,data-fork}/<node>/data.
++    # Only callers explicitly passing node args use this fallback; stop at the relay-side `--`.
++    local arg base="" previous="" candidate layout
++    for arg in "$@"; do
++        [[ "$arg" == "--" ]] && break
++        case "$previous" in --base-path|-d) base="$arg" ;; esac
++        case "$arg" in --base-path=*) base="${arg#--base-path=}" ;; esac
++        [[ -n "$base" ]] && break
++        previous="$arg"
++    done
++    if [[ "$base" == /*/data ]]; then
++        candidate="${base%/data}"
++        candidate="${candidate%/*}"
++        layout="${candidate##*/}"
++        candidate="${candidate%/*}"
++        if [[ -n "$candidate" && ( "$layout" == "data" || "$layout" == "data-fork" ) ]] && [[ -d "$candidate/bin" ]]; then
++            echo "$candidate"; return
++        fi
++    fi
+     local dir="$PWD"
+     for _ in 1 2 3 4 5 6 7 8; do
+         [[ -d "$dir/networks" ]] && { echo "$dir"; return; }
+         [[ "$dir" == "/" ]] && break
+         dir="$(dirname "$dir")"
+     done
+     # A checkout: this helper sits at <root>/scripts/lib/workspace.sh, and a checkout has a
+     # fetched bin/. The npm package ships scripts/ too but never a bin/, so this rung
+     # distinguishes them.
+     local own; own="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+     [[ -d "$own/bin" ]] && { echo "$own"; return; }
+     # The per-user home.
+     if [[ -n "${XDG_DATA_HOME:-}" ]]; then
+         echo "$XDG_DATA_HOME/ppn"; return
+     fi
+     if [[ -n "${HOME:-}" ]]; then
+         echo "$HOME/.ppn"; return
+     fi
+     local owner
+     owner="$(stat -c '%U' "${BASH_SOURCE[0]}" 2>/dev/null)" \
+         || owner="$(stat -f '%Su' "${BASH_SOURCE[0]}" 2>/dev/null)" \
+         || owner=""
+     [[ "$owner" =~ ^[A-Za-z0-9._-]+$ ]] && { echo "$(eval echo "~$owner")/.ppn"; return; }
+     echo ""
+ }
+ 
+ PPN_WS="$(ppn_workspace_root)"
+ PPN_WS_BIN="$PPN_WS/bin"
+diff --git a/scripts/omni-node.sh b/scripts/omni-node.sh
+index b3cd73d..3bce0d9 100755
+--- a/scripts/omni-node.sh
++++ b/scripts/omni-node.sh
+@@ -1,112 +1,115 @@
+ #!/usr/bin/env bash
+ # Wrapper around polkadot-omni-node that forces the libp2p network backend on the
+ # collator's *relay-chain* side.
+ #
+ # Why this exists: a collator runs a relay-chain node in the same process, configured by
+ # the args after the `--` separator. zombienet owns those args and passes no
+ # `--network-backend`, so the relay side takes the default — litep2p — whose websocket
+ # listener dies a few seconds after startup with:
+ #
+ #   litep2p::websocket: [Relaychain] Websocket listener terminated error=Kind(InvalidInput)
+ #   sc_service::task_manager: [Relaychain] Essential task `network-worker` failed.
+ #
+ # `network-worker` is essential, so the whole collator exits, usually right after it has
+ # authored its first block. Verified on macOS arm64 with 1.24.0-2f2eeb2b81d: with the
+ # default backend three or four collators die on every start; with libp2p, none do.
+ #
+ # This is consistent rather than exceptional — PPN already passes --network-backend=libp2p
+ # to every relay validator (see CHAIN_ARGS.relay in @ppn/network-config). The
+ # relay side of a collator is the one relay node that was still getting the default.
+ #
+ # The flag is appended, which puts it in the relay-chain arg list, and only on a real node
+ # run: zombienet also invokes this binary for spec and key generation, where it would be
+ # rejected as an unexpected argument.
+ #
+ # Which binary is exec'd, and from where, comes from the environment (set per collator
+ # in the generated fork TOML — zombienet forwards node-level env):
+ #   PPN_BIN_DIR          bin directory; non-previewnet networks keep theirs in bin/<network>
+ #   PPN_COLLATOR_BINARY  e.g. polkadot-parachain (networks/<name>.json parachain `command`)
+ # The libp2p fix applies to any cumulus collator, whichever binary it is.
+ set -euo pipefail
+ 
+ # Where the binaries are is a property of the *workspace*, never of this script's location.
+ # `ppn fetch` writes them to the workspace's bin/ ($PPN_HOME, or the checkout); installed from
+ # npm this script lives in node_modules/@parity/ppn/scripts, whose ../bin does not exist at all
+ # — under `set -e` the old `cd .../../bin` ended the script before the fallback below could run.
+ # So: the explicit env first, then the workspace, and only then this script's own tree, which is
+ # the right answer in a checkout and a harmless miss anywhere else.
+ source "$(dirname "${BASH_SOURCE[0]}")/lib/workspace.sh"
++# Only the node launcher opts into base-path recovery; service args are never scanned.
++PPN_WS="$(ppn_workspace_root "$@")"
++PPN_WS_BIN="$PPN_WS/bin"
+ REPO_BIN="$PPN_WS_BIN"
+ # `ppn start` exports BIN as the directory this run resolved to — bin/ for previewnet,
+ # bin/<network> for everything else — and the probe below inherits it even though it gets
+ # none of the node-level env.
+ BIN_DIR="${PPN_BIN_DIR:-${BIN:-$REPO_BIN}}"
+ BINARY="${PPN_COLLATOR_BINARY:-polkadot-omni-node}"
+ BIN="$BIN_DIR/$BINARY"
+ 
+ # Fall back to bin/<network>/ when the resolved path has nothing in it.
+ #
+ # Before spawning anything, zombienet probes each node command to learn which arguments it
+ # accepts — and that probe runs *without* the node-level env, so PPN_BIN_DIR is unset and the
+ # lookup above lands on plain bin/. previewnet keeps its binaries there, so it works; every other
+ # network keeps them in bin/<network>/, and the probe fails with a bare
+ #
+ #   NodeAvailableArgsError("", ".../scripts/omni-node.sh")
+ #
+ # which says nothing about a missing binary. It only shows up on a machine that has fetched one
+ # network and not previewnet — a fresh CI runner — so a developer whose bin/ still holds a
+ # previewnet fetch will never see it.
+ #
+ # The probe cannot know the *name* either: Kusama's collator is polkadot-parachain and it
+ # still probes as the default, which is how a completed bite died at spawn with the error
+ # above naming bin/polkadot-omni-node. A network's directory holds one collator, so
+ # whichever of the two is in there is the one this network runs.
+ if [[ ! -x "$BIN" ]]; then
+     dirs=("$BIN_DIR")
+     if [[ -n "$REPO_BIN" ]]; then
+         [[ -n "${PPN_NETWORK:-}" ]] && dirs+=("$REPO_BIN/$PPN_NETWORK")
+         dirs+=("$REPO_BIN" "$REPO_BIN"/*/)
+     fi
+     for dir in "${dirs[@]}"; do
+         for name in "$BINARY" polkadot-omni-node polkadot-parachain; do
+             if [[ -x "${dir%/}/$name" ]]; then
+                 BIN="${dir%/}/$name"
+                 break 2
+             fi
+         done
+     done
+ fi
+ 
+ # On a chain whose Aura is ed25519 (Polkadot's Asset Hub), zombienet's keystore has no key the
+ # collator can author with: it writes `aura` as sr25519 and files the ed25519 key under `gran`.
+ # Same seed, so inserting it under `aura` is all that is missing — without it the collator syncs,
+ # reports no error, and never proposes a block.
+ #
+ # Only on a real node run: the arg probe passes neither, and `key insert` on a half-set-up node
+ # would fail the probe rather than the spawn.
+ if [[ "${PPN_COLLATOR_AURA:-}" == "ed25519" ]]; then
+   base=""; chain=""
+   prev=""
+   for arg in "$@"; do
+     case "$prev" in
+       --base-path|-d) base="$arg" ;;
+       --chain) chain="$arg" ;;
+     esac
+     prev="$arg"
+   done
+   if [[ -n "$base" && -n "$chain" ]]; then
+     name="$(basename "$base")"
+     [[ "$name" == "data" ]] && name="$(basename "$(dirname "$base")")"
+     "$BIN" key insert --key-type aura --scheme ed25519 \
+       --suri "//$name" --chain "$chain" --base-path "$base" \
+       || echo "omni-node.sh: could not insert the ed25519 aura key for $name" >&2
+   fi
+ fi
+ 
+ for arg in "$@"; do
+   if [[ "$arg" == "--" ]]; then
+     exec "$BIN" "$@" --network-backend=libp2p --discover-local --allow-private-ip
+   fi
+ done
+ 
+ exec "$BIN" "$@"
+diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.ts
+index 3758d00..1f79646 100644
+--- a/packages/cli/src/commands/start.ts
++++ b/packages/cli/src/commands/start.ts
+@@ -24,7 +24,7 @@ import {
+   type NetworkDef,
+ } from '@parity/ppn-network-config';
+ import { readSpawnStamp, writeSpawnStamp, SPAWN_FILE } from '../lib/spawn-stamp.js';
+-import { localEnvContent, childEnv, customProcessEnv, spawnTomlFor, withCustomProcessEnv } from '../lib/spawn-env.js';
++import { localEnvContent, childEnv, customProcessEnv, spawnTomlFor, withCustomProcessEnv, withNodeProcessEnv } from '../lib/spawn-env.js';
+ import { forkBundleName } from '../lib/fork-bundle-name.js';
+ import {
+   classifyGroup,
+@@ -550,7 +550,10 @@ export async function start(args: string[], opts: StartOptions = {}): Promise<vo
+   const tomlFile = spawnTomlFor(sourceToml);
+   fs.writeFileSync(
+     tomlFile,
+-    withCustomProcessEnv(fs.readFileSync(sourceToml, 'utf-8'), customProcessEnv({ workspace: WS, network: name, dataDir }))
++    withNodeProcessEnv(
++      withCustomProcessEnv(fs.readFileSync(sourceToml, 'utf-8'), customProcessEnv({ workspace: WS, network: name, dataDir })),
++      { PPN_HOME: WS, PPN_BIN_DIR: binDir, PPN_NETWORK: name }
++    )
+   );
+ 
+   // Decided after ensureDeps, which is where a --fresh-bite produces the bundle the data is

package/adapters/environment/engine/src/setup/patch-catalogue.d.ts

@@ -18,3 +18,26 @@ export declare const LIGHT_TOPOLOGY_OVERLAY: {
 };
 /** The descriptor overlays a fork layout names (`ForkLayout.descriptors`), by manifest entry. */
 export declare const DESCRIPTOR_OVERLAYS: Readonly<Record<string, unknown>>;
+/**
+ * The native-node workspace fix (patches/previewnet-engine/manifest.json, `node-workspace`): optional, stock Engine stays
+ * the default. Its file ships beside this catalogue (`file`, in this folder), byte for byte the repository's
+ * patches/previewnet-engine/node-workspace.patch, so an installed package prepares the same patched Engine as the
+ * checkout (`shippedEnginePatch`, patches.ts). This entry is its manifest entry in the package.
+ */
+export declare const NODE_WORKSPACE_PATCH: {
+    readonly name: "node-workspace";
+    readonly file: "node-workspace.patch";
+    readonly repository: "https://github.com/paritytech/previewnet-engine.git";
+    readonly base: "e11792b234ca0c39a5fc1d47af491f82fc8e2670";
+    readonly sha256: "a4b866a6da4cbb636bd614271c9691280490b00172dae02a8b113ad161055757";
+};
+/** The Engine patches the package ships, by name (`EngineSource.patch`). */
+export declare const SHIPPED_ENGINE_PATCHES: {
+    readonly "node-workspace": {
+        readonly name: "node-workspace";
+        readonly file: "node-workspace.patch";
+        readonly repository: "https://github.com/paritytech/previewnet-engine.git";
+        readonly base: "e11792b234ca0c39a5fc1d47af491f82fc8e2670";
+        readonly sha256: "a4b866a6da4cbb636bd614271c9691280490b00172dae02a8b113ad161055757";
+    };
+};

package/adapters/environment/engine/src/setup/patch-catalogue.js

@@ -13,3 +13,11 @@ export const OWNED_PROCESSES_PATCH = {
 };
 export const LIGHT_TOPOLOGY_OVERLAY = { relay: { validators: 4 } };
 export const DESCRIPTOR_OVERLAYS = { "light-topology": LIGHT_TOPOLOGY_OVERLAY };
+export const NODE_WORKSPACE_PATCH = {
+    name: "node-workspace",
+    file: "node-workspace.patch",
+    repository: ENGINE_RELEASE.repository,
+    base: ENGINE_RELEASE.base,
+    sha256: "a4b866a6da4cbb636bd614271c9691280490b00172dae02a8b113ad161055757",
+};
+export const SHIPPED_ENGINE_PATCHES = { [NODE_WORKSPACE_PATCH.name]: NODE_WORKSPACE_PATCH };

package/adapters/environment/engine/src/setup/patches.d.ts

@@ -9,7 +9,7 @@ declare const patchEntry: z.ZodObject<{
 export type PatchEntry = z.infer<typeof patchEntry>;
 /** Repository-level `patches/` directory, shared by every provider. */
 export declare const patchesDirectory: string;
-/** Why a patched Engine cannot be prepared or checked here: this installation carries no Engine patches. */
+/** Why a repository patch's manifest cannot be read here: this installation carries no patches/ folder. */
 export declare const ENGINE_PATCHES_REPOSITORY_ONLY: string;
 /** A patch or manifest was asked for where patches/<upstream>/ does not exist (an installed package). */
 export declare class EnginePatchesNotInstalled extends Error {
@@ -34,4 +34,18 @@ export declare function resolvePatch(upstream: string, name: string): {
     base: string;
     repository: string;
 };
+/** The Engine patch the package ships (adapters/environment/engine/src/setup/), read here and digest-checked. */
+export declare const shippedPatchesDirectory: string;
+/**
+ * One Engine patch the package ships (`SHIPPED_ENGINE_PATCHES`), from its file beside the catalogue, refused when the
+ * file differs from the catalogue's digest. The same file in product-lab's checkout and in an installed package;
+ * `directory` is for tests (a changed copy is refused).
+ */
+export declare function shippedEnginePatch(name: string, directory?: string): {
+    name: string;
+    path: string;
+    sha256: "a4b866a6da4cbb636bd614271c9691280490b00172dae02a8b113ad161055757";
+    base: "e11792b234ca0c39a5fc1d47af491f82fc8e2670";
+    repository: "https://github.com/paritytech/previewnet-engine.git";
+};
 export {};