@parity/product-lab 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @parity/product-lab
 
+## 0.3.0
+
+### Minor Changes
+
+- b2abd7c: Add `previewnetGenesis()` to `@parity/product-lab/composition`: one line of a lab's config, `environments: { ...previewnetGenesis() }`, gives it "Previewnet from genesis" (`previewnet-genesis`), Previewnet's People, Asset Hub and Bulletin started from genesis on your machine by Engine, a new network every start. Once it is ready, and after every reset, People's rings are prepared for new people, so a new person can be onboarded on it like on the local copies. `product-lab fetch --environment previewnet-genesis` prepares its Engine and `product-lab doctor` checks it; it keeps its own folder in the cache, so your local copies' Engine is not changed. It binds Engine's default ports (relay 10000 to 10005, People 10010, Asset Hub 10020, Bulletin 10030, dashboard 8090, dub 8092, dub's database 5433, and Engine's other defaults in its config/ports.env: eth-rpc 8545, IPFS 8080, 5001 and 4001, TURN 3478, 3479 and its relay range 49152 to 49407, p2p 30333 to 30336), not the lab's port block: one Engine network per machine at a time; a port option is a planned follow-up.
+  
+  The package now ships Engine's node-workspace patch, so `EngineSource.patch: "node-workspace"` works from an installed package instead of failing with `EnginePatchesNotInstalled`. The Engine setup script takes `--engine-patch node-workspace`. People's ring preparation is available on its own as `PeopleAttesterChain.prepareRings(collections)`, with `PEOPLE_LITE_COLLECTION`.
+
+### Patch Changes
+
+- b2abd7c: A failed step is no longer explained by the folders or Node modules in its stack trace. The failure explanation's rules now read only the error's message, not its stack frames, so a check that fails in a checkout or product folder named like `previewnet-genesis` or `truapi`, or with frames in a `websocket.js` file or `node:events`, keeps the explanation its message gives, instead of "Infrastructure, not the product", a chain mismatch or a host refusal. The environment rule's bare words "genesis" and "baseline" are replaced by the environment errors they were meant for: endpoints that share a genesis, a fast baseline that is missing, for another machine or changed, an attached chain or Chopsticks upstream that is another chain, and a People whose genesis is not the network's. An assertion that mentions genesis, such as "account funded at genesis", is explained as the check's failure.
+
 ## 0.2.0
 
 ### Minor Changes

package/adapters/environment/engine/README.md

@@ -45,7 +45,8 @@ use to reach an Engine network. Imported from the original lab.
 | `topology/engine-plan.ts` | `engineLaunchPlan`: a resolved relay-backed `EngineTopology` as `ppn` commands (fork, `--fresh-bite`, `--upgrade`, `--runtime`, `--binary`, genesis subsets through `genesis-toml --parachains` then `start --toml`) and `config/ports.env` keys |
 | `topology/engine-topology.ts` | `resolveEngineTopology`, `engineOptionsSchema`, `engineProfiles` (full-fork, genesis-subset), `engineFlagOptions`, `ENGINE_FLAGS` (`--engine-arg`, `--engine-env`, `--engine-toml`), `ENGINE_KIND`, `DEFAULT_ENGINE_PORTS`: the adapter's own topology options, defaults, flags and issues (refactor step 5) |
 | `topology/engine-environment-factory.ts` | `EngineEnvironmentFactory`: the adapter's `TopologyAdapterFactory` (kind `engine`, section `engine`), constructed by the composition root when a lab selects `defineLab({ environmentAdapters: { engine: { engineConfig } } })` (`composition/src/adapter-catalogue.ts`), or registered directly with `defineLab({ environmentFactories: [new EngineEnvironmentFactory({ engineConfig })] })` |
