@parity/product-lab 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @parity/product-lab
 
+## 0.3.0
+
+### Minor Changes
+
+- b2abd7c: Add `previewnetGenesis()` to `@parity/product-lab/composition`: one line of a lab's config, `environments: { ...previewnetGenesis() }`, gives it "Previewnet from genesis" (`previewnet-genesis`), Previewnet's People, Asset Hub and Bulletin started from genesis on your machine by Engine, a new network every start. Once it is ready, and after every reset, People's rings are prepared for new people, so a new person can be onboarded on it like on the local copies. `product-lab fetch --environment previewnet-genesis` prepares its Engine and `product-lab doctor` checks it; it keeps its own folder in the cache, so your local copies' Engine is not changed. It binds Engine's default ports (relay 10000 to 10005, People 10010, Asset Hub 10020, Bulletin 10030, dashboard 8090, dub 8092, dub's database 5433, and Engine's other defaults in its config/ports.env: eth-rpc 8545, IPFS 8080, 5001 and 4001, TURN 3478, 3479 and its relay range 49152 to 49407, p2p 30333 to 30336), not the lab's port block: one Engine network per machine at a time; a port option is a planned follow-up.
+  
+  The package now ships Engine's node-workspace patch, so `EngineSource.patch: "node-workspace"` works from an installed package instead of failing with `EnginePatchesNotInstalled`. The Engine setup script takes `--engine-patch node-workspace`. People's ring preparation is available on its own as `PeopleAttesterChain.prepareRings(collections)`, with `PEOPLE_LITE_COLLECTION`.
+
+### Patch Changes
+
+- b2abd7c: A failed step is no longer explained by the folders or Node modules in its stack trace. The failure explanation's rules now read only the error's message, not its stack frames, so a check that fails in a checkout or product folder named like `previewnet-genesis` or `truapi`, or with frames in a `websocket.js` file or `node:events`, keeps the explanation its message gives, instead of "Infrastructure, not the product", a chain mismatch or a host refusal. The environment rule's bare words "genesis" and "baseline" are replaced by the environment errors they were meant for: endpoints that share a genesis, a fast baseline that is missing, for another machine or changed, an attached chain or Chopsticks upstream that is another chain, and a People whose genesis is not the network's. An assertion that mentions genesis, such as "account funded at genesis", is explained as the check's failure.
+
+## 0.2.0
+
+### Minor Changes
+
+- 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,10 @@ 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`, `setup/node-workspace.patch` | Stock Engine v0.11.0 preparation and shipped release pin; `preparedEngine` checks the pin, stock record, checkout HEAD, built CLI and dot CLI. The optional `EngineSource.patch: "node-workspace"` is read from the copy the package ships beside the catalogue (`setup/node-workspace.patch`, `shippedEnginePatch`, digest-checked against `NODE_WORKSPACE_PATCH`, its manifest entry in the package; since 12 November 2026, so a product prepares it too: `tests/patch-catalogue.test.ts` holds it byte for byte the repository's `patches/previewnet-engine/node-workspace.patch`), applied before build, keyed by digest and reverse-checked before reuse. Retired owned-processes records and requests are refused. Descriptor overlays remain digest-checked through the repository manifest. |
+| `setup/engine-tooling.ts` | An Engine checkout as an environment's tooling in a state directory of its own (12 November 2026, for composition's `previewnetGenesis`): `engineCheckoutTooling({ state, network, patch, environment })` (id `engine:<state>`; `check` is ready only for the build `patch` names; `prepare` runs `prepareEngine` with it, and refuses `--no-engine-patch` for a patched one), `preparedEngineCheckout` (the start's check, its refusal naming the fix) and `engineFetchCommand(environment)` (`product-lab fetch --environment <id>`, through the checkout's CLI script or npx). `tests/engine-checkout-tooling.test.ts` |
 | `setup/setup-command.ts` | The command every Engine refusal names, for where this adapter runs (`engineSetupCommand(environment?)`): `bun run setup` in product-lab's checkout, `npx --no-install product-lab fetch --environment <id>` in a product, which has no `bun run setup` (`insideProductLabCheckout`, this adapter's own copy of the CLI's check) |
-| `saved-fork/saved-fork-tooling.ts` | The Engine checkout a saved fork starts from, `<cacheDir>/engine` (16 October 2026): `savedForkEngine` (the start's check, `as-prepared`, its refusal naming `SavedForkSettings.setupCommand`, default `engineSetupCommand`), and `savedForkTooling`, the fork's `EnvironmentProvider.tooling` (id `engine:<cacheDir>/engine`, shared by every saved fork with that cache; kind `engine`): `check` is `savedForkEngine`'s, `prepare` runs `prepareEngine` there for the fork's network with the request's source (`repository`, `ref`, `patched: false` for stock, also the default; `patched: true` is refused) and returns the check of exactly what it asked for. `product-lab fetch` prepares it and `product-lab doctor` reports it in a product. A saved fork 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 +122,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/index.d.ts

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

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

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

package/adapters/environment/engine/src/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)