@parity/product-lab 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @parity/product-lab
 
+## 0.2.0
+
+### Minor Changes
+
+- 36bf358: Breaking change: `publishedBundle` now reads only the release asset record, requires a valid SHA-256 digest, and returns no snapshot. `PublishedBundle.digest` is required and `snapshot` is optional. Read bite time, blocks and runtimes from the verified installed or staged manifest after downloading. This removes the dependency on where `manifest.json` appears in the archive.
+  
+  Refresh compares verified bite times before changing saved state. Background checks and explicit refresh download only when the published digest is new or unknown; an already staged matching bundle boots without another download. Older or equal downloads are not staged beside the installed bundle. The digest is a cache key, not an integrity check; existing manifest, snapshot-size, decompression and marker checks still apply. `PRODUCT_LAB_FORK_BUNDLE=keep` still downloads nothing.
+  
+  An installed bundle with a missing or stale completion marker learns the digest after one download when its manifest matches and its snapshot sizes and decompression pass verification. Incomplete bundles remain unknown and continue downloading.
+
+### Patch Changes
+
+- 759dc0b: Allow repository users to prepare Engine with the optional node-workspace fix, so previewnet collators find binaries in a custom run workspace. Keep stock Engine as the default and verify the selected patch before reuse and launch, including saved forks. Limit node base-path recovery to node launchers.
+
 ## 0.1.2
 
 ### Patch Changes

package/adapters/environment/engine/README.md

@@ -33,7 +33,7 @@ use to reach an Engine network. Imported from the original lab.
 | `engine/network-reset.ts` | `resetPersistentNetwork(directory, { stop, sessionFile, commands })` (29 September 2026): stops the saved network, removes its data and network.json, and restores the first boot's template as a new generation (`method: "template"`, with `stopMs` and the copy); a workspace without a template gets `method: "fork-again"` with the reason, and the caller's next `persistentNetwork` forks again (the old path). Notes' `paseo-copy` reset uses it. The persistent network's `stop()` (`persistent-network.ts`) now stops every saved process at once (`stopTogether`; on Notes' fork 3.8 s and 4.2 s against 4.5 s one after another), each with its own stop policy, every failure reported together (`tests/stop-together.test.ts`) |
 | `engine/runtime-upgrade.ts` | An in-place runtime upgrade of one chain of a running network (relay, People, Asset Hub, Bulletin): `upgradeRuntime(request)` runs Engine's own `ppn upgrade <chain> <wasm> --ws <loopback> --enact-timeout <min>` (with `--allow-same-spec` for the same spec or `withoutChecks`; the caller decides whether Engine's authorization path applies to its network) as a recorded tree of the network's registry through `runEnginePrepare`, writes its code through the injected `FileSystem.writePrivateBytes`, and judges the result on the chain: `observeRuntime(rpc, ws)` before and after (finalized `:code` hash, spec, block, and `System.LastRuntimeUpgrade`, decoded by `decodeLastRuntimeUpgrade`, which says the new runtime's migrations ran). While Engine waits for enactment, the chain is read every 5 s: an authorization dropped with nothing scheduled and the code unchanged (`System.RejectedInvalidAuthorizedUpgrade`: another chain's runtime, a lower spec), which Engine's tool does not notice until its enact timeout, stops the wait at once as a failure. Outcomes: `already-running` (nothing submitted), `upgraded` (the chain runs exactly the code, `migrated` true or false), `failed` (with `unchanged`: the chain still runs its old code). `recordRuntimeUpgrade(files, …)` rewrites a persistent network's saved session (`network.json` and the session file) on purpose, since `checkEngineSession` refuses any runtime change it was not told about, and appends `runtime-upgrades.json` |
 | `engine/fork-bundle.ts` | A fork bundle is reused only once verified complete. `verifyForkBundle(dir)`: `manifest.json` parses, every snapshot it names is there at the size it records (`snapshotBytes`, written by every bite since Engine v0.8.0; else one snapshot per chain) and decompresses to its end (3.5 s for the 642 MB Paseo bundle). `markForkBundle` writes `.product-lab-complete` (the manifest's sha256, each snapshot's size); `markedComplete` holds while both match. `forkBundleState(bundle)`: complete, absent, or incomplete; an unmarked bundle (fetched before this check, or copied in) is verified once and marked. A start's fetch or bite writes into `<bundle>.incoming` (cleared first; `EngineCommand.installs`), and `installIncomingBundle` verifies it, marks it and renames it into place after the command exits 0, so a fetch or bite stopped part way never leaves a bundle that is reused, and a failed one leaves the bundle in place unchanged. `acquireForkBundleLock` (`<bundle>.lock`, through the injected `LockManager`) is held from the bundle's check to the end of the preparatory commands: a second start from one workspace waits, then finds it complete. A start without isolation, where Engine's own `ppn start` fetches a missing bundle, is not covered |
-| `engine/published-bundle.ts` | Engine's published fork bundles (the rolling `PPN_REPO@PPN_BITE_TAG` pre-release of the checkout's `config/versions.env`, `engineReleaseSettings`): `publishedBundle({ files, checkout, network, fetch })` (bounded by `timeoutMs`, default 180 000 ms, with the caller's optional `signal`) reads the asset record from GitHub's API and the bundle's `manifest.json` by streaming at most the first 48 MiB of the compressed tarball (an HTTP range, stopping once `manifest.json` is read), so what is published is known without downloading it (under `PRODUCT_LAB_FORK_BUNDLE=keep` the background check never calls it: `engine/fork-refresh.ts`); the caller passes `fetch` (the public-endpoint opt-in) and the `FileSystem` system port for the checkout settings and staged bundles. `startPrefetch` downloads it with Engine's own `ppn fork fetch-bundle` into `fork-bundle-<network>.next.partial` at background priority (`backgroundPriority`: macOS `taskpolicy -c utility`, else `nice -n 19`) as a recorded process of the caller's registry; `finishPrefetch` verifies it complete and marks it (`engine/fork-bundle.ts`; an incomplete download is removed), then `completePrefetch` stages it (`.next`, `stagedBundle`, which offers only a verified one); `installStagedBundle` makes it the bundle new forks start from, keeping the old one until `discardPrevious` or `restorePrevious`. `currentBundle`, `bittenAfter`, `prefetchActive`, `bundleLocations` |
+| `engine/published-bundle.ts` | Engine's published fork bundles (the rolling `PPN_REPO@PPN_BITE_TAG` pre-release of the checkout's `config/versions.env`, `engineReleaseSettings`): `publishedBundle({ files, checkout, network, fetch })` (bounded by `timeoutMs`, default 180 000 ms, with the caller's optional `signal`) reads only the release asset record from GitHub's API and requires a `sha256:` digest with 64 lowercase hex digits; it never requests the archive. `PublishedBundle.digest` is required and `snapshot` is optional and absent from lookup. Read bite time, blocks and runtimes from `currentBundle` or `stagedBundle` after a verified download. `manifestFromTarHead`, `TarManifestScanner` and `MANIFEST_SEARCH_BYTES` remain exported for existing callers but are unused by lookup. Under `PRODUCT_LAB_FORK_BUNDLE=keep` the background check uses its separate release-record-only report; the caller passes `fetch` (the public-endpoint opt-in) and the `FileSystem` system port for the checkout settings and staged bundles. `startPrefetch` downloads it with Engine's own `ppn fork fetch-bundle` into `fork-bundle-<network>.next.partial` at background priority (`backgroundPriority`: macOS `taskpolicy -c utility`, else `nice -n 19`) as a recorded process of the caller's registry; `finishPrefetch` verifies it complete and marks it (`engine/fork-bundle.ts`; an incomplete download is removed), then `completePrefetch` stages it (`.next`, `stagedBundle`, which offers only a verified one); `installStagedBundle` makes it the bundle new forks start from, keeping the old one until `discardPrevious` or `restorePrevious`. `currentBundle`, `bittenAfter`, `prefetchActive`, `bundleLocations` |
 | `engine/fork-freshness.ts`, `engine/fork-refresh.ts`, `engine/fork-updates.ts` | Freshness, `--update-runtime` and `--refresh` for any saved Engine fork (fixture sharing, 30 September 2026, backlog 17c). They were lifted from an example, which now wraps them. State: `forkState` reads what a saved fork runs: its saved session, `runtimes.json` and its bite. `liveEndpoints` reads the public RPCs from Engine's network file; a relative one (previewnet's `relay/alice`, `people`) resolves under the file's `bite.source` as `wss://` (`resolveNetworkRpc`, as Engine's bite does). Freshness line: `freshness` is pure: it gives the age, the blocks behind live, and each chain whose spec or code changed, ending with the update command. The live read is injected as `LiveRuntimeReader`; the composition root's is `readLiveRuntimes`. `--update-runtime`: `updateForkRuntimes` applies each changed live runtime in place through `upgradeRuntime`. The code comes from an injected `LiveCodeFetcher`, checked against its hash. It then records the upgrade and waits `settleBlocks`. It refuses without a live read or a sudo key. Other pieces: `recordForkRuntimes`. `prefetchNewerState` fetches a newer published state in the background and never rejects. `PRODUCT_LAB_FORK_BUNDLE` (29 October 2026, read through the `EnvironmentVariables` port, so `savedForkUpdates` and a lab's own wrapper get it too): `fresh` or unset as described; `keep` reads only the release record from GitHub's API (no asset bytes, no range, nothing staged, no `ppn fork fetch-bundle`) and logs one line with the kept bundle's bite, its age, a newer state already downloaded, and the asset's `updated_at` when more than 6 hours after that bite (an upload within that is the bite's own); a record or local manifest that cannot be read is said, and the lab carries on. Surrounding white space is ignored; any other value logs a warning with the fix and checks nothing. `--refresh` and commands run by hand are the same under both. `tests/fork-bundle-keep.test.ts`. `prepareRefresh` sets the old fork aside for the newest published state; a lab record is carried across with `carry`. `commit` or `rollback` ends it. For a lab's start: `savedForkUpdates(options)` combines these into three calls. Before the start it runs `--refresh` when asked, and runs the live read and line beside the start. `started(target)` runs `--update-runtime` before anything connects, records the runtimes, commits a refresh and prefetches. `failed()` rolls a refresh back. `liveRpc` (3 October 2026): the lab's own RPC per chain for the live reads, over the network file's. `upgradeToLive(target, signal)` serves `networkSnapshots({ upgrade })` for `fixture refresh`. `tests/fork-freshness.test.ts` |
 | `engine/owned-environment.ts` | `ownedEngineEnvironment`: owned Engine + consumer app sessions as one resettable environment; its local `engineSessionEnvironment` forwards optional app surfaces across reset and closes the current sessions and Engine once |
 | `engine/network-plan.ts`, `engine/persisted-data.ts`, `engine/eth-rpc-probe.ts` | The persistent network's phases around `persistentNetwork`, split out of `persistent-network.ts`, which still exports their public names: the saved plan (`NetworkPlan`, `resumePlan`, `isolatedPlan`, `completePlan`, `planFacts`, `ENGINE_PORTS_FILE`); the resume's preconditions (`hasChainDatabase`, `missingPersistedData`, `requirePersistedData`, `restateEngineLocalEnv`, `engineCheckout`, `restateEnginePorts`, `portNames`, `requireFreePorts`; and, in `engine/saved-tooling.ts`, `missingSavedTooling` and `requireSavedTooling`: every command, what the lab's launchers in `<network>.isolation` exec, and the Engine checkout are on this machine); eth-rpc's health after a start (`probeEthRpc`, `EthRpcStatus`) |
@@ -45,9 +45,9 @@ 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. Retired patched 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` | 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/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 started from a stock build writes `enginePatch: "none"` in its own engine.json |
+| `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) |
 | `versions/engine-versions.ts` | Phase 6: `engineVersionPlan(topology, resolution, { snapshot, now })` (what Engine honours: runtimes read from the network it forks; refused as unsupported: released or git runtimes, resolved binaries, a runtime override on the same chain, a network runtime on genesis, a published bundle that `SnapshotFreshness` finds stale or on another runtime), `engineVersionCheck(session, plan, snapshot)` (each chain's observed `:code` hash, spec, genesis and bite block against the resolution), `VersionedEngineDependency` (checks every start and reset, stops and throws `EngineVersionMismatch` on other code), `engineVersionsRecord`, `workspaceVersionPlan` (persistent networks). Engine cannot fork at a chosen block: a `deployed` resolution is honoured by runtime, and the bite blocks are recorded beside the resolved block |
 
@@ -121,3 +121,21 @@ a taken port named, and the readiness wait's reasons). With the Node
 system adapters: the lock on disk, `tools/verify/tests/scenario-lock.test.ts`; an owned Engine started, awaited and
 stopped against a stand-in checkout, and a stock build passing the pre-start check while legacy patched configurations are refused, `tools/verify/tests/engine-owned-start.test.ts`; an Engine session routing the
 truAPI CLI host, `tools/verify/tests/host-routes.test.ts`.
+
+Native-node workspace regression: `node --import tsx --test adapters/environment/engine/tests/node-workspace.test.ts`
+from the repository root. This runs the actual before/after shell launcher extracted
+from the full-context manifest patch, under `env -i` with temporary stub binaries,
+and checks the actual TOML writer. No chain, user workspace or Engine cache is used.
+
+Lookup cannot compare bite times before download. Under `fresh`, background checks and explicit `--refresh` download
+only when the published digest is new or unknown, then compare verified bite times before touching saved state.
+A matching installed or staged bundle skips the download; `--refresh` boots a matching staged newer bite. A download
+no newer than the installed bundle is not staged. Markers from older versions remain readable; an identical bundle
+needs one download to record its digest. Missing or stale markers are rebuilt only after the installed manifest,
+snapshot sizes and decompression pass verification. When keeping an equal bite, the digest transfers only if manifest hashes
+match. A changed manifest at the same bite stays unknown and downloads on each start until Engine publishes a newer bite.
+
+The marker's optional `assetDigest` is a cache key, not an integrity check. Engine owns and removes the tarball;
+the manifest, snapshot-size, decompression and `manifestSha256` checks still protect bundle completeness. The release
+digest is checked again after downloading, and is recorded only if unchanged; a racing release replacement or a failed
+confirmation costs another download rather than skipping a needed one. `keep` still downloads nothing.

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

@@ -66,6 +66,7 @@ export declare const engineConfiguration: z.ZodObject<{
     enginePatch: z.ZodDefault<z.ZodEnum<{
         none: "none";
         "owned-processes": "owned-processes";
+        "node-workspace": "node-workspace";
     }>>;
     recordProgress: z.ZodDefault<z.ZodBoolean>;
     nodeSupervision: z.ZodDefault<z.ZodBoolean>;

package/adapters/environment/engine/src/engine/fork-bundle.d.ts

@@ -17,7 +17,7 @@ export type BundleCheck = {
  */
 export declare function verifyForkBundle(directory: string, signal?: AbortSignal): Promise<BundleCheck>;
 /** Record that `directory` was verified complete (written to a temporary name, then renamed: never half a marker). */
-export declare function markForkBundle(directory: string, snapshots: Record<string, number>, source: string): void;
+export declare function markForkBundle(directory: string, snapshots: Record<string, number>, source: string, assetDigest?: string): void;
 /**
  * True when `directory` carries the marker and still matches it: the same manifest, every snapshot at its size. A
  * missing or unparsable marker, manifest or snapshot is "not marked": the caller verifies the bundle again. Any other

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

@@ -67,8 +67,8 @@ export async function verifyForkBundle(directory, signal) {
     }
     return { complete: true, snapshots };
 }
-export function markForkBundle(directory, snapshots, source) {
-    const marker = { manifestSha256: sha256(join(directory, "manifest.json")), snapshots, source, verifiedAt: new Date().toISOString() };
+export function markForkBundle(directory, snapshots, source, assetDigest) {
+    const marker = { ...(assetDigest ? { assetDigest } : {}), manifestSha256: sha256(join(directory, "manifest.json")), snapshots, source, verifiedAt: new Date().toISOString() };
     const file = join(directory, BUNDLE_MARKER);
     writeFileSync(`${file}.tmp`, `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
     renameSync(`${file}.tmp`, file);

package/adapters/environment/engine/src/engine/fork-refresh.d.ts

@@ -2,10 +2,7 @@ import type { ForkSnapshot } from "@parity/product-lab/domain/versions";
 import type { EnvironmentVariables, FileSystem, Logger, OwnedProcesses } from "@parity/product-lab/ports/system";
 import { type ForkUpdateCommands } from "./fork-freshness.js";
 import { type PublishedBundle } from "./published-bundle.js";
-/**
- * How long the check for a newer published state may take: it streams the bundle until its manifest (the 27
- * September bundle: 8.8 MB read, 67 s at the 180 KB/s one machine had then). It runs in the background.
- */
+/** How long the background release-record lookup may take. Archive bytes are read only by the download. */
 export declare const PUBLISHED_CHECK_MS = 300000;
 /** What a lab start tells about the published state (the CLI line and the lab window's notice). */
 export declare function newerStateNotice(snapshot: Pick<ForkSnapshot, "bittenAt">, ready: boolean, commands?: ForkUpdateCommands): string;
@@ -29,8 +26,8 @@ export interface PrefetchDeps {
     commands?: ForkUpdateCommands;
 }
 /**
- * While the lab runs: if Engine publishes a state newer than the fork's bite, make it ready for a refresh (already
- * staged or installed: say so; otherwise download it in the background). Never throws; returns when it has decided (the
+ * While the lab runs: offer a newer local bite for refresh, or download the published asset in the background to
+ * compare its verified bite. Never throws; returns when it has decided (the
  * download itself continues).
  */
 export declare function prefetchNewerState(forkBite: Pick<ForkSnapshot, "bittenAt"> | undefined, deps: PrefetchDeps): Promise<PublishedBundle | undefined>;
@@ -68,7 +65,7 @@ export interface RefreshDeps<T = unknown> {
 }
 /**
  * `--refresh`: set the saved fork aside and install the newest published state as the bundle a first start boots,
- * downloading it now unless a background download staged it. Returns undefined, changing nothing, when the fork already
+ * downloading a new or unknown digest to read its verified bite (offline: use a newer local bundle). Returns undefined when the fork already
  * runs the newest published state.
  */
 export declare function prepareRefresh<T>(directory: string, deps: RefreshDeps<T>): Promise<RefreshHandle | undefined>;

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

@@ -3,13 +3,13 @@
 import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { forkState, refreshCommand, shortError } from "./fork-freshness.js";
-import { bittenAfter, bundleLocations, finishPrefetch, currentBundle, discardPrevious, engineReleaseSettings, installStagedBundle, prefetchActive, publishedBundle, restorePrevious, stagedBundle, startPrefetch, } from "./published-bundle.js";
+import { bittenAfter, bundleLocations, bundleAssetDigest, finishPrefetch, currentBundle, discardPrevious, engineReleaseSettings, installStagedBundle, prefetchActive, publishedBundle, restorePrevious, stagedBundle, startPrefetch, } from "./published-bundle.js";
 export const PUBLISHED_CHECK_MS = 300_000;
 export function newerStateNotice(snapshot, ready, commands) {
     const bitten = snapshot.bittenAt.slice(0, 16).replace("T", " ");
     return ready
-        ? `A newer published state of the network (bitten ${bitten} UTC) is downloaded: ${refreshCommand(commands)} makes a new local fork from it in a few minutes (this fork's identities are discarded).`
-        : `A newer published state of the network (bitten ${bitten} UTC) exists; downloading it in the background at low priority so ${refreshCommand(commands)} only boots.`;
+        ? `A newer published state of the network (bitten ${bitten} UTC) is downloaded; ${refreshCommand(commands)} checks the newest published state before making a new local fork (this fork's identities are discarded).`
+        : `A newer published state of the network (bitten ${bitten} UTC) exists; downloading it in the background at low priority so its verified bite is available for ${refreshCommand(commands)}.`;
 }
 export async function prefetchNewerState(forkBite, deps) {
     try {
@@ -62,7 +62,7 @@ async function reportKeptBundle(forkBite, deps) {
     const kept = installed ?? forkBite;
     const parts = [kept ? `bitten ${kept.bittenAt.slice(0, 16).replace("T", " ")} UTC, ${age(kept.bittenAt, Date.now())} old` : "no bundle installed yet"];
     if (staged && (!kept || bittenAfter(staged, kept)))
-        parts.push(`a newer state (bitten ${staged.bittenAt.slice(0, 16).replace("T", " ")} UTC) is downloaded, so ${refreshCommand(deps.commands)} only boots`);
+        parts.push(`a newer state (bitten ${staged.bittenAt.slice(0, 16).replace("T", " ")} UTC) is downloaded; ${refreshCommand(deps.commands)} checks the newest published state before making a new fork`);
     parts.push(...problems);
     const line = `Keeping the fork bundle of ${network} on this machine (${FORK_BUNDLE_SETTING}=keep; ${parts.join("; ")})`;
     const asset = `fork-bundle-${network}.tar.gz`;
@@ -92,6 +92,21 @@ async function reportKeptBundle(forkBite, deps) {
     else
         logger.info(`${line}.`);
 }
+function publishedIsLocal(deps, published, staged, installed) {
+    const { next, current } = bundleLocations(deps.engine.workspace, deps.network);
+    return !!((staged && bundleAssetDigest(deps.files, next) === published.digest) || (installed && bundleAssetDigest(deps.files, current) === published.digest));
+}
+async function confirmedAssetDigest(deps, before) {
+    try {
+        const after = await publishedBundle({ files: deps.files, checkout: deps.engine.checkout, network: deps.network,
+            fetch: deps.fetch ?? fetch, env: deps.environment.all(), token: deps.environment.get("GITHUB_TOKEN"), signal: "signal" in deps ? deps.signal : undefined, timeoutMs: PUBLISHED_CHECK_MS });
+        return after.digest === before.digest ? before.digest : undefined;
+    }
+    catch (error) {
+        deps.logger.warn(`Could not confirm the downloaded release digest (${shortError(error)}); a later check may download again.`);
+        return undefined;
+    }
+}
 async function prefetchWhenNewer(forkBite, deps) {
     const { engine, network, logger } = deps;
     let published;
@@ -110,23 +125,25 @@ async function prefetchWhenNewer(forkBite, deps) {
         logger.info(`Could not check for a newer published state of ${network} (${shortError(error)}); a later start checks again.`);
         return undefined;
     }
-    if (!bittenAfter(published.snapshot, forkBite))
+    if (!forkBite)
         return published;
     const staged = stagedBundle(deps.files, engine.workspace, network);
     const installed = currentBundle(deps.files, engine.workspace, network);
-    if ((staged && !bittenAfter(published.snapshot, staged)) || (installed && bittenAfter(installed, forkBite) && !bittenAfter(published.snapshot, installed))) {
-        const ready = staged && !bittenAfter(published.snapshot, staged) ? staged : installed;
+    const ready = [staged, installed].filter((entry) => !!entry && bittenAfter(entry, forkBite))
+        .sort((a, b) => Date.parse(b.bittenAt) - Date.parse(a.bittenAt))[0];
+    if (ready) {
         const text = newerStateNotice(ready, true, deps.commands);
         logger.info(text);
         deps.notice(text);
-        return published;
     }
+    if (publishedIsLocal(deps, published, staged, installed))
+        return published;
     const { partial } = bundleLocations(engine.workspace, network);
     if (prefetchActive(deps.files, partial)) {
-        logger.info(`A newer published state of ${network} (bitten ${published.snapshot.bittenAt}) is being downloaded by another lab on this machine.`);
+        logger.info(`The published state of ${network} is being downloaded by another lab on this machine.`);
         return published;
     }
-    const text = newerStateNotice(published.snapshot, false, deps.commands);
+    const text = `Checking the published state of ${network}: downloading it in the background at low priority to read its bite time.`;
     logger.info(`${text} (${Math.round(published.size / 1_000_000)} MB)`);
     deps.notice(text);
     try {
@@ -147,10 +164,17 @@ async function prefetchWhenNewer(forkBite, deps) {
                 return;
             }
             try {
-                const snapshot = await finishPrefetch(deps.files, engine.workspace, network);
-                const done = newerStateNotice(snapshot, true, deps.commands);
-                logger.info(done);
-                deps.notice(done);
+                const digest = await confirmedAssetDigest(deps, published);
+                const snapshot = await finishPrefetch(deps.files, engine.workspace, network, undefined, digest);
+                if (bittenAfter(snapshot, forkBite)) {
+                    const done = newerStateNotice(snapshot, true, deps.commands);
+                    logger.info(done);
+                    deps.notice(done);
+                }
+                else {
+                    logger.info(`The downloaded state of ${network} (bitten ${snapshot.bittenAt}) is not newer than this fork.`);
+                    deps.notice(undefined);
+                }
             }
             catch (error) {
                 logger.warn(`The background download of ${network}'s newer state is unusable (${shortError(error)}); a later start tries again.`);
@@ -172,7 +196,7 @@ export async function prepareRefresh(directory, deps) {
     const saved = fork?.kind === "saved";
     const forkBite = saved && fork.bittenAt ? { bittenAt: fork.bittenAt } : undefined;
     let staged = stagedBundle(deps.files, engine.workspace, network);
-    const installed = currentBundle(deps.files, engine.workspace, network);
+    let installed = currentBundle(deps.files, engine.workspace, network);
     let published;
     try {
         const token = deps.environment.get("GITHUB_TOKEN");
@@ -184,15 +208,10 @@ export async function prepareRefresh(directory, deps) {
             throw new Error(`--refresh could not read the newest published state (${shortError(error)}), and nothing newer than this fork is downloaded. Nothing was changed. Fix: connect to the internet and run it again.`);
         logger.warn(`Could not check GitHub for a newer published state (${shortError(error)}); refreshing from the one downloaded (bitten ${local.bittenAt}).`);
     }
-    const newest = [staged, installed, published?.snapshot].filter((entry) => !!entry).sort((a, b) => Date.parse(b.bittenAt) - Date.parse(a.bittenAt))[0];
-    if (saved && forkBite && newest && !bittenAfter(newest, forkBite)) {
-        logger.info(`--refresh: the fork already runs the newest published state (bitten ${forkBite.bittenAt}); nothing to refresh. Resuming it as it is.`);
-        return undefined;
-    }
-    if (published && (!staged || bittenAfter(published.snapshot, staged)) && (!installed || bittenAfter(published.snapshot, installed))) {
+    if (published && !publishedIsLocal(deps, published, staged, installed)) {
         const registry = deps.processes.open(join(existsSync(directory) ? directory : dirname(directory), existsSync(directory) ? "processes" : "refresh-processes"));
         try {
-            logger.info(`--refresh: downloading the newest published state (bitten ${published.snapshot.bittenAt}, ${Math.round(published.size / 1_000_000)} MB) now; a background download while a lab runs avoids this wait.`);
+            logger.info(`--refresh: downloading the newest published state (${Math.round(published.size / 1_000_000)} MB; bite time is read after verification) now to check the rolling release before changing the saved fork.`);
             const child = await startPrefetch({ engine, network, registry, environment: deps.environment, files: deps.files });
             const onAbort = () => {
                 registry.stop("bundle-prefetch").catch((error) => logger.warn(`Could not stop the interrupted download: ${shortError(error)}`));
@@ -204,13 +223,23 @@ export async function prepareRefresh(directory, deps) {
             deps.signal?.throwIfAborted();
             if (code !== 0)
                 throw new Error(`--refresh: the download failed (exit ${code}; ${registry.logFile("bundle-prefetch")}). Nothing was changed.`);
-            await finishPrefetch(deps.files, engine.workspace, network, deps.signal);
+            const digest = await confirmedAssetDigest(deps, published);
+            await finishPrefetch(deps.files, engine.workspace, network, deps.signal, digest);
             staged = stagedBundle(deps.files, engine.workspace, network);
+            installed = currentBundle(deps.files, engine.workspace, network);
         }
         finally {
             registry.close();
         }
     }
+    const newest = [staged, installed].filter((entry) => !!entry)
+        .sort((a, b) => Date.parse(b.bittenAt) - Date.parse(a.bittenAt))[0];
+    if (saved && forkBite && newest && !bittenAfter(newest, forkBite)) {
+        logger.info(`--refresh: the fork already runs the newest published state (bitten ${forkBite.bittenAt}); nothing to refresh. Resuming it as it is.`);
+        return undefined;
+    }
+    if (!newest)
+        throw new Error("--refresh: no bundle is installed after the download; nothing to boot.");
     if (saved) {
         const registry = deps.processes.open(join(directory, "processes"));
         try {

package/adapters/environment/engine/src/engine/published-bundle.d.ts

@@ -1,9 +1,8 @@
 import type { ForkSnapshot } from "@parity/product-lab/domain";
 import type { EnvironmentVariables, FileSystem, OwnedProcess, OwnedProcesses } from "@parity/product-lab/ports/system";
 /**
- * At most this much of the compressed tarball is read looking for its manifest. The entry order is the bite's
- * file-system order and is not stable: the bundle of 26 September had `manifest.json` second, the one of
- * 27 September after 15.5 MB of chain specs (about 4 MB compressed); the snapshots (hundreds of MB) come later.
+ * Legacy head-reading budget, retained for callers of the tar helpers. Lookup never reads archive bytes.
+ * @deprecated Use publishedBundle for release identity and verifyForkBundle for extracted bundles.
  */
 export declare const MANIFEST_SEARCH_BYTES: number;
 /** `KEY="${KEY:-default}"` lines of Engine's config/versions.env, resolved against `env` as Engine resolves them. */
@@ -18,28 +17,31 @@ export interface PublishedBundle {
     /** The asset's download URL. */
     url: string;
     size: number;
-    /** GitHub's digest of the asset (`sha256:<hex>`), when it reports one. */
-    digest?: string;
+    /** GitHub's validated SHA-256 digest of the complete asset (`sha256:<64 lowercase hex digits>`). */
+    digest: string;
     /** When the asset was last uploaded. */
     updatedAt: string;
-    /** Its manifest: when and at which blocks it was bitten, each chain's runtime. */
-    snapshot: ForkSnapshot;
+    /** Lookup does not read the archive. Read its snapshot from the verified installed or staged manifest instead. */
+    snapshot?: ForkSnapshot;
 }
 /**
  * Scans a tar stream chunk by chunk for `manifest.json` (ustar headers), keeping only the bytes it still needs: the
  * other entries' contents are skipped as they go by. `push` returns the parsed manifest once it is complete.
+ * @deprecated Use publishedBundle for release identity and verifyForkBundle for extracted bundles.
  */
 export declare class TarManifestScanner {
     #private;
     push(chunk: Uint8Array): unknown;
 }
-/** Find `manifest.json` among a tar stream's first entries (ustar headers). */
+/**
+ * Find `manifest.json` among a tar stream's first entries (ustar headers).
+ * @deprecated Use publishedBundle for release identity and verifyForkBundle for extracted bundles.
+ */
 export declare function manifestFromTarHead(tar: Uint8Array): unknown;
 /**
- * What Engine publishes for `network` now: the asset's record and its
- * manifest, read with at most MANIFEST_SEARCH_BYTES of the tarball (streamed until the manifest has gone by). Rejects
- * (naming the host) when GitHub cannot be reached or the release carries no
- * bundle for the network.
+ * What Engine publishes for `network` now: the release asset's record and SHA-256 identity, with no archive request.
+ * Rejects when GitHub cannot be reached, the release has no bundle for the network, or its digest is not SHA-256.
+ * The archive's entry order is irrelevant; read bite time, blocks and runtimes after downloading and verifying it.
  */
 export declare function publishedBundle(input: {
     files: Pick<FileSystem, "readText">;
@@ -49,7 +51,7 @@ export declare function publishedBundle(input: {
     env?: Readonly<Record<string, string | undefined>>;
     token?: string;
     signal?: AbortSignal;
-    /** Bound of the whole read, both requests and the streamed range (default 180 000 ms); on expiry it rejects. */
+    /** Bound of the release-record request (default 180 000 ms); on expiry it rejects. */
     timeoutMs?: number;
 }): Promise<PublishedBundle>;
 /** Where a network's bundle lives in an Engine workspace, the staged newer one, and a download in progress. */
@@ -63,6 +65,8 @@ type BundleFiles = Pick<FileSystem, "exists" | "readJson" | "listDirectory" | "r
 export declare function stagedBundle(files: BundleFiles, workspace: string, network: string): ForkSnapshot | undefined;
 /** The bundle a new fork of this workspace would start from now. */
 export declare function currentBundle(files: BundleFiles, workspace: string, network: string): ForkSnapshot | undefined;
+/** The recorded release cache key; an old or damaged marker has an unknown digest. */
+export declare function bundleAssetDigest(files: Pick<FileSystem, "readJson">, directory: string): string | undefined;
 /** True when `a` was bitten after `b` (either missing: false). */
 export declare function bittenAfter(a: Pick<ForkSnapshot, "bittenAt"> | undefined, b: Pick<ForkSnapshot, "bittenAt"> | undefined): boolean;
 /** A download in progress in `partial`: a file there written within the last minute (another lab's prefetch). */
@@ -97,9 +101,9 @@ export declare function startPrefetch(input: {
  * After the download exited 0: verify it complete and mark it (fork-bundle.ts), then stage it (`completePrefetch`). An
  * incomplete download is removed and rejects, naming what is wrong; the staged and installed bundles are unchanged.
  */
-export declare function finishPrefetch(files: BundleFiles, workspace: string, network: string, signal?: AbortSignal): Promise<ForkSnapshot>;
+export declare function finishPrefetch(files: BundleFiles & Pick<FileSystem, "writePrivateJson">, workspace: string, network: string, signal?: AbortSignal, assetDigest?: string): Promise<ForkSnapshot>;
 /** Move a finished, verified download into place as the staged bundle (replacing an older staged one). */
-export declare function completePrefetch(files: BundleFiles, workspace: string, network: string): ForkSnapshot;
+export declare function completePrefetch(files: BundleFiles & Pick<FileSystem, "writePrivateJson">, workspace: string, network: string): ForkSnapshot;
 /**
  * Make the staged bundle the one new forks start from. The current bundle is
  * kept beside it (`<current>.previous`) until `discardPrevious`, so a failed

package/adapters/environment/engine/src/engine/published-bundle.js

@@ -1,7 +1,8 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { createGunzip, constants as zlib } from "node:zlib";
 import { forkBundleManifestPath, forkSnapshotFrom } from "./fork-snapshot.js";
 import { BUNDLE_MARKER, markForkBundle, verifyForkBundle } from "./fork-bundle.js";
 export const MANIFEST_SEARCH_BYTES = 48 * 1024 * 1024;
@@ -92,65 +93,23 @@ export async function publishedBundle(input) {
     if (!response.ok)
         throw new Error(`GitHub answered ${response.status} for ${repository}@${tag}`);
     const release = (await response.json());
+    if (!release || typeof release !== "object")
+        throw new Error(`${repository}@${tag} release response is not an object`);
     const found = release.assets?.find((entry) => entry.name === asset);
     if (!found)
         throw new Error(`${repository}@${tag} publishes no ${asset}`);
-    const manifest = await manifestFromStream(found.browser_download_url, input.fetch, signal);
+    if (typeof found.digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(found.digest))
+        throw new Error(`${repository}@${tag} ${asset} requires a sha256: digest with 64 lowercase hex digits from GitHub`);
     return {
         repository,
         tag,
         asset,
         url: found.browser_download_url,
         size: found.size,
-        ...(found.digest ? { digest: found.digest } : {}),
+        digest: found.digest,
         updatedAt: found.updated_at,
-        snapshot: forkSnapshotFrom(manifest),
     };
 }
-async function manifestFromStream(url, fetchImpl, signal) {
-    const stop = new AbortController();
-    const response = await fetchImpl(url, {
-        headers: { range: `bytes=0-${MANIFEST_SEARCH_BYTES - 1}`, "user-agent": "product-lab" },
-        signal: signal ? AbortSignal.any([signal, stop.signal]) : stop.signal,
-    });
-    if (!response.ok || !response.body)
-        throw new Error(`the bundle download answered ${response.status}`);
-    const gunzip = createGunzip({ finishFlush: zlib.Z_SYNC_FLUSH });
-    const scanner = new TarManifestScanner();
-    let found;
-    let failure;
-    gunzip.on("data", (chunk) => {
-        if (found !== undefined || failure !== undefined)
-            return;
-        try {
-            found = scanner.push(chunk);
-        }
-        catch (error) {
-            failure = error;
-        }
-    });
-    const reader = response.body.getReader();
-    try {
-        while (found === undefined && failure === undefined) {
-            const { done, value } = await reader.read();
-            if (value)
-                await new Promise((resolve, reject) => gunzip.write(value, (error) => (error ? reject(error) : resolve())));
-            await new Promise((resolve) => gunzip.flush(zlib.Z_SYNC_FLUSH, () => resolve()));
-            if (done)
-                break;
-        }
-    }
-    finally {
-        stop.abort();
-        gunzip.destroy();
-        await reader.cancel().catch(() => undefined);
-    }
-    if (failure !== undefined)
-        throw failure;
-    if (found === undefined)
-        throw new Error(`no manifest.json in the bundle's first ${MANIFEST_SEARCH_BYTES / 1024 / 1024} MB`);
-    return found;
-}
 export function bundleLocations(workspace, network) {
     const current = join(workspace, `fork-bundle-${network}`);
     return { current, next: `${current}.next`, partial: `${current}.next.partial` };
@@ -174,6 +133,17 @@ export function currentBundle(files, workspace, network) {
     const directory = bundleLocations(workspace, network).current;
     return usableBundle(files, directory) ? forkSnapshotFrom(files.readJson(forkBundleManifestPath(workspace, network)), forkBundleManifestPath(workspace, network)) : undefined;
 }
+export function bundleAssetDigest(files, directory) {
+    try {
+        const marker = files.readJson(join(directory, BUNDLE_MARKER));
+        return typeof marker?.assetDigest === "string" && /^sha256:[0-9a-f]{64}$/.test(marker.assetDigest) ? marker.assetDigest : undefined;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return undefined;
+        throw error;
+    }
+}
 export function bittenAfter(a, b) {
     if (!a || !b)
         return false;
@@ -200,14 +170,29 @@ export function startPrefetch(input) {
         env: { ...input.environment.all(), PPN_HOME: input.engine.workspace, PPN_NETWORK: input.network, PATH: path },
     });
 }
-export async function finishPrefetch(files, workspace, network, signal) {
-    const { partial } = bundleLocations(workspace, network);
+export async function finishPrefetch(files, workspace, network, signal, assetDigest) {
+    const { partial, next, current } = bundleLocations(workspace, network);
     const check = await verifyForkBundle(partial, signal);
     if (!check.complete) {
         files.remove(partial);
         throw new Error(`the download in ${partial} is not a complete bundle (${check.problem}); it was removed`);
     }
-    markForkBundle(partial, check.snapshots, "download");
+    markForkBundle(partial, check.snapshots, "download", assetDigest);
+    if (assetDigest) {
+        const downloaded = files.readJson(join(partial, BUNDLE_MARKER));
+        for (const directory of [next, current]) {
+            if (!usableBundle(files, directory))
+                continue;
+            if (bundleAssetDigest(files, directory) === assetDigest)
+                continue;
+            const manifestSha256 = createHash("sha256").update(readFileSync(join(directory, "manifest.json"))).digest("hex");
+            if (manifestSha256 !== downloaded.manifestSha256)
+                continue;
+            const local = await verifyForkBundle(directory, signal);
+            if (local.complete)
+                markForkBundle(directory, local.snapshots, "verified in place", assetDigest);
+        }
+    }
     return completePrefetch(files, workspace, network);
 }
 export function completePrefetch(files, workspace, network) {
@@ -215,6 +200,14 @@ export function completePrefetch(files, workspace, network) {
     if (!verifiedBundle(files, partial))
         throw new Error(`the download in ${partial} is not a verified bundle (no manifest.json, no snapshots or not verified complete)`);
     const snapshot = forkSnapshotFrom(files.readJson(join(partial, "manifest.json")));
+    const staged = stagedBundle(files, workspace, network);
+    const installed = currentBundle(files, workspace, network);
+    const newest = [staged, installed].filter((entry) => !!entry)
+        .sort((a, b) => Date.parse(b.bittenAt) - Date.parse(a.bittenAt))[0];
+    if (newest && !bittenAfter(snapshot, newest)) {
+        files.remove(partial);
+        return newest;
+    }
     files.remove(next);
     if (!files.rename(partial, next))
         throw new Error(`the completed bundle disappeared from ${partial}`);

package/adapters/environment/engine/src/saved-fork/saved-fork-tooling.d.ts

@@ -9,7 +9,7 @@ export declare const savedForkEngineState: (cacheDir: string) => string;
 export declare const savedForkSetupCommand: (fork: SavedFork, settings: Pick<SavedForkSettings, "setupCommand">) => string;
 /**
  * The prepared Engine a saved fork starts from, or `EngineNotPrepared` naming the command that prepares it. A start
- * takes the recorded stock build (`as-prepared`), including an explicitly selected ref. Retired patched records
+ * takes the recorded stock or node-workspace build (`as-prepared`), including an explicitly selected ref. Retired owned-processes records
  * are refused. `ref`: when supplied, also check that commit.
  */
 export declare function savedForkEngine(fork: SavedFork, settings: EngineSettings, commands: SyncCommandRunner, patch?: PreparedEnginePatch, ref?: string): PreparedEngine;

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

@@ -13,9 +13,12 @@ export function engineBuildWords(engine) {
     const ref = build.resolvedRef.slice(0, 12);
     const from = build.repository && build.repository !== defaultEngineRepository ? ` from ${build.repository}` : "";
     const tested = build.resolvedRef === testedEngineRef ? "" : ` (not the tested ${testedEngineRef.slice(0, 12)}: \`product-lab fetch\` without --engine-ref prepares it)`;
-    return recordedPatch(build) === "none"
+    const patch = recordedPatch(build);
+    return patch === "none"
         ? `stock Engine ${ref}${from}${tested}, ${engine.checkout}`
-        : `retired patched Engine ${ref}${from}; prepare stock Engine again, ${engine.checkout}`;
+        : patch === "node-workspace"
+            ? `Engine ${ref}${from} with node-workspace patch, ${engine.checkout}`
+            : `retired patched Engine ${ref}${from}; prepare stock Engine again, ${engine.checkout}`;
 }
 function syncCommands(system) {
     if (!system.syncCommands)

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

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

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

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

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

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

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

@@ -18,3 +18,9 @@ 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. */
+export declare const NODE_WORKSPACE_PATCH: {
+    readonly name: "node-workspace";
+    readonly base: "e11792b234ca0c39a5fc1d47af491f82fc8e2670";
+    readonly sha256: "a4b866a6da4cbb636bd614271c9691280490b00172dae02a8b113ad161055757";
+};

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

@@ -13,3 +13,8 @@ export const OWNED_PROCESSES_PATCH = {
 };
 export const LIGHT_TOPOLOGY_OVERLAY = { relay: { validators: 4 } };
 export const DESCRIPTOR_OVERLAYS = { "light-topology": LIGHT_TOPOLOGY_OVERLAY };
+export const NODE_WORKSPACE_PATCH = {
+    name: "node-workspace",
+    base: ENGINE_RELEASE.base,
+    sha256: "a4b866a6da4cbb636bd614271c9691280490b00172dae02a8b113ad161055757",
+};

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

@@ -29,6 +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.
      * Default `none`. The retired `owned-processes` value is refused.
      */
     readonly patch?: EnginePatch;
@@ -47,7 +48,7 @@ export interface EngineBuildRecord {
     repository?: string;
     /** `none`: stock Engine, without the owned-processes patch (absent in an older record: the patch). */
     patch?: EnginePatch;
-    /** The owned-processes patch's digest; empty for a stock build. */
+    /** The selected patch's digest; empty for a stock build. */
     patchSha256: string;
     preparedAt: string;
 }
@@ -68,15 +69,15 @@ export interface PreparedEngine {
 export declare class EngineNotPrepared extends Error {
     readonly reason: string;
     readonly fix: string;
-    /** The requested stock build, or a retired legacy choice. */
+    /** The requested build or a retired legacy choice. */
     readonly patch: EnginePatch;
     constructor(reason: string, fix: string, 
-    /** The requested stock build, or a retired legacy choice. */
+    /** The requested build or a retired legacy choice. */
     patch?: EnginePatch);
 }
-/** `as-prepared` accepts the recorded choice only when it is stock; legacy patched records are refused. */
+/** `as-prepared` accepts stock or the current repository fix; legacy owned-processes records are refused. */
 export type PreparedEnginePatch = EnginePatch | "as-prepared";
-/** Check the record against the pin (or explicit ref), checkout HEAD, stock digest, build and dot CLI. */
+/** Check the record against the pin (or explicit ref), checkout HEAD, selected digest, build and dot CLI. */
 export declare function preparedEngine(root: string, options: {
     stateDirectory?: string;
     fix: string;

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

@@ -4,7 +4,8 @@ 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 { ENGINE_RELEASE } from "./patch-catalogue.js";
+import { resolvePatch } 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";
 export const defaultStateDirectory = ".product-lab";
@@ -41,8 +42,12 @@ export function prepareEngine(root, ref, network, commands, stateDirectory = def
         throw new Error("Network must be previewnet or paseo-next-v2");
     setupPaths(root, ref, "", stateDirectory);
     const repository = engineRepository(source);
-    if (source.patch && source.patch !== "none")
+    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;
+    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";
     const revisions = /^[0-9a-f]{40}$/i.test(ref)
         ? [[ref, ref]]
@@ -65,7 +70,9 @@ export function prepareEngine(root, ref, network, commands, stateDirectory = def
         revisions[0])?.[0];
     if (!resolvedRef || !/^[0-9a-f]{40}$/i.test(resolvedRef))
         throw new Error("Could not resolve an immutable Engine revision");
-    const paths = setupPaths(root, resolvedRef, "", stateDirectory);
+    if (patchFile && resolvedRef !== patchFile.base)
+        throw new Error("node-workspace patch requires its tested Engine base");
+    const paths = setupPaths(root, resolvedRef, patchFile?.sha256 ?? "", stateDirectory);
     mkdirSync(paths.base, { recursive: true });
     const run = (command, args, cwd = paths.checkout) => checkedSync(commands, { command, args, cwd, output, timeoutMs: 1_800_000 });
     if (!existsSync(join(paths.checkout, ".git"))) {
@@ -83,6 +90,13 @@ export function prepareEngine(root, ref, network, commands, stateDirectory = def
     }
     else if (head !== resolvedRef)
         throw new Error("Prepared Engine checkout changed; refusing to overwrite it");
+    if (patchFile) {
+        const applied = commands.run({ command: "git", args: ["apply", "--reverse", "--check", patchFile.path], cwd: paths.checkout, timeoutMs: 30_000 });
+        if (applied.code !== 0) {
+            run("git", ["apply", "--check", patchFile.path]);
+            run("git", ["apply", patchFile.path]);
+        }
+    }
     const manifest = JSON.parse(readFileSync(join(paths.checkout, "package.json"), "utf8"));
     if (manifest.packageManager !== "pnpm@10.33.0")
         throw new Error("Engine package manager changed; review setup before updating its toolchain");
@@ -113,7 +127,7 @@ export function prepareEngine(root, ref, network, commands, stateDirectory = def
         dashboard: "http://127.0.0.1:8090",
         extraPath: [dotBin],
         startupTimeoutMs: 1_800_000,
-        enginePatch: "none",
+        enginePatch: patch,
     };
     const configFile = resolve(root, stateDirectory, "engine.json");
     writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
@@ -121,8 +135,8 @@ export function prepareEngine(root, ref, network, commands, stateDirectory = def
         requestedRef: ref,
         resolvedRef,
         repository,
-        patch: "none",
-        patchSha256: "",
+        patch,
+        patchSha256: patchFile?.sha256 ?? "",
         preparedAt: new Date().toISOString(),
     }, null, 2) + "\n");
     return configFile;
@@ -163,16 +177,19 @@ export function preparedEngine(root, options) {
         throw refuse(prepared === "none"
             ? `${stateDirectory} holds stock Engine ${String(build.resolvedRef).slice(0, 12)} (prepared without the owned-processes patch), not the patched one`
             : `${stateDirectory} holds the patched Engine ${String(build.resolvedRef).slice(0, 12)}, not stock Engine`, wanted);
-    if (wanted !== "none")
+    if (wanted !== "none" && wanted !== "node-workspace")
         throw refuse(ENGINE_PATCH_RETIRED, wanted);
     const ref = options.ref ?? (options.patch === "as-prepared" ? build.resolvedRef : testedEngineRef);
     if (!/^[0-9a-f]{40}$/i.test(build.resolvedRef))
         throw refuse(`${recordFile} has no immutable Engine revision`, wanted);
     if (/^[0-9a-f]{40}$/i.test(ref) && build.resolvedRef !== ref)
         throw refuse(`${stateDirectory} holds Engine ${String(build.resolvedRef).slice(0, 12)}, this checkout of product-lab tests ${ref.slice(0, 12)}`, wanted);
-    if (build.patchSha256 !== "")
-        throw refuse(`${recordFile} records a patch digest for stock Engine`, wanted);
-    const paths = setupPaths(stateDirectory, build.resolvedRef, "", ".");
+    const digest = wanted === "node-workspace" ? NODE_WORKSPACE_PATCH.sha256 : "";
+    if (wanted === "node-workspace" && build.resolvedRef !== NODE_WORKSPACE_PATCH.base)
+        throw refuse("node-workspace patch requires its tested Engine base", wanted);
+    if (build.patchSha256 !== digest)
+        throw refuse(wanted === "none" ? `${recordFile} records a patch digest for stock Engine` : `${recordFile} records another node-workspace patch digest`, wanted);
+    const paths = setupPaths(stateDirectory, build.resolvedRef, digest, ".");
     const issue = existsSync(join(paths.checkout, ".git")) ? engineBuildIssue(paths.checkout, options.commands, wanted) : `there is no checkout at ${paths.checkout}`;
     if (issue)
         throw refuse(issue, wanted);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/product-lab",
-  "version": "0.1.2",
+  "version": "0.2.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",