-| `setup/prepare-engine.ts`, `setup/engine-build.ts`, `setup/patches.ts`, `setup/patch-catalogue.ts` | Stock Engine v0.11.0 preparation and shipped release pin; `preparedEngine` checks the pin, stock record, checkout HEAD, built CLI and dot CLI. The optional repository-only `EngineSource.patch: "node-workspace"` is manifest-checked, applied before build, keyed by digest and reverse-checked before reuse. Retired owned-processes records and requests are refused. Descriptor overlays remain digest-checked through the manifest. |
+| `setup/prepare-engine.ts`, `setup/engine-build.ts`, `setup/patches.ts`, `setup/patch-catalogue.ts`, `setup/node-workspace.patch` | Stock Engine v0.11.0 preparation and shipped release pin; `preparedEngine` checks the pin, stock record, checkout HEAD, built CLI and dot CLI. The optional `EngineSource.patch: "node-workspace"` is read from the copy the package ships beside the catalogue (`setup/node-workspace.patch`, `shippedEnginePatch`, digest-checked against `NODE_WORKSPACE_PATCH`, its manifest entry in the package; since 12 November 2026, so a product prepares it too: `tests/patch-catalogue.test.ts` holds it byte for byte the repository's `patches/previewnet-engine/node-workspace.patch`), applied before build, keyed by digest and reverse-checked before reuse. Retired owned-processes records and requests are refused. Descriptor overlays remain digest-checked through the repository manifest. |
+| `setup/engine-tooling.ts` | An Engine checkout as an environment's tooling in a state directory of its own (12 November 2026, for composition's `previewnetGenesis`): `engineCheckoutTooling({ state, network, patch, environment })` (id `engine:<state>`; `check` is ready only for the build `patch` names; `prepare` runs `prepareEngine` with it, and refuses `--no-engine-patch` for a patched one), `preparedEngineCheckout` (the start's check, its refusal naming the fix) and `engineFetchCommand(environment)` (`product-lab fetch --environment <id>`, through the checkout's CLI script or npx). `tests/engine-checkout-tooling.test.ts` |
 | `setup/setup-command.ts` | The command every Engine refusal names, for where this adapter runs (`engineSetupCommand(environment?)`): `bun run setup` in product-lab's checkout, `npx --no-install product-lab fetch --environment <id>` in a product, which has no `bun run setup` (`insideProductLabCheckout`, this adapter's own copy of the CLI's check) |
 | `saved-fork/saved-fork-tooling.ts` | The Engine checkout a saved fork starts from, `<cacheDir>/engine` (16 October 2026): `savedForkEngine` (the start's check, `as-prepared`, its refusal naming `SavedForkSettings.setupCommand`, default `engineSetupCommand`), and `savedForkTooling`, the fork's `EnvironmentProvider.tooling` (id `engine:<cacheDir>/engine`, shared by every saved fork with that cache; kind `engine`): `check` is `savedForkEngine`'s, `prepare` runs `prepareEngine` there for the fork's network with the request's source (`repository`, `ref`, `patched: false` for stock, also the default; `patched: true` is refused) and returns the check of exactly what it asked for. `product-lab fetch` prepares it and `product-lab doctor` reports it in a product. A saved fork can reuse a node-workspace build prepared through `prepareEngine`; its status names that patch and its launch config records `enginePatch`, so the launch-time reverse check is retained. A saved fork started from a stock build writes `enginePatch: "none"` in its own engine.json |
 | `testing` subpath | Fake Engine dashboard and chain RPCs for contract tests (`codeHashOffset`, `specVersion` change the served runtime) |

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

@@ -38,8 +38,9 @@ export { defaultEngineRepository, defaultStateDirectory, enginePatch, EngineNotP
 export { ENGINE_PATCHES, engineBuildIssue, type EnginePatch } from "./setup/engine-build.js";
 export { CHECKOUT_ENGINE_SETUP, engineSetupCommand } from "./setup/setup-command.js";
 export { engineBuildWords, savedForkEngine, savedForkEngineState, savedForkSetupCommand, savedForkTooling } from "./saved-fork/saved-fork-tooling.js";
-export { ENGINE_PATCHES_REPOSITORY_ONLY, EnginePatchesNotInstalled, patchesDirectory, patchesInstalled, readPatchManifest, resolvePatch, type PatchEntry, } from "./setup/patches.js";
-export { DESCRIPTOR_OVERLAYS, LIGHT_TOPOLOGY_OVERLAY, OWNED_PROCESSES_PATCH } from "./setup/patch-catalogue.js";
+export { engineCheckoutTooling, engineFetchCommand, preparedEngineCheckout, type EngineCheckoutSettings } from "./setup/engine-tooling.js";
+export { ENGINE_PATCHES_REPOSITORY_ONLY, EnginePatchesNotInstalled, patchesDirectory, patchesInstalled, readPatchManifest, resolvePatch, shippedEnginePatch, shippedPatchesDirectory, type PatchEntry, } from "./setup/patches.js";
+export { DESCRIPTOR_OVERLAYS, LIGHT_TOPOLOGY_OVERLAY, NODE_WORKSPACE_PATCH, OWNED_PROCESSES_PATCH, SHIPPED_ENGINE_PATCHES } from "./setup/patch-catalogue.js";
 export { engineLaunchPlan, type EngineCommand, type EngineLaunchPlan, } from "./topology/engine-plan.js";
 export { DEFAULT_ENGINE_DASHBOARD, enginePortOverrides, engineRun, type EngineIsolationInput, type EngineRun, type EngineRunIsolation, } from "./topology/engine-run.js";
 export { ENGINE_TIME_UNSUPPORTED, describeEngine, engineEnvironment, type EngineEnvironmentSettings, } from "./topology/engine-provider.js";

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

@@ -40,8 +40,9 @@ export { defaultEngineRepository, defaultStateDirectory, enginePatch, EngineNotP
 export { ENGINE_PATCHES, engineBuildIssue } from "./setup/engine-build.js";
 export { CHECKOUT_ENGINE_SETUP, engineSetupCommand } from "./setup/setup-command.js";
 export { engineBuildWords, savedForkEngine, savedForkEngineState, savedForkSetupCommand, savedForkTooling } from "./saved-fork/saved-fork-tooling.js";
-export { ENGINE_PATCHES_REPOSITORY_ONLY, EnginePatchesNotInstalled, patchesDirectory, patchesInstalled, readPatchManifest, resolvePatch, } from "./setup/patches.js";
-export { DESCRIPTOR_OVERLAYS, LIGHT_TOPOLOGY_OVERLAY, OWNED_PROCESSES_PATCH } from "./setup/patch-catalogue.js";
+export { engineCheckoutTooling, engineFetchCommand, preparedEngineCheckout } from "./setup/engine-tooling.js";
+export { ENGINE_PATCHES_REPOSITORY_ONLY, EnginePatchesNotInstalled, patchesDirectory, patchesInstalled, readPatchManifest, resolvePatch, shippedEnginePatch, shippedPatchesDirectory, } from "./setup/patches.js";
+export { DESCRIPTOR_OVERLAYS, LIGHT_TOPOLOGY_OVERLAY, NODE_WORKSPACE_PATCH, OWNED_PROCESSES_PATCH, SHIPPED_ENGINE_PATCHES } from "./setup/patch-catalogue.js";
 export { engineLaunchPlan, } from "./topology/engine-plan.js";
 export { DEFAULT_ENGINE_DASHBOARD, enginePortOverrides, engineRun, } from "./topology/engine-run.js";
 export { ENGINE_TIME_UNSUPPORTED, describeEngine, engineEnvironment, } from "./topology/engine-provider.js";

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

@@ -3,7 +3,7 @@ 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[];
-/** Stock and the optional repository fix; owned-processes is recognized only to refuse stale configurations. */
+/** 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";

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

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { resolvePatch } from "./patches.js";
+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";
@@ -15,7 +15,7 @@ export function engineBuildIssue(checkout, commands, patch = "none") {
     if (patch !== "none" && patch !== "node-workspace")
         return ENGINE_PATCH_RETIRED;
     if (patch === "node-workspace") {
-        const resolved = resolvePatch("previewnet-engine", patch);
+        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 });

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,9 +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>>;
-/** Optional repository-only fix; stock preparation remains the default. */
+/**
+ * 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

@@ -15,6 +15,9 @@ 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 };