@parity/product-lab 0.2.0 → 0.3.0

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 {};

package/adapters/environment/engine/src/setup/patches.js

@@ -2,8 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
+import { SHIPPED_ENGINE_PATCHES } from "./patch-catalogue.js";
 const patchEntry = z
     .looseObject({
     file: z.string().regex(/^[\w.-]+\.(?:patch|json)$/),
@@ -13,8 +15,8 @@ const patchEntry = z
     adds: z.array(z.string()),
 });
 export const patchesDirectory = fileURLToPath(new URL("../../../../../patches/", import.meta.url));
-export const ENGINE_PATCHES_REPOSITORY_ONLY = "a patched Engine is prepared from the product-lab repository; this installation of product-lab carries no previewnet-engine patches (patches/ is not part of the package). " +
-    "Prepare stock Engine instead: `product-lab fetch --environment <id> --no-engine-patch` (EngineSource `patch: \"none\"`)";
+export const ENGINE_PATCHES_REPOSITORY_ONLY = "the previewnet-engine patch manifest is the product-lab repository's; this installation of product-lab carries no patches/ folder (patches/ is not part of the package), only the node-workspace patch it ships. " +
+    "Prepare stock Engine, or the shipped node-workspace patch: `product-lab fetch --environment <id>` (EngineSource `patch: \"none\"` or `\"node-workspace\"`)";
 export class EnginePatchesNotInstalled extends Error {
     directory;
     constructor(directory) {
@@ -46,3 +48,16 @@ export function resolvePatch(upstream, name) {
         throw new Error(`${upstream}/${entry.file} differs from its manifest digest`);
     return { name, path, sha256, base: entry.base, repository: entry.repository };
 }
+export const shippedPatchesDirectory = fileURLToPath(new URL("./", import.meta.url));
+export function shippedEnginePatch(name, directory = shippedPatchesDirectory) {
+    const entry = Object.hasOwn(SHIPPED_ENGINE_PATCHES, name) ? SHIPPED_ENGINE_PATCHES[name] : undefined;
+    if (!entry)
+        throw new Error(`Unknown shipped Engine patch: ${name} (shipped: ${Object.keys(SHIPPED_ENGINE_PATCHES).join(", ")})`);
+    const path = join(directory, entry.file);
+    if (!existsSync(path))
+        throw new Error(`The shipped Engine patch ${name} is missing from this installation (no ${path}): reinstall @parity/product-lab`);
+    const sha256 = createHash("sha256").update(readFileSync(path)).digest("hex");
+    if (sha256 !== entry.sha256)
+        throw new Error(`The shipped Engine patch ${entry.file} differs from its catalogue digest`);
+    return { name, path, sha256, base: entry.base, repository: entry.repository };
+}

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

@@ -29,7 +29,7 @@ export interface EngineSource {
     /**
      * `none`: stock Engine at the ref, without the owned-processes patch (an Engine that carries the fixes upstream),
      * recorded as such (engine-build.json `patch: "none"`, an empty `patchSha256`; engine.json `enginePatch: "none"`).
-     * `node-workspace`: repository-only native-node workspace fix at the tested base.
+     * `node-workspace`: the native-node workspace fix at the tested base, which the package ships (patch-catalogue.ts).
      * Default `none`. The retired `owned-processes` value is refused.
      */
     readonly patch?: EnginePatch;

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

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, symlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { checkedSync } from "./sync-command.js";
-import { resolvePatch } from "./patches.js";
+import { shippedEnginePatch } from "./patches.js";
 import { ENGINE_RELEASE, NODE_WORKSPACE_PATCH } from "./patch-catalogue.js";
 import { ENGINE_PATCH_RETIRED, engineBuildIssue } from "./engine-build.js";
 import { applyTurnRelayChoice, turnRelayAvailable } from "../engine/turn-relay.js";
@@ -45,7 +45,7 @@ export function prepareEngine(root, ref, network, commands, stateDirectory = def
     if (source.patch && source.patch !== "none" && source.patch !== "node-workspace")
         throw new Error(ENGINE_PATCH_RETIRED);
     const patch = source.patch ?? "none";
-    const patchFile = patch === "node-workspace" ? resolvePatch("previewnet-engine", patch) : undefined;
+    const patchFile = patch === "node-workspace" ? shippedEnginePatch(patch) : undefined;
     if (patchFile && (patchFile.sha256 !== NODE_WORKSPACE_PATCH.sha256 || patchFile.base !== NODE_WORKSPACE_PATCH.base))
         throw new Error("node-workspace patch differs from its tested catalogue");
     const output = source.output ?? "inherit";

package/composition/README.md

@@ -32,7 +32,7 @@ its own, so its result never depends on a developer's running lab and never rewr
 | Part | Built from |
 | --- | --- |
 | System ports | `NodeSystem` (`src/node-system.ts`, `new NodeSystem(env, { redactor })`): files, clock, ids, logger (a `ConsoleLogger` that scrubs each line with `redactor`; `createLabRuntime` passes the runtime's own `SecretRedactor`, backlog 89), processes, bounded asynchronous and synchronous commands, locks, ports, JSON-RPC (`@product-lab/system-node`, `@product-lab/storage-filesystem`); run manifests under `<lab root>/.product-lab/runs` |
-| Engine setup CLI | `src/engine-setup.ts` parses setup options (`--engine-ref`, `--network`, `--state-dir`, `--dry-run`; since 16 October 2026 `--engine-repository <url\|path>` and `--no-patch`, stock Engine recorded as such) and supplies `NodeSyncCommandRunner` to env-engine's synchronous `prepareEngine`, keeping adapter construction in composition. A product prepares the saved forks' Engine with `product-lab fetch --environment paseo-copy` instead (the fork's `EnvironmentProvider.tooling`, reached through `LabRuntime.prepareEnvironmentTooling`; the attached runtime answers it locally) |
+| Engine setup CLI | `src/engine-setup.ts` parses setup options (`--engine-ref`, `--network`, `--state-dir`, `--dry-run`; since 16 October 2026 `--engine-repository <url\|path>` and `--no-patch`, stock Engine recorded as such; since 12 November 2026 `--engine-patch none\|node-workspace`, the shipped node-workspace patch at the tested release) and supplies `NodeSyncCommandRunner` to env-engine's synchronous `prepareEngine`, keeping adapter construction in composition. A product prepares the saved forks' Engine with `product-lab fetch --environment paseo-copy` instead (the fork's `EnvironmentProvider.tooling`, reached through `LabRuntime.prepareEnvironmentTooling`; the attached runtime answers it locally) |
 | Console redaction (backlog 89) | `redactConsole(redactor, console?)` (`src/redact-console.ts`, exported): every `console.log`/`info`/`debug`/`warn`/`error` line goes through the runtime's redactor until restored, so a lab or provider printing a secret of the lab (a `fromEnv` URL with its token) never shows it. The CLI's `src/main.ts` installs it for one invocation, `featureRuntime` (bundled runs) and the Cucumber runner's `cucumberRuntime` for their process; the MCP server scrubs its captured console itself (`captureConsole`'s `redact`). Tests: `tests/redact-console.test.ts`, `tests/composition.test.ts` (the logger a provider gets, `system.logger`), and end to end `entrypoints/cli/tests/secret-console.test.ts`, `entrypoints/cli/tests/rpc-flags.test.ts`, `entrypoints/mcp/tests/stdio.test.ts` |
 | Protected stdio worker | `NodeSystem.stdioWorker` constructs the Node adapter for MCP's fd-3 protocol channel; `NodeSystem.syncCommands` supplies bounded synchronous CLI/AI commands; `NodeSystem.terminalCommands` runs an interactive program on the terminal (the terminal app's agent beside the lab) |
 | Environment adapters | the kinds the lab selects in `defineLab({ environmentAdapters: { <kind>: <settings> } })`, from `ENVIRONMENT_ADAPTERS` (`engine`, `relayless`, `chopsticks` with the attached adapter's probe); imported when first selected |
@@ -40,6 +40,7 @@ its own, so its result never depends on a developer's running lab and never rewr
 | Host tool services | `src/host-tool-services.ts`: `hostToolServices({ clock, env })` gives the runtime a `NodeCommandRunner`, a `NodeProcessSandbox` (the official build's behavioural probes run under it) and `githubUpstreamResolver`, an `UpstreamResolver` on the GitHub version adapter (`latest` = newest release in the request's tag family, skipping other packages' tags, drafts and prereleases; `GITHUB_TOKEN` when set). `host rebase-check` receives all three in its tool context (`tests/host-tool-services.test.ts`, a fake API) |
 | What a lab's own code gets (refactor step 9) | `SessionContext.system` and `EnvironmentStartContext.system` (the lab's system ports, `NodeSystem.forLab`, including `commands: NodeCommandRunner` for bounded one-shot commands), `SessionContext.browsers` (`BROWSERS`: `PlaywrightBrowserLauncher`, imported on first launch; `defineLab({ browsers })` overrides) |
 | Local copies of live networks (the user's decision 5) | `paseoCopy(options?)` and `previewnetCopy(options?)` (`src/network-copies.ts`): one line of a lab's config, `environments: { ...paseoCopy() }`, gives it "Local copy of Paseo", Full or Light (backlog 184), each env-engine's `savedForkEnvironment` in its own folder (`<lab>/.product-lab/environments/<id>`, `<id>-light`) with the live reads composed here (`readLiveRuntimes`, `liveCodeFetcher`), the lab's cache (PRODUCT_LAB_CACHE_DIR) and seeds (PRODUCT_LAB_SHARED_FIXTURES), and a port block (`portBase`, else PRODUCT_LAB_FORK_PORT_BASE, else 42000). `savedForkOptions` builds the options for a lab's own forks (Notes). `tests/network-copies.test.ts` |
+| Previewnet from genesis (12 November 2026) | `previewnetGenesis(options?)` (`src/previewnet-genesis.ts`): one line of a lab's config, `environments: { ...previewnetGenesis() }`, gives it "Previewnet from genesis" (id `previewnet-genesis`, kind `fast-local`): env-engine's `engineEnvironment` over `engineProfiles.genesisSubset({ chains })` (default People, Asset Hub and Bulletin, `PREVIEWNET_GENESIS_CHAINS`), `mode: "genesis"`, a new owned network every start with Engine's readiness. 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 backlog 253 in docs/backlog.md). Its Engine checkout carries the node-workspace patch the package ships, in a cache folder of its own (`<cache>/engine-node-workspace`, env-engine's `engineCheckoutTooling`), so `product-lab fetch --environment previewnet-genesis` prepares it, `product-lab doctor` checks it, and the copies' stock `<cache>/engine` is never changed; a start without it is refused naming that fetch. Once Engine is ready, and after every reset, People's rings are prepared for new people by the genesis sudo key //Alice (`prepareGenesisRings`, people-dev's `PeopleAttesterChain.prepareRings`): the ZK chunk pages from `people-chunks.json` a genesis lacks and an onboarding size of 1 for the lite people collection (`PEOPLE_LITE_COLLECTION`), each skipped when the chain has it; the transactions are in the provenance (`peopleRings`) and a notice, the journal beside Engine's reports. `peopleRings: false` turns it off; a failed preparation stops the network and fails the start. Options: `id`, `label`, `description`, `chains`, `cacheDir`, `reports`, `peopleRings`, `startupTimeoutMs`. `tests/previewnet-genesis.test.ts` (live start) |
 | The product config (config redesign, lane L1) | `labDefinitionFrom(config, { root, env, environmentPorts?, path? })` (`src/default-lab.ts`, exported): `defineLab({ app, … })` (core/application's `product-lab-config.ts`) onto the definition the runtime runs, starting nothing. The app's id is its first step set's; the others are offered beside it as standalone integrations, available wherever their own requirements hold (7 October 2026: before, each was "used by no app of this lab" and every sentence of theirs refused). Sr25519 keys; fixture `inputs` default `FIXTURE_INPUTS`. It also returns `resolvedConfig` (`@product-lab/ports/driving`'s `ResolvedLabConfig`: every value and where it came from, a secret by its variable's name only), which `createLabRuntime` passes to the registry (`LabRegistry.config`). `createLabRuntime` translates every product config through it, object or function form (`PRODUCT_LAB_MODE` is the function's `mode`; it may be async). `tests/default-lab.test.ts` |
 | The product config's environments | `fast` is `relaylessTopology` over People and the app's chains it can make; `paseo-copy` `paseoCopy`; `previewnet-copy` and `chopsticks` only when listed; `live.<network>` `liveNetworkEnvironment` (read only without `people`; with them read-write, each person pre-onboarded from the variable named, `newPeople.fund` in planck on the first app chain). `defaultEnvironment` and a mode may name the lab's environments or the keys of `advanced.environments`. Each environment's run folders are under `<output>/environments` (`PRODUCT_LAB_OUTPUT_DIR`, default `<lab>/.product-lab`; Chopsticks' in `chopsticks/` there, its adapter also when `advanced` brings a Chopsticks topology). `tests/default-lab.test.ts` |
 | The product config's people on `fast` | Persons (`persons` launch option; the default session's `src/default-session-persons.ts` calls people-dev's `peopleOnboarding` and `standInForXcm`, People's genesis from `peopleDevGenesis`) when the app's chains include bulletin or its requires name the Statement Store, else funded wallets. `environments.fast.personProduct` names the label of the person product their member keys are derived under (`"<label>"` alone; the lab adds each network's suffix), shown as `environments.fast.personProduct`; unset, the released truAPI host's, so the keys are today's; refused when it is not a label, and, when the app needs persons, with `onboarding: "truapi-cli"` (the CLI host derives under its own preset). `tests/default-lab.test.ts`, `tests/people-dev-member-key.test.ts` |
@@ -53,7 +54,7 @@ its own, so its result never depends on a developer's running lab and never rewr
 | The product config's ports and workers | A lab without `ports` claims blocks of 100 in 20000-32699 (`NodeSystem.ports.next()`, `@product-lab/system-node`'s `claimPortBlock`; the window's and the local dev chain's blocks seeded by the lab's directory, so a reopened lab finds them again); `ports` or `PRODUCT_LAB_PORTS` names a range instead, carved from the top. The function form's `claimPorts(size)` (`LabPreparation.claimPorts`) gives exactly `size` ports from the same allocator for what the config runs itself (Notes' own sessions, 500), or refuses by name. `ports: { size }` (1-10000) makes the window's and its sessions' block exactly that size, seeded `<lab>:config` as `claimPorts` is, with the chains' 100 exactly beside it: under PRODUCT_LAB_PORTS from the top, refused naming the range, the size and what is left when it cannot hold them (before, a lab got at most half of what was left); `resolvedConfig`'s `ports` shows the block ("500 ports: 48100-48599"). A lab that states no size gets the blocks it got before. `tests/ports-size.test.ts` A `workers` declaration: each worker `PRODUCT_LAB_OUTPUT_DIR`, its own claimed ports or a slice of a fixed range. `tests/default-lab.test.ts` |
 | The product config's `advanced` | Today's definition fields the shape does not cover yet, merged over the translation: an app's, a host's or an adapter's fields one by one, `keepBetweenStarts` whole, other records by key, anything else replaces; each listed in `resolvedConfig` with its `advancedWhy`, an adapter by its label (`ADAPTER_LABELS`, `src/adapter-catalogue.ts`, held equal to each factory's by `tests/adapter-catalogue.test.ts`), never its code id; lint warns on a why for a field `advanced` does not set. `tests/default-lab.test.ts` |
 | The product config's versions (lane L4) | `productVersions` (`src/product-versions.ts`): the policy selects every component lab.lock.json pins (runtimes and polkadot-omni-node by `versions.runtime`, a pinned host by `versions.hosts`; `locked` by default) and, at `latest` only, runtimes and hosts the lock does not pin (a `locked` selector the lock cannot answer would refuse every run); sources for every component that can move, with polkadot-omni-node's added (`NODE_VERSION_SOURCES`: paritytech/polkadot-sdk, the whole tag as the version, the assets as the lock records them, ranked by `order` since polkadot-sdk's tags are not dotted versions; checked against the live repository's release listing on 7 October 2026: the lock's `polkadot-stable2606-2` and the newest stable release carry both assets under those names, and the latest published release, `polkadot-stable2603-7`, is a patch of an older line without them, which `order` ranks below 2606-2; `tests/product-versions.test.ts` replays that listing); a lock that is missing or pins nothing is declared under `unsupported["*"]`, so a mode's `latest` row says the lab has nothing to resolve, naming the lock (`tests/product-versions.test.ts`). |
-| The local dev chain's people (backlog 91; from Notes, 6 October 2026) | `src/people-dev/`, product-neutral, for the default session: `peopleDevGenesis(chains)` (People's people and people-lite collections at genesis, `relaylessTopology({ chains, ...peopleDevGenesis(chains) })`); `peopleOnboarding(options)` (a person per new actor: the truAPI CLI provisioner where an identity backend runs, else the lab attester, which reads the wallet's People member key and ring (`environments.fast.onboarding`: `"released"`, the default, with `releasedAllocCheck` in `src/people-dev/member-key.ts`: the ring-VRF entropy in TypeScript, per network (`<label>.<suffix>`: the label `environments.fast.personProduct`, by default the one the released truAPI host derives under, `DEFAULT_PERSON_PRODUCT`; the suffix the routes' namespace) as host-rust-core 0.23 derives it, pinned to its vectors, the released core's `ringVrfMember` and People's `Members` storage at the finalized block, printed in `alloc-check`'s lines; or `"truapi-cli"`, the CLI host's `alloc-check`, in product-lab's checkout, and in a product once the CLI host's locked release takes the lab's local endpoints (the official release, no patches; refused by name with #1166 when it does not; the locked 0.26.0 does; `hostLockFile` names another host lock); `truapiCliAllocCheck` runs it alone), recognises it by //Alice once People's sudo key is checked to be //Alice, prepares the ring on a fresh genesis and waits until the ring includes it; `memberStanding` reads where a member stands); `standInForXcm(environment, options)` (the lab answers each Bulletin allowance a relay-less People cannot send over XCM, by Bulletin's //Alice, declared as lab setup) and `xcmStandIn(environment)` to find it again, `skipNext()` being the lab's self-test hook. `personReadings(person, onboarding, people)` (backlog 160): a new person's screen (the app ready with their account) and People (the member key in a ring, and the lab's own read of `Members.Members` at the finalized head) readings, which the default session offers as `actorReadings` where its people are persons; the window shows them as the step's two checks. Only for apps that write to Bulletin or the Statement Store (the coordinator's rule, 6 October 2026). `tests/people-dev-onboarding.test.ts`, `tests/people-dev-member-key.test.ts` (the vectors, the alloc-check vector, the reader's lines and controls), `tests/people-dev-xcm-stand-in.test.ts`, `tests/people-dev-readings.test.ts`; live cross-check: `tools/verify/tests/member-key-live.test.ts` |
+| The local dev chain's people (backlog 91; from Notes, 6 October 2026) | `src/people-dev/`, product-neutral, for the default session: `peopleDevGenesis(chains)` (People's people and people-lite collections at genesis, `relaylessTopology({ chains, ...peopleDevGenesis(chains) })`); `peopleOnboarding(options)` (a person per new actor: the truAPI CLI provisioner where an identity backend runs, else the lab attester, which reads the wallet's People member key and ring (`environments.fast.onboarding`: `"released"`, the default, with `releasedAllocCheck` in `src/people-dev/member-key.ts`: the ring-VRF entropy in TypeScript, per network (`<label>.<suffix>`: the label `environments.fast.personProduct`, by default the one the released truAPI host derives under, `DEFAULT_PERSON_PRODUCT`; the suffix the routes' namespace) as host-rust-core 0.23 derives it, pinned to its vectors, the released core's `ringVrfMember` and People's `Members` storage at the finalized block, printed in `alloc-check`'s lines; or `"truapi-cli"`, the CLI host's `alloc-check`, in product-lab's checkout, and in a product once the CLI host's locked release takes the lab's local endpoints (the official release, no patches; refused by name with #1166 when it does not; the locked 0.26.0 does; `hostLockFile` names another host lock); `truapiCliAllocCheck` runs it alone), recognises it by //Alice once People's sudo key is checked to be //Alice, prepares the ring on a fresh genesis (`PeopleAttesterChain.prepareRings(collections)`: the ZK chunk pages and an onboarding size of 1 for each collection, each skipped when the chain has it, after `requireDevSudo`; `previewnetGenesis` runs it for `PEOPLE_LITE_COLLECTION`) and waits until the ring includes it; `memberStanding` reads where a member stands); `standInForXcm(environment, options)` (the lab answers each Bulletin allowance a relay-less People cannot send over XCM, by Bulletin's //Alice, declared as lab setup) and `xcmStandIn(environment)` to find it again, `skipNext()` being the lab's self-test hook. `personReadings(person, onboarding, people)` (backlog 160): a new person's screen (the app ready with their account) and People (the member key in a ring, and the lab's own read of `Members.Members` at the finalized head) readings, which the default session offers as `actorReadings` where its people are persons; the window shows them as the step's two checks. Only for apps that write to Bulletin or the Statement Store (the coordinator's rule, 6 October 2026). `tests/people-dev-onboarding.test.ts`, `tests/people-dev-member-key.test.ts` (the vectors, the alloc-check vector, the reader's lines and controls), `tests/people-dev-xcm-stand-in.test.ts`, `tests/people-dev-readings.test.ts`; live cross-check: `tools/verify/tests/member-key-live.test.ts` |
 | Keep chain and people between starts (backlog 183; from Notes, 6 October 2026) | `src/people-keep/`, product-neutral: `keptPeople(options)`, the default session's entry point. A kept start (`keep`, a host that keeps app storage, an environment that names its chain generation) gets the folder `<root>/<environment>/<generation>` with `saved()` (the people to reopen, with their wallets), `remember`, `forget` (a deleted person, with their folders), `hosts()` (the truAPI CLI host's state root in that folder) and `fixtureState()`; at the start a replaced generation's people are discarded and those of generations no longer kept swept (`discard.ts`), each said in `lines`. `SavedPeople` (the records, bound to the generation) and `PeopleLifecycle` (Stop and Start keeping wallet, place and account). `tests/people-keep-*.test.ts` |
 | Default keys | `definition.keys ?? new Sr25519KeyDerivation()`: a lab whose secrets need a signer (`secrets.signer(name)`) does not need to declare a key adapter itself |
 | Default chain connections | `connectChains` (`src/chain-connections.ts`): one live `ChainConnection` (`@product-lab/chain-papi`'s `PapiChainAccess`) per chain the started environment declares (`RunningEnvironment.routes`, and since 30 September 2026 each chain its offer lists with a loopback WebSocket endpoint but no route, such as a Chopsticks fork: backlog 16, so the lab can check a time advance itself; since 3 October 2026, backlog A2, a routed chain off this machine connects only under the routes' own `publicRoutes` reason, passed as `publicEndpoint`, never without one), given to `SessionContext.chains`/`ActionContext.chains`/`AssertionContext.chains` (core/lab's `CompileOptions.chains`) and closed with the environment. Since 4 October 2026 (backlog 91) it also builds `readers` (`ChainReaders`, given to `AssertionContext.readers`): `statements(chain)` (`RpcStatementStoreReader` on that chain's endpoint) and `bulletin()` (`BulletinContentReader` through the runtime's `JsonRpcClient`), on this machine only (a chain the environment does not run, or one routed off this machine, is refused, without printing its URL); `chainConnector` (same file) is the matching `ChainConnector` a lab-level integration (`defineLab({ integrations })`, for example `@product-lab/deploy-bulletin`'s platform integration) uses instead of building its own `PapiChainAccess`/`PapiTransactionSubmitter` pair |
@@ -277,5 +278,6 @@ binary retain the checkout's routing-patch declaration. This keeps an all-releas
 patched provisioner for its identities. `tests/people-dev-onboarding.test.ts` checks a verified official cache hit and
 the older-release fallback with no host process or network request.
 
-Engine setup (`src/engine-setup.ts`) prepares stock v0.11.0 without a patch by default.
-The compatible `--no-patch` flag is optional; the release pin and build checks live in env-engine.
+Engine setup (`src/engine-setup.ts`) prepares stock v0.11.0 without a patch by default, or with the node-workspace
+patch the package ships (`--engine-patch node-workspace`). The compatible `--no-patch` flag is optional and refuses
+`--engine-patch`; the release pin and build checks live in env-engine.

package/composition/src/engine-setup.js

@@ -1,7 +1,7 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from "node:util";
-import { defaultEngineRepository, defaultStateDirectory, engineRepository, prepareEngine, setupPaths, testedEngineRef, } from "@parity/product-lab/env-engine";
+import { defaultEngineRepository, defaultStateDirectory, engineRepository, prepareEngine, setupPaths, shippedEnginePatch, testedEngineRef, } from "@parity/product-lab/env-engine";
 import { NodeSyncCommandRunner } from "@parity/product-lab/system-node";
 const root = process.cwd();
 try {
@@ -10,15 +10,21 @@ try {
             "engine-ref": { type: "string", default: testedEngineRef },
             "engine-repository": { type: "string", default: defaultEngineRepository },
             "no-patch": { type: "boolean", default: false },
+            "engine-patch": { type: "string", default: "none" },
             network: { type: "string", default: "paseo-next-v2" },
             "state-dir": { type: "string", default: defaultStateDirectory },
             "dry-run": { type: "boolean", default: false },
         },
     });
-    const source = { repository: engineRepository({ repository: values["engine-repository"] }), patch: "none" };
+    const asked = ["none", "node-workspace"].find((patch) => patch === values["engine-patch"]);
+    if (!asked)
+        throw new Error(`--engine-patch takes none or node-workspace, not ${JSON.stringify(values["engine-patch"])}`);
+    if (values["no-patch"] && asked !== "none")
+        throw new Error(`--no-patch prepares stock Engine: it cannot be combined with --engine-patch ${asked}`);
+    const source = { repository: engineRepository({ repository: values["engine-repository"] }), patch: asked };
     if (values["dry-run"])
         console.log(JSON.stringify({
-            ...setupPaths(root, values["engine-ref"], "", values["state-dir"]),
+            ...setupPaths(root, values["engine-ref"], source.patch === "none" ? "" : shippedEnginePatch(source.patch).sha256, values["state-dir"]),
             network: values.network,
             engineRef: values["engine-ref"],
             repository: source.repository,

package/composition/src/index.d.ts

@@ -12,7 +12,7 @@ export { chainConnector, connectChains, transactionSubmitter } from "./chain-con
 export { deployedRuntimeSource } from "./versions/version-source-catalogue.js";
 export { downloadLiveCode, liveCodeFetcher, readLiveRuntimes, requireLiveCode } from "./fork-live.js";
 export { PEOPLE_DEV_GENESIS, peopleDevGenesis } from "./people-dev/genesis.js";
-export { DEFAULT_FAST_ONBOARDING, labAttester, MEMBER_READERS, memberStanding, PEOPLE_COLLECTION, PeopleAttesterChain, peopleOnboarding, RING_TIMEOUT_MS, sameKey, truapiCliAllocCheck, type AllocCheck, type FastOnboarding, type LabAttesterDeps, type MemberStanding, type PeopleOnboarding, type PeopleOnboardingOptions } from "./people-dev/onboarding.js";
+export { collectionName, DEFAULT_FAST_ONBOARDING, labAttester, MEMBER_READERS, memberStanding, PEOPLE_COLLECTION, PEOPLE_LITE_COLLECTION, PeopleAttesterChain, peopleOnboarding, RING_TIMEOUT_MS, sameKey, truapiCliAllocCheck, type AllocCheck, type FastOnboarding, type LabAttesterDeps, type MemberStanding, type PeopleOnboarding, type PeopleOnboardingOptions } from "./people-dev/onboarding.js";
 export { chainCode, indexBytes, papiRingStorage, PERSON_COLLECTIONS, personProductId, personRingEntropy, releasedAllocCheck, RING_LOOKBACK, type MemberKeyOf, type RingStorage } from "./people-dev/member-key.js";
 export { personReadings, type ReadPerson } from "./people-dev/readings.js";
 export { allocationFailures, BULLETIN_ALLOWANCES, continuesChain, followBlocks, StandInLedger, standInForXcm, unansweredReason, PROBE_BLOB_STORED, XCM_STAND_IN_LABEL, XcmStandIn, xcmStandIn, type AllocationFailure, type ProbeBlob, type FinalizedBlock, type FinalizedBlocks, type PeopleEvent, type StandInForXcmOptions, type XcmStandInOptions } from "./people-dev/xcm-stand-in.js";
@@ -21,6 +21,7 @@ export { SavedPeople, type SavedPerson } from "./people-keep/saved-people.js";
 export { PeopleLifecycle, type ActorEntry, type LifecycleActor, type StoppedActor } from "./people-keep/lifecycle.js";
 export { discardedLine, discardGeneration, replacedFolder, sweepGenerations, sweptLine, type DiscardedGeneration } from "./people-keep/discard.js";
 export { DEFAULT_FORK_PORT_BASE, paseoCopy, previewnetCopy, savedForkOptions, type NetworkCopyOptions } from "./network-copies.js";
+export { PREVIEWNET_GENESIS_CHAINS, PREVIEWNET_GENESIS_ENGINE_FOLDER, PREVIEWNET_GENESIS_ID, PREVIEWNET_GENESIS_LABEL, PREVIEWNET_GENESIS_RING_COLLECTIONS, PREVIEWNET_GENESIS_STARTUP_MS, prepareGenesisRings, previewnetGenesis, previewnetGenesisEngine, previewnetGenesisEnvironment, type PeopleRingsPrepared, type PrepareRings, type PreviewnetGenesisOptions, type PreviewnetGenesisParts } from "./previewnet-genesis.js";
 export { forkPortBase, MACHINE_VARIABLES, machineInputs, type MachineInputs } from "./machine-inputs.js";
 export { attachedForkEnvironment, forkEndpoints, PASEO_FORK_NETWORK, readSnapshotFile } from "./fork-attach.js";
 export { defaultSessions } from "./default-session.js";

package/composition/src/index.js

@@ -15,7 +15,7 @@ export { chainConnector, connectChains, transactionSubmitter } from "./chain-con
 export { deployedRuntimeSource } from "./versions/version-source-catalogue.js";
 export { downloadLiveCode, liveCodeFetcher, readLiveRuntimes, requireLiveCode } from "./fork-live.js";
 export { PEOPLE_DEV_GENESIS, peopleDevGenesis } from "./people-dev/genesis.js";
-export { DEFAULT_FAST_ONBOARDING, labAttester, MEMBER_READERS, memberStanding, PEOPLE_COLLECTION, PeopleAttesterChain, peopleOnboarding, RING_TIMEOUT_MS, sameKey, truapiCliAllocCheck } from "./people-dev/onboarding.js";
+export { collectionName, DEFAULT_FAST_ONBOARDING, labAttester, MEMBER_READERS, memberStanding, PEOPLE_COLLECTION, PEOPLE_LITE_COLLECTION, PeopleAttesterChain, peopleOnboarding, RING_TIMEOUT_MS, sameKey, truapiCliAllocCheck } from "./people-dev/onboarding.js";
 export { chainCode, indexBytes, papiRingStorage, PERSON_COLLECTIONS, personProductId, personRingEntropy, releasedAllocCheck, RING_LOOKBACK } from "./people-dev/member-key.js";
 export { personReadings } from "./people-dev/readings.js";
 export { allocationFailures, BULLETIN_ALLOWANCES, continuesChain, followBlocks, StandInLedger, standInForXcm, unansweredReason, PROBE_BLOB_STORED, XCM_STAND_IN_LABEL, XcmStandIn, xcmStandIn } from "./people-dev/xcm-stand-in.js";
@@ -24,6 +24,7 @@ export { SavedPeople } from "./people-keep/saved-people.js";
 export { PeopleLifecycle } from "./people-keep/lifecycle.js";
 export { discardedLine, discardGeneration, replacedFolder, sweepGenerations, sweptLine } from "./people-keep/discard.js";
 export { DEFAULT_FORK_PORT_BASE, paseoCopy, previewnetCopy, savedForkOptions } from "./network-copies.js";
+export { PREVIEWNET_GENESIS_CHAINS, PREVIEWNET_GENESIS_ENGINE_FOLDER, PREVIEWNET_GENESIS_ID, PREVIEWNET_GENESIS_LABEL, PREVIEWNET_GENESIS_RING_COLLECTIONS, PREVIEWNET_GENESIS_STARTUP_MS, prepareGenesisRings, previewnetGenesis, previewnetGenesisEngine, previewnetGenesisEnvironment } from "./previewnet-genesis.js";
 export { forkPortBase, MACHINE_VARIABLES, machineInputs } from "./machine-inputs.js";
 export { attachedForkEnvironment, forkEndpoints, PASEO_FORK_NETWORK, readSnapshotFile } from "./fork-attach.js";
 export { defaultSessions } from "./default-session.js";

package/composition/src/people-dev/onboarding.d.ts

@@ -112,8 +112,12 @@ export interface LabAttesterDeps {
 export declare function labAttester(deps: LabAttesterDeps): Omit<PeopleOnboarding, "close">;
 /** The people collection's identifier in People's `Members` pallet (`pop:polkadot.network/people`, space padded). */
 export declare const PEOPLE_COLLECTION = "0x706f703a706f6c6b61646f742e6e6574776f726b2f70656f706c652020202020";
+/** The lite people collection's identifier in People's `Members` pallet (`pop:polkadot.network/people-lite`, 32 bytes). */
+export declare const PEOPLE_LITE_COLLECTION = "0x706f703a706f6c6b61646f742e6e6574776f726b2f70656f706c652d6c697465";
 /** Whether an address the chain read is this public key's (any SS58 prefix); false for anything that is no address. */
 export declare function sameKey(address: unknown, publicKey: Uint8Array): boolean;
+/** A collection identifier as its text when it is printable (`pop:polkadot.network/people-lite`), else as given. */
+export declare function collectionName(identifier: string): string;
 /**
  * The lab attester's People connection: `Sudo(People.force_recognize_personhood)` by the dev chain's sudo key //Alice
  * (the role an identity backend plays on a full network). People's offchain worker then puts the keys in a ring and
@@ -132,11 +136,21 @@ export declare class PeopleAttesterChain {
      * What a ring needs on a development genesis, each step skipped when the chain already has it:
      * - People's sudo key is the dev chain's //Alice (else nothing is sent: the lab cannot recognise anyone here);
      * - the people collection: created at genesis (genesis.ts, `PEOPLE_DEV_GENESIS`);
+     * - the ring chunk pages and one person at a time for the people collection (`prepareRings`).
+     */
+    private preparePeople;
+    /** People's sudo key is the dev chain's //Alice, or a refusal before anything is sent. */
+    requireDevSudo(): Promise<void>;
+    /**
+     * What People's rings need on a development genesis before anyone joins one, sent by the dev chain's sudo key //Alice
+     * (check it with `requireDevSudo` first). Each step is skipped when the chain already has it, so it may run again on
+     * the same chain:
      * - the R2e9 ZK chunk pages (`people-chunks.json`): `Sudo(Utility.dispatch_as(Authorized,
      *   ChunksManager.add_chunks))`; the chain accepts a page only when its blake2-256 is the one its genesis names;
-     * - one person at a time: `Sudo(Members.set_onboarding_size(people, 1))`; the offchain worker onboards only cohorts
-     *   of at least that size, which one lab actor at a time never fills.
+     * - one person at a time in each of `collections`: `Sudo(Members.set_onboarding_size(<collection>, 1))`; the offchain
+     *   worker onboards only cohorts of at least that size, which one lab actor at a time never fills.
+     * Every transaction sent is returned (none when the chain already had all of it).
      */
-    private preparePeople;
+    prepareRings(collections: readonly string[]): Promise<TransactionReceipt[]>;
     close(): void;
 }

package/composition/src/people-dev/onboarding.js

@@ -155,6 +155,7 @@ export function labAttester(deps) {
     };
 }
 export const PEOPLE_COLLECTION = "0x706f703a706f6c6b61646f742e6e6574776f726b2f70656f706c652020202020";
+export const PEOPLE_LITE_COLLECTION = "0x706f703a706f6c6b61646f742e6e6574776f726b2f70656f706c652d6c697465";
 const PEOPLE_CHUNKS = JSON.parse(readFileSync(new URL("./people-chunks.json", import.meta.url), "utf8"));
 export function sameKey(address, publicKey) {
     if (typeof address !== "string")
@@ -168,6 +169,10 @@ export function sameKey(address, publicKey) {
         throw error;
     }
 }
+export function collectionName(identifier) {
+    const text = Buffer.from(identifier.replace(/^0x/, ""), "hex").toString("utf8").trimEnd();
+    return /^[\x20-\x7e]+$/.test(text) ? text : identifier;
+}
 const DEV_SUDO = "//Alice";
 export class PeopleAttesterChain {
     connection;
@@ -193,14 +198,23 @@ export class PeopleAttesterChain {
         return sent;
     }
     async preparePeople() {
-        const { tx, query } = this.connection.api;
-        const sudo = tx.Sudo.sudo;
-        const sent = [];
-        const key = await query.Sudo?.Key?.getValue({ at: "best" });
-        if (!sameKey(key, this.authority.publicKey))
-            throw new Error(`People's sudo key is ${String(key)}, not the dev chain's ${DEV_SUDO} (${this.authority.address}): the lab attester makes persons on the local dev chain only`);
+        const { query } = this.connection.api;
+        await this.requireDevSudo();
         if (!(await query.People.PeopleCollectionCreated.getValue({ at: "best" })))
             throw new Error("People has no people collection: its genesis must create it (genesis edit people.createCollection, PEOPLE_DEV_GENESIS)");
+        return this.prepareRings([PEOPLE_COLLECTION]);
+    }
+    async requireDevSudo() {
+        const key = await this.connection.api.query.Sudo?.Key?.getValue({ at: "best" });
+        if (!sameKey(key, this.authority.publicKey))
+            throw new Error(`People's sudo key is ${String(key)}, not the dev chain's ${DEV_SUDO} (${this.authority.address}): the lab prepares People's rings on a development chain only`);
+    }
+    async prepareRings(collections) {
+        const { tx, query } = this.connection.api;
+        const sudo = tx.Sudo?.sudo;
+        if (!sudo)
+            throw new Error("People runtime has no Sudo.sudo: the lab cannot prepare its rings");
+        const sent = [];
         const exponent = Enum(PEOPLE_CHUNKS.ringExponent);
         for (const [index, page] of PEOPLE_CHUNKS.pages.entries()) {
             if ((await query.ChunksManager.Chunks.getValue(exponent, index, { at: "best" })) !== undefined)
@@ -209,9 +223,11 @@ export class PeopleAttesterChain {
             const authorized = tx.Utility.dispatch_as({ as_origin: Enum("system", Enum("Authorized")), call: add.decodedCall });
             sent.push(await this.executor.submit(`Add ${PEOPLE_CHUNKS.ringExponent} ZK chunk page ${index}`, sudo({ call: authorized.decodedCall }), this.authority.signer));
         }
-        const size = Number(await query.Members.OnboardingSize.getValue(PEOPLE_COLLECTION, { at: "best" }));
-        if (size !== 1)
-            sent.push(await this.executor.submit(`Onboard people one at a time (onboarding size ${size} to 1)`, sudo({ call: tx.Members.set_onboarding_size({ identifier: PEOPLE_COLLECTION, onboarding_size: 1 }).decodedCall }), this.authority.signer));
+        for (const collection of collections) {
+            const size = Number(await query.Members.OnboardingSize.getValue(collection, { at: "best" }));
+            if (size !== 1)
+                sent.push(await this.executor.submit(`Onboard people one at a time in ${collectionName(collection)} (onboarding size ${size} to 1)`, sudo({ call: tx.Members.set_onboarding_size({ identifier: collection, onboarding_size: 1 }).decodedCall }), this.authority.signer));
+        }
         return sent;
     }
     close() {

package/composition/src/previewnet-genesis.d.ts

@@ -0,0 +1,62 @@
+import type { TopologyChain } from "@parity/product-lab/domain";
+import { type EngineCheckoutSettings, type EngineEnvironmentSettings, type EngineTopology } from "@parity/product-lab/env-engine";
+import type { EnvironmentProvider, TopologyEnvironment } from "@parity/product-lab/ports/environment";
+import type { SystemPorts } from "@parity/product-lab/ports/system";
+/** The environment's id unless the lab names another, after the copies' naming (`<network>-copy`). */
+export declare const PREVIEWNET_GENESIS_ID = "previewnet-genesis";
+/** Its name unless the lab names another. */
+export declare const PREVIEWNET_GENESIS_LABEL = "Previewnet from genesis";
+/** The chains it starts unless the lab names others: what a hosted app needs (hosts route People, Asset Hub, Bulletin). */
+export declare const PREVIEWNET_GENESIS_CHAINS: readonly TopologyChain[];
+/** The cache folder its Engine checkout is prepared in (beside the copies' `engine/`). */
+export declare const PREVIEWNET_GENESIS_ENGINE_FOLDER = "engine-node-workspace";
+/** The People collections given an onboarding size of 1 on genesis: the lite people collection, which new people join. */
+export declare const PREVIEWNET_GENESIS_RING_COLLECTIONS: readonly string[];
+/** How long a start may take before Engine's dashboard answers (a first start downloads binaries). */
+export declare const PREVIEWNET_GENESIS_STARTUP_MS = 1800000;
+/** What a lab may change of the environment. */
+export interface PreviewnetGenesisOptions {
+    readonly id?: string;
+    readonly label?: string;
+    readonly description?: string;
+    /** Previewnet's chains to start (default PREVIEWNET_GENESIS_CHAINS); People is needed for the ring preparation. */
+    readonly chains?: readonly TopologyChain[];
+    /** The lab's cache (default PRODUCT_LAB_CACHE_DIR, else the user's cache): the Engine checkout is its `engine-node-workspace/`. */
+    readonly cacheDir?: string;
+    /** Engine's evidence (logs, session, run manifest), relative to lab.config.ts unless absolute. Default `.product-lab/engine`. */
+    readonly reports?: string;
+    /** Prepare People's rings for new people after each start (default true). */
+    readonly peopleRings?: boolean;
+    /** How long a start may take before Engine's dashboard answers (default PREVIEWNET_GENESIS_STARTUP_MS). */
+    readonly startupTimeoutMs?: number;
+}
+/** What the ring preparation sent, for the evidence. */
+export interface PeopleRingsPrepared {
+    /** Every transaction sent (none when the chain already had all of it). */
+    readonly transactions: readonly {
+        readonly hash: string;
+        readonly block: number;
+    }[];
+    /** The JSON-lines journal of the preparation. */
+    readonly journal: string;
+}
+/** Prepares People's rings on a running genesis network (the default: `PeopleAttesterChain.prepareRings` as //Alice). */
+export type PrepareRings = (people: {
+    readonly ws: string;
+    readonly journalDirectory: string;
+    readonly signal: AbortSignal;
+    readonly system: Partial<SystemPorts>;
+}) => Promise<PeopleRingsPrepared>;
+/** What a start composes (tests replace them; nothing else does). */
+export interface PreviewnetGenesisParts {
+    readonly engine?: (topology: EngineTopology, settings: EngineEnvironmentSettings, system: Partial<SystemPorts>) => TopologyEnvironment;
+    readonly prepareRings?: PrepareRings;
+}
+/** The default ring preparation: //Alice's sudo calls on People, each skipped when the chain already has it. */
+export declare const prepareGenesisRings: PrepareRings;
+/** The Engine checkout settings of the environment `id` with cache `cacheDir`. */
+export declare function previewnetGenesisEngine(id: string, cacheDir: string): EngineCheckoutSettings;
+/** The environment as a provider (what `previewnetGenesis` names and returns under its id). */
+export declare function previewnetGenesisEnvironment(options?: PreviewnetGenesisOptions, parts?: PreviewnetGenesisParts): TopologyEnvironment;
+/** "Previewnet from genesis": an owned Engine network of Previewnet started from genesis on this machine, a new one every start. */
+export declare function previewnetGenesis(options?: PreviewnetGenesisOptions): Record<string, EnvironmentProvider>;

package/composition/src/previewnet-genesis.js

@@ -0,0 +1,127 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { join } from "node:path";
+import { nameEnvironment } from "@parity/product-lab";
+import { ScenarioJournal } from "@parity/product-lab/chain";
+import { engineCheckoutTooling, engineEnvironment, engineProfiles, preparedEngineCheckout, recordedPatch, engineConfiguration, } from "@parity/product-lab/env-engine";
+import { FileEvidenceJournal } from "@parity/product-lab/storage-filesystem";
+import { SystemClock } from "@parity/product-lab/system-node";
+import { productLabCacheDir } from "@parity/product-lab/versions-github";
+import { processEnvironment } from "./create-lab-runtime.js";
+import { PEOPLE_LITE_COLLECTION, PeopleAttesterChain } from "./people-dev/onboarding.js";
+export const PREVIEWNET_GENESIS_ID = "previewnet-genesis";
+export const PREVIEWNET_GENESIS_LABEL = "Previewnet from genesis";
+export const PREVIEWNET_GENESIS_CHAINS = ["people", "asset-hub", "bulletin"];
+export const PREVIEWNET_GENESIS_ENGINE_FOLDER = "engine-node-workspace";
+export const PREVIEWNET_GENESIS_RING_COLLECTIONS = [PEOPLE_LITE_COLLECTION];
+export const PREVIEWNET_GENESIS_STARTUP_MS = 1_800_000;
+const PORT_NAMES = { people: "People", "asset-hub": "Asset Hub", bulletin: "Bulletin", "web3-storage": "Web3 Storage", ethRpc: "eth-rpc", identityBackend: "dub", dashboard: "dashboard" };
+const portWords = (ports) => Object.entries(ports).flatMap(([key, port]) => (port === undefined ? [] : [`${PORT_NAMES[key] ?? key} ${port}`])).join(", ");
+const stamp = () => new Date().toISOString().replace(/[:.]/g, "-");
+export const prepareGenesisRings = async ({ ws, journalDirectory, signal, system }) => {
+    const clock = system.clock ?? new SystemClock();
+    const evidence = new FileEvidenceJournal(journalDirectory).open();
+    const journal = new ScenarioJournal(evidence, () => { }, { clock });
+    const chain = new PeopleAttesterChain(ws, journal, signal);
+    try {
+        await chain.requireDevSudo();
+        const sent = await chain.prepareRings(PREVIEWNET_GENESIS_RING_COLLECTIONS);
+        return { transactions: sent.map((receipt) => ({ hash: receipt.txHash, block: receipt.block.number })), journal: journal.file };
+    }
+    finally {
+        chain.close();
+    }
+};
+export function previewnetGenesisEngine(id, cacheDir) {
+    return { state: join(cacheDir, PREVIEWNET_GENESIS_ENGINE_FOLDER), network: "previewnet", patch: "node-workspace", environment: id };
+}
+export function previewnetGenesisEnvironment(options = {}, parts = {}) {
+    const id = options.id ?? PREVIEWNET_GENESIS_ID;
+    const env = processEnvironment();
+    const cacheDir = options.cacheDir ?? productLabCacheDir({ PRODUCT_LAB_CACHE_DIR: env.get("PRODUCT_LAB_CACHE_DIR"), XDG_CACHE_HOME: env.get("XDG_CACHE_HOME") });
+    const chains = [...(options.chains ?? PREVIEWNET_GENESIS_CHAINS)];
+    const topology = engineProfiles.genesisSubset({ chains });
+    const engine = previewnetGenesisEngine(id, cacheDir);
+    const rings = options.peopleRings !== false && chains.includes("people");
+    const makeEngine = parts.engine ?? engineEnvironment;
+    const prepareRings = parts.prepareRings ?? prepareGenesisRings;
+    return {
+        label: options.label ?? PREVIEWNET_GENESIS_LABEL,
+        description: options.description ?? `Previewnet's ${chains.join(", ")} started from genesis on this machine by Engine (a relay chain, collators and Engine's services), a new network every start, on Engine's default ports (${portWords(topology.ports)}, and its others): one Engine network per machine at a time${rings ? "; People's rings are prepared for new people once it is ready" : ""}`,
+        topology,
+        offer: topology.offer,
+        tooling: engineCheckoutTooling(engine),
+        async start(context) {
+            const system = context.system ?? {};
+            if (!system.syncCommands)
+                throw new Error(`The ${id} environment checks its Engine checkout through the lab's sync command adapter (SystemPorts.syncCommands), which this lab lacks`);
+            const prepared = preparedEngineCheckout(engine, system.syncCommands);
+            const environment = makeEngine(topology, {
+                engineConfig: engineConfiguration.parse({
+                    checkout: prepared.checkout,
+                    workspace: prepared.workspace,
+                    network: "previewnet",
+                    mode: "genesis",
+                    extraPath: prepared.extraPath,
+                    enginePatch: recordedPatch(prepared.build),
+                    startupTimeoutMs: options.startupTimeoutMs ?? PREVIEWNET_GENESIS_STARTUP_MS,
+                }),
+                ...(options.reports ? { reports: options.reports } : {}),
+            }, system);
+            const running = await environment.start(context);
+            const preparations = [];
+            const prepare = async (signal) => {
+                if (!rings)
+                    return;
+                const ws = running.endpoints?.people;
+                if (!ws)
+                    throw new Error(`The ${id} environment started without a People endpoint, so People's rings cannot be prepared`);
+                const reports = running.provenance?.reports;
+                const journalDirectory = join(typeof reports === "string" ? reports : join(context.root, ".product-lab", "engine"), `people-rings-${stamp()}`);
+                context.progress?.("People: preparing its rings for new people (ZK chunk pages, one person at a time)");
+                const done = await prepareRings({ ws, journalDirectory, signal, system });
+                preparations.push(done);
+                context.progress?.(`People: rings ready (${done.transactions.length} transaction${done.transactions.length === 1 ? "" : "s"} sent)`);
+            };
+            try {
+                await prepare(context.signal);
+            }
+            catch (error) {
+                await running.close();
+                throw error;
+            }
+            const wrapped = Object.defineProperties({}, Object.getOwnPropertyDescriptors(running));
+            const last = () => preparations.at(-1);
+            Object.defineProperties(wrapped, {
+                notices: {
+                    enumerable: true,
+                    get: () => {
+                        const done = last();
+                        const words = done && (done.transactions.length ? `${done.transactions.length} transaction${done.transactions.length === 1 ? "" : "s"} by //Alice (${done.journal})` : "nothing to send, the chain had it");
+                        return [...(running.notices ?? []), ...(words ? [`People's rings prepared for new people: ${words}`] : [])];
+                    },
+                },
+                provenance: {
+                    enumerable: true,
+                    get: () => ({ ...(running.provenance ?? {}), ...(last() ? { peopleRings: last() } : {}) }),
+                },
+            });
+            if (running.reset) {
+                const reset = running.reset.bind(running);
+                Object.defineProperty(wrapped, "reset", {
+                    enumerable: true,
+                    value: async (signal) => {
+                        preparations.length = 0;
+                        await reset(signal);
+                        await prepare(signal);
+                    },
+                });
+            }
+            return wrapped;
+        },
+    };
+}
+export function previewnetGenesis(options = {}) {
+    const id = options.id ?? PREVIEWNET_GENESIS_ID;
+    return { [id]: nameEnvironment(previewnetGenesisEnvironment(options), { kind: "fast-local", label: options.label ?? PREVIEWNET_GENESIS_LABEL }) };
+}

package/core/application/src/runs/failure-rules.js

@@ -104,7 +104,7 @@ const RULES = [
         id: "environment-unreachable",
         layer: "environment",
         confidence: "medium",
-        test: /(ECONNREFUSED|ECONNRESET|WebSocket|socket hang up|endpoint|not running|cannot start|failed to start|spawn|EADDRINUSE|address already in use|Environment \S+ reports no|No \S+ lab was started for|genesis|baseline)/i,
+        test: /(ECONNREFUSED|ECONNRESET|WebSocket|socket hang up|endpoint|not running|cannot start|failed to start|spawn|EADDRINUSE|address already in use|Environment \S+ reports no|No \S+ lab was started for|share a genesis|duplicate genesis|baseline requires|baseline integrity mismatch|fast[- ]baseline|is another chain|genesis \S+ is not)/i,
         expected: () => "the environment is running and reachable",
         actual: (m) => `it is not (${m[1]})`,
         hint: "Infrastructure, not the product: a chain, service or process is down or misconfigured. env_status and tail_logs show which; a negative control failing this way is not a valid result.",
@@ -168,10 +168,11 @@ export function classifyFailure(error, title, hook = false, control = false) {
             actual: firstLine(error),
             hint: "A Before/After hook failed: the environment or the scenario context, not a scenario step. tail_logs on the run.",
         };
+    const message = messageLines(error);
     for (const rule of RULES) {
         if (control && rule.layer === "environment")
             continue;
-        const match = rule.test.exec(error);
+        const match = rule.test.exec(message);
         if (!match)
             continue;
         const generic = genericValues(error);
@@ -194,4 +195,6 @@ export function classifyFailure(error, title, hook = false, control = false) {
         hint: "No rule matched this error. Read the full error, step_evidence for the step and tail_logs for the run.",
     };
 }
+const STACK_FRAME = /^\s+at\s.*(?::\d+:\d+\)?|\((?:<anonymous>|native)\)|<anonymous>)\s*$/;
+const messageLines = (error) => error.split("\n").filter((line) => !STACK_FRAME.test(line)).join("\n");
 export const firstLine = (text) => text.split("\n").find((line) => line.trim())?.trim().slice(0, 500) ?? "";

package/entrypoints/cli/src/setup-commands.d.ts

@@ -1,7 +1,7 @@
 import type { LabRuntime } from "@parity/product-lab/ports/driving";
 import type { SyncCommandRunner } from "@parity/product-lab/ports/system";
 import type { VariableReader } from "./environment.js";
-export declare const FETCH_USAGE = "Usage: product-lab fetch [--config lab.config.ts] [--environment <id>]... [--json]\n                         [--engine-repository <url|path>] [--engine-ref <ref>] [--no-engine-patch]\n\nDownload and verify every release file the lab's lab.lock.json pins for this machine (polkadot-omni-node,\nruntime Wasm) into the shared cache (PRODUCT_LAB_CACHE_DIR, default ~/.cache/product-lab). A file already\ncached and verified is not downloaded again.\n\nThen prepare, in the same cache, what the lab's default environment needs on this machine and never makes\nitself, and what each --environment needs (repeat it, or --environment all): a local copy of a network\n(paseo-copy, previewnet-copy) starts from an Engine checkout, cloned at the tested stock Engine release (or --engine-ref), with no lab patch,\nbuilt, with its network's binaries and the pinned dot CLI (<cache>/engine; Git and network access, a few\nminutes and about 900 MB the first time). One already prepared is only checked. Another Engine:\n  --engine-repository <url|path>  clone it from this Git URL or local repository instead of GitHub\n  --engine-ref <ref>              this commit, branch or tag instead of the tested release; starts use it as\n                                  prepared; doctor names it as not the tested release (cache:engine) and fails\n                                  when the copy is asked for (the default environment or --environment)\n  --no-engine-patch               compatibility flag; stock Engine is the default and the old patch is retired\n\nExit 0 when every file is cached and everything asked for is prepared, 1 otherwise.\nIn the product-lab checkout, `bun run setup` runs this for every example.";
+export declare const FETCH_USAGE = "Usage: product-lab fetch [--config lab.config.ts] [--environment <id>]... [--json]\n                         [--engine-repository <url|path>] [--engine-ref <ref>] [--no-engine-patch]\n\nDownload and verify every release file the lab's lab.lock.json pins for this machine (polkadot-omni-node,\nruntime Wasm) into the shared cache (PRODUCT_LAB_CACHE_DIR, default ~/.cache/product-lab). A file already\ncached and verified is not downloaded again.\n\nThen prepare, in the same cache, what the lab's default environment needs on this machine and never makes\nitself, and what each --environment needs (repeat it, or --environment all): a local copy of a network\n(paseo-copy, previewnet-copy) starts from an Engine checkout, cloned at the tested stock Engine release (or --engine-ref), with no lab patch,\nbuilt, with its network's binaries and the pinned dot CLI (<cache>/engine; Git and network access, a few\nminutes and about 900 MB the first time). Previewnet from genesis (previewnet-genesis) starts from its own\ncheckout, the same release with the node-workspace patch the package ships (<cache>/engine-node-workspace).\nOne already prepared is only checked. Another Engine:\n  --engine-repository <url|path>  clone it from this Git URL or local repository instead of GitHub\n  --engine-ref <ref>              this commit, branch or tag instead of the tested release; starts use it as\n                                  prepared; doctor names it as not the tested release (cache:engine) and fails\n                                  when the copy is asked for (the default environment or --environment)\n  --no-engine-patch               compatibility flag; stock Engine is the default and the old patch is retired\n\nExit 0 when every file is cached and everything asked for is prepared, 1 otherwise.\nIn the product-lab checkout, `bun run setup` runs this for every example.";
 export declare const DOCTOR_USAGE = "Usage: product-lab doctor [--config lab.config.ts] [--environment <id>]... [--json]\n\nWhat this machine has and lacks to run the lab: Node.js, the shared cache, the lab's locked release files,\nthe selected browser (the full Chromium executable for the default launcher), what its environments need\nprepared (the Engine checkout of a local copy of a network: required for the default environment and each\n--environment, a note for the others), the Engine build the shared cache holds checked against the pinned\nrelease whatever the lab declares (cache:engine: another build, such as the retired patched one, fails where the lab\nwould start from it, as the Engine checkout line does, else a note; a cache holding no Engine says nothing) and the hosts its people run on (in a product, the truAPI WASM test host the package installs and the truAPI CLI host's locked official release:\ncached or not, what it provides; in the product-lab checkout, also Bun and its truAPI CLI host). Then what fits\nthis machine, from its cores, memory and free disk: the lab's local copy of a network as Full or Light, how\nmany people at once on each environment, and whether the cache is set up. Starts nothing, downloads nothing. Exit 0 when everything is\npresent, 1 otherwise, with the one command that fixes it; what fits never changes the exit code.";
 /** The command that fixes a missing piece, for the product-lab checkout. */
 export declare const SETUP_FIX = "bun run setup";

package/entrypoints/cli/src/setup-commands.js

@@ -20,7 +20,9 @@ Then prepare, in the same cache, what the lab's default environment needs on thi
 itself, and what each --environment needs (repeat it, or --environment all): a local copy of a network
 (paseo-copy, previewnet-copy) starts from an Engine checkout, cloned at the tested stock Engine release (or --engine-ref), with no lab patch,
 built, with its network's binaries and the pinned dot CLI (<cache>/engine; Git and network access, a few
-minutes and about 900 MB the first time). One already prepared is only checked. Another Engine:
+minutes and about 900 MB the first time). Previewnet from genesis (previewnet-genesis) starts from its own
+checkout, the same release with the node-workspace patch the package ships (<cache>/engine-node-workspace).
+One already prepared is only checked. Another Engine:
   --engine-repository <url|path>  clone it from this Git URL or local repository instead of GitHub
   --engine-ref <ref>              this commit, branch or tag instead of the tested release; starts use it as
                                   prepared; doctor names it as not the tested release (cache:engine) and fails

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/product-lab",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Run and test Polkadot products against real local chains, hosts and browsers: the framework and the product-lab CLI.",
   "license": "Apache-2.0",