@parity/product-lab 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @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
+
+- d9721de: Keep direct and custom feature steps in recordings, with their timing and after-step images. Default frames-only runs keep capture non-blocking. Video runs wait for document load completion and exact screenshot stability over 200 ms before taking after-step images, and add a 2-second tail per scenario before cleanup. Stability checking defaults to a 3-second cap, configurable with `PRODUCT_LAB_RECORDINGS_SETTLE_MS`; the effective cap reserves 1000 ms for the final image (half the capture timeout below 2000 ms), so the default capture timeout clamps requested stability waits to at most 4000 ms. At the cap, a fresh image is kept with `settled: false` and `waitedMs`, without failing the step. The recording view and demo captions disclose when a frame was taken at the stability cap. The existing whole-capture timeout still applies. Recording metadata is additive and older recordings remain readable.
+  
+  `product-lab demo` now produces 1280×960 held stills with captions below the app, instead of a moving 1280×720 cut. Each step is held for at least 2 seconds and exports a midpoint PNG. `--max-seconds` no longer shortens the cut. Older recordings without after-state evidence are refused, including with `--plan` and `--slide-only`, instead of substituting unrelated footage.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -323,3 +323,30 @@ For Parity's security disclosure process, and Bug Bounty program, feel free to v
 
 Apache-2.0: see LICENSE. The icons and fonts the lab window carries keep their own licences, in the files beside them
 (`lucide.LICENSE`, `*.OFL.txt`); the packages npm installs with this one keep theirs.
+
+## Settled feature demos
+
+Feature recordings include direct/custom step timing. Default frames-only capture stays asynchronous. Video recording (`--video`) awaits bounded after-step captures and keeps a 2-second tail per scenario before cleanup.
+
+`product-lab demo` produces 1280×960 held stills, with a 1280×720 app above a separate caption band and a decoded midpoint PNG per step. Each hold lasts at least two seconds; `--max-seconds` never shortens it. Older recordings without after-state evidence are refused, including with `--plan` and `--slide-only`. Setup context and older slide fallback imagery are labelled.
+
+
+Video feature after-frames first check that the current document has completed loading, then compare exact PNGs
+across a 200 ms window, sampling at least 100 ms apart. The stability wait is capped at 3000 ms by default
+(`RecordingSettings.settleTimeoutMs`, or `PRODUCT_LAB_RECORDINGS_SETTLE_MS`). At the cap, the recorder takes a
+fresh frame anyway and adds `settled: false` and `waitedMs` to its metadata. Successful checks add `settled: true`;
+`loadComplete` records when the source verified the document. The existing `captureTimeoutMs` still bounds the
+whole capture, including this wait and any final image. The wait never changes the step's own timestamps or outcome.
+
+Only feature after-frames with video enabled wait for visual stability, including the final frame after the
+2-second scenario tail. Tool-run captures, before-frames, checkpoints and default frames-only feature captures
+retain their existing asynchronous policy. Scenario cleanup still settles captures already in flight. Custom
+capture sources may ignore the optional load check; absent `loadComplete` means load completion is unknown.
+
+
+The effective stability cap reserves time for the final screenshot: it is clamped to `captureTimeoutMs` minus
+1000 ms, or minus half that timeout when it is shorter than 2000 ms. With the default 5000 ms capture timeout,
+`PRODUCT_LAB_RECORDINGS_SETTLE_MS` accepts positive values but uses at most 4000 ms; the default stays 3000 ms.
+A captured frame with `settled: false` is labelled "Taken at the stability cap" in recording-view notes and in
+the demo image manifest and captions, including reused setup and failure context. Older frames without this
+metadata retain their existing labels.

package/adapters/browser/playwright/README.md

@@ -212,3 +212,5 @@ condition on this package's own files; a distribution of axe-core itself keeps i
 `newContext({ permissions })` and `newPage({ permissions })` forward explicit permissions to the selected Playwright context. `onPageError(listener)` observes the original error message and returns a disposer; it does not change the app or its error handling. Consumers redact diagnostic strings before persistence. The Chromium controls exercise camera/microphone grants and listener disposal in `tests/playwright.test.ts`. An example's companion launchers receive `SessionContext.browsers` rather than constructing an independent browser.
 
 The native RTC connection fixture also closes its own browser when Node cancels its test. The test runner deadline alone does not interrupt an outstanding browser evaluation; the cancellation cleanup keeps a failed connection attempt from leaving that browser and test process alive. The original connection, privacy and ownership assertions remain in place.
+
+`PageFrameCapture.capture` accepts optional `loadComplete: true`: it waits until the current document has `readyState === "complete"`, within the supplied capture timeout, and reports `loadComplete: true`. Video feature after-frame checks use this before comparing PNGs; ordinary captures add no load wait. Tests in `tests/page-frame-capture.test.ts` cover ordering and existing capture behavior.

package/adapters/browser/playwright/src/page-frame-capture.js

@@ -56,7 +56,15 @@ export class PageFrameCapture {
             else
                 return { status: "unavailable", reason: `Identity ${actorId}'s app document cannot paint over elements (no locators)` };
         }
-        const image = async (document) => screenshots(document) ? new Uint8Array(await document.screenshot(shot)) : framed(document) ? new Uint8Array(await (await document.frameElement()).screenshot(shot)) : undefined;
+        let loadComplete;
+        const image = async (target) => {
+            if (options.loadComplete && "waitForFunction" in target && typeof target.waitForFunction === "function") {
+                await target.waitForFunction(() => document.readyState === "complete", undefined, { timeout: shot.timeout });
+                loadComplete = true;
+                options.signal?.throwIfAborted();
+            }
+            return screenshots(target) ? new Uint8Array(await target.screenshot(shot)) : framed(target) ? new Uint8Array(await (await target.frameElement()).screenshot(shot)) : undefined;
+        };
         let bytes;
         try {
             bytes = await image(page);
@@ -69,7 +77,7 @@ export class PageFrameCapture {
             bytes = await image(again);
         }
         if (bytes)
-            return { status: "captured", mediaType: "image/png", bytes, ...settled };
+            return { status: "captured", mediaType: "image/png", bytes, ...settled, ...(loadComplete !== undefined ? { loadComplete } : {}) };
         return { status: "unavailable", reason: `Identity ${actorId}'s app document offers no image capture` };
     }
     async accessibility(actorId, options = {}) {

package/adapters/chain/papi/README.md

@@ -38,7 +38,9 @@ alive, when an endpoint stopped answering: Node's own `WebSocket.close()` waits
 bound, and polkadot-api's ws-provider drops a socket whose connection timed out (5 s) without closing it. A Notes
 fork run whose live freshness reads timed out held four public sockets for nine minutes.
 `tests/close-unresponsive.test.ts` drives both cases against a loopback endpoint that never answers, and
-`composition/tests/fork-live.test.ts` the live runtime read; with the cut disabled all three fail.
+`composition/tests/fork-live.test.ts` the live runtime read; with the cut disabled all three fail. The endpoint counts
+only the client's WebSocket upgrades, so a local port probe's `GET /` is not taken for a reconnect, and each test closes
+its access even when it fails early.
 
 
 The account watch's reads (`ChainHistory`, since 29 September 2026): `signedExtrinsics(block, accounts)` gives a block's extrinsics one of the accounts signed, with their hashes (the signer is read from each signed version-4 extrinsic's `MultiAddress::Id`, `src/extrinsic-signer.ts`; unsigned and general extrinsics have none), and `pendingExtrinsics(accounts)` the pool's (`author_pendingExtrinsics`; `undefined` when the node does not offer the method, `isMethodUnavailable` in `src/errors.ts`). `poolAwareNonce(account)` (2 October 2026, backlog item 17k) is the node's own next nonce for the account, `system_accountNextIndex` asked by SS58 address: its nonce at the best block plus its transactions in the pool, every sender's and every format the pool holds; `undefined` without the method. Live on the People fast chain (omni-node), three `//Alice` remarks in flight: 6 while the nonce at the best block was 3 and `author_pendingExtrinsics` held 3; a read before the node imported them answers the best block's nonce.

package/adapters/environment/engine/README.md

@@ -23,7 +23,7 @@ use to reach an Engine network. Imported from the original lab.
 | `engine/network-template.ts` | engine.json `template: true`: `saveNetworkTemplate` keeps a clean copy of a new network right after its first boot (Engine stopped, before the first resume) in `<workspace>/template/` (its data folder, network.json, versions.json, the session, `template.json`); `restoreNetworkTemplate` (a reset) clones it back as a new generation: a new spawn stamp in `<data>/spawn.json` and the session (the session check and the network lock compare it) and a new run id; its chain state is the first boot's, so nothing created since exists on it. `cloneTree`: `cp -c -R` (APFS copy-on-write) on macOS, `cp --reflink=auto -a` elsewhere, else a plain copy with a warning. The template serves its own workspace's resets only: every saved path names `<workspace>/network` |
 | `engine/network-snapshots.ts` | Fixtures: `networkSnapshots(control)`, the `EnvironmentSnapshots` of a persistent network: `save` records each chain's finalized head, stops the network, copies `<workspace>/network` through the `TreeCloner` port (an APFS clone on macOS) with network.json, versions.json and the session, and resumes; `restore` refuses another kind, another lineage (`networkLineage`: the template's first boot, else the session's run; a network forked again is another lineage) or another workspace (saved paths name it), moves the live network aside, copies the snapshot in and resumes it, putting the moved one back when that fails. Since 30 September 2026 (backlog 1a) `control.files` names more plain files of the workspace to save beside the network (a consumer's own manifests, for example a workspace, an identity pool and its actors) under `files/`; restore puts each back, and one absent when saved stays absent. `networkSnapshotsUnsupported(owned, trees)` says why an attached network offers none. Since 30 September 2026 `networkSnapshots({ upgrade })` offers `EnvironmentSnapshots.upgrade` (a lab that owns the fork passes `savedForkUpdates(...).upgradeToLive`: `fixture refresh` upgrades a restored fixture in place); without it the snapshots say `upgradeUnsupported`. An Engine topology run (`engineEnvironment`) is disposable and reports `snapshotsUnsupported` Since 3 October 2026 (backlog 17h) `save` records `detail.savedAt` once the network has stopped, and with `control.locks` (`{ manager, directory?, log? }`) a restore reclaims the restored network's stale lock that a killed run took after that moment (`reclaimLockPredatedByRestore`), logging `Reclaimed the network lock … the restored state predates it (saved …)` |
 | `engine/network-adoption.ts` | Fixture sharing (30 September 2026): `planNetworkAdoption` reads an imported network snapshot and this workspace's running plan and says what adopting it moves: the saved workspace directory and prepared Engine tooling directory to this checkout's (another tooling hash, another Engine, is refused) and, when the port block differs by one offset, every port of the old block wherever a port is named (plan arguments and environment, session, `engine-ports.json`, isolation and zombienet records, chain spec boot nodes, IPFS addresses; `rewriteText`); it refuses, naming each, another port layout, content-addressed IPFS blocks naming an old loopback port, and any other small file that still names the old workspace or ports. `applyNetworkAdoption` rewrites the snapshot copy; `networkSnapshots` `restore(…, { adopt: true })` plans before anything stops, applies it to its own snapshot copy, keeps the brought lineage in `network/adopted-lineage.json` (`readAdoptedLineage`, read first by `networkLineage`; a template reset replaces the folder and forgets it) and returns what moved. `save` records Engine's bite (`fork-snapshot.json`) and ports as `detail.provenance`. Since backlog 242 the workspace's own files a snapshot carries under `files/` (the environment names them: `networkSnapshots({ files })`) are rewritten too, so an environment's records with their ports and directories move with it. `tests/network-adoption.test.ts`; a dry run on a real saved fork: `tools/verify/live/engine/fixture-adoption.ts` |
-| `engine/finality-stall.ts` | A saved network whose finality never advances after a resume (backlog 76). Seen live: relay validators that restart together can each lose the approval check of a candidate in their first second (`Session params unavailable (no active leaf?)`, upstream behaviour), and when too few are left to approve it (four of six lost) the relay block is never approved and nothing finalizes until the validators restart. `persistentNetwork.start()` recovers within a bound: it reads the validators' logs every second (`lostApprovalChecks`, `unapprovable`: the verdict arrives about 12 s into the start) and also calls a stall from the symptom alone (every chain answers, no finalized head advanced for `stallAfterMs`, default 2 minutes); it keeps what every process logged in `<workspace>/stall-evidence/<time>-start-<n>/` with `stall.json` (`keepStallEvidence`; `history.jsonl` lists every stall and outcome), stops the saved processes and starts them again, at most `stallRecovery.restarts` times (default 2). A recovered stall is reported: the `network-ready` phase says `finality advancing after 1 restart (finality had stalled: …)`, the logger warns, and `network.recovery.stalls` lists each stall (`NetworkStartRecovery`). One that is not recovered throws `FinalityStalledError` (`attempts`, `stalls`, each with its evidence directory), with the processes stopped and the data kept. `tests/finality-stall.test.ts` (the control: a network that never finalizes fails after 3 starts); the live loop is `tools/verify/live/engine/resume-loop.ts` Backlog 143 (5 October 2026): chains that stand while the relay's finalized head advances (read from a relay validator's RPC, `relayEndpoint` in `engine/drain.ts`) are waiting for the validators to prepare the parachains' PVFs, so they get no standing verdict and no restart, said in the start's progress; the start's deadline still bounds them, and a relay that stands too, or cannot be read, gives the verdict as before (`tests/finality-stall.test.ts`, with a frozen relay as its control). |
+| `engine/finality-stall.ts` | A saved network whose finality never advances after a resume (backlog 76). Seen live: relay validators that restart together can each lose the approval check of a candidate in their first second (`Session params unavailable (no active leaf?)`, upstream behaviour), and when too few are left to approve it (four of six lost) the relay block is never approved and nothing finalizes until the validators restart. `persistentNetwork.start()` recovers within a bound: it reads the validators' logs every second (`lostApprovalChecks`, `unapprovable`: the verdict arrives about 12 s into the start) and also calls a stall from the symptom alone (every chain answers, no finalized head advanced for `stallAfterMs`, default 2 minutes); it keeps what every process logged in `<workspace>/stall-evidence/<time>-start-<n>/` with `stall.json` (`keepStallEvidence`; `history.jsonl` lists every stall and outcome), stops the saved processes and starts them again, at most `stallRecovery.restarts` times (default 2). A recovered stall is reported: the `network-ready` phase says `finality advancing after 1 restart (finality had stalled: …)`, the logger warns, and `network.recovery.stalls` lists each stall (`NetworkStartRecovery`). One that is not recovered throws `FinalityStalledError` (`attempts`, `stalls`, each with its evidence directory), with the processes stopped and the data kept. `tests/finality-stall.test.ts` (the control: a network that never finalizes fails after 3 starts); the live loop is `tools/verify/live/engine/resume-loop.ts` Backlog 143 (5 October 2026): chains that stand while the relay's finalized head advances (read from a relay validator's RPC, `relayEndpoint` in `engine/drain.ts`) are waiting for the validators to prepare the parachains' PVFs, so they get no standing verdict and no restart, said in the start's progress; the start's deadline still bounds them, and a relay that stands too, or cannot be read, gives the verdict as before (`tests/finality-stall.test.ts`, with a frozen relay as its control; the test's fake relay answers only JSON-RPC POSTs, so a local port probe's `GET /` gets a 404). |
 | `engine/chain-clock.ts` | A resumed network's chains reach the wall clock before it is ready (backlog 106). A saved chain keeps the time of its last block until it builds a new one, and readiness waits for finality only on the lab's required chains, so a chain that only has to answer (Notes: Asset Hub) could still be at the save's time. That time is signed with: the truAPI CLI host timestamps its dotNS registration with Asset Hub's `Timestamp.Now` at the best block, and the identity backend refuses one more than 600 s old (seen 5 October 2026: gate batch 21's resume of a fork saved hours earlier failed onboarding with `dotns.signedAt is older than the intake freshness bound (600s)`). `persistentNetwork.start()` reads every chain's `Timestamp.Now` and best block after readiness (`waitForChainClocks`, `chainTime`) and waits until each is within 2 minutes (`CHAIN_CLOCK_MAX_LAG_MS`) of the wall clock, the `network-ready` phase naming what it waits for; one still behind after `CHAIN_CLOCK_TIMEOUT_MS` (2 minutes) is not building blocks, and the start fails with `ChainClockBehindError` (`behind`: each chain, its lag and best block), naming why and the way out (restart the network, or a fresh fork). The logger gives each chain's time, its lag at the first read and how long the wait took (`onRead`). `chainClock: false` skips it. `tests/chain-clock.test.ts` (the fake dashboard's `chainLagMs` sets each chain's time) |
 | `engine/approval-pin.ts` | Relay finality pinned at the approval threshold after a session change (backlog 93, 239). A start whose first block changes the session builds two gossip topologies before any peer connects; polkadot-sdk's `SessionGridTopologies::update_authority_ids` gives the peers to the first only, so some approval votes reach nobody until approval-distribution's level-1 aggression (`l1_threshold` 16), and every block then finalizes about 16 blocks late for the rest of the start. `ApprovalPinWatch` and the constants `APPROVAL_PIN_GAP` (14), `APPROVAL_PIN_HOLD_MS` (30 s), `APPROVAL_PIN_RESTARTS` (1): once the relay has finalized past the best head of the start's first read (so a backlog the start began with, as after the pin's own restart without a drain, is finalized first), a best head 14 or more ahead of the finalized one for 30 s restarts the network once (`stallRecovery.pinned`), recorded in `recovery.stalls` as `pinned` ("finality pinned at the approval threshold after a session change; restarted once", with the heads and the gap), its logs kept like a stall's; a second pin fails the start (`FinalityPinnedError`). Watched while the start waits for readiness and, if the relay is at the threshold when it is ready, until it falls below or holds |
 | `engine/node-temp-dir.ts` | A relay validator's TMPDIR fits its PVF sockets (backlog 93). A validator binds its PVF workers' Unix sockets directly in its TMPDIR (`pvf-host-prepare-<10>`); a path of `sun_path`'s size or more is refused (`path must be shorter than SUN_LEN`: 104 bytes on macOS and the BSDs, 108 on Linux, `SUN_PATH_BYTES`), so no candidate is validated, no approval completes and the relay's finality stops at the last block before the first unapproved candidate. Seen 4 October 2026: a fork started with TMPDIR under a lane's `_artifacts` folder (107-byte socket paths) stalled at relay #1,310,664 on a fresh boot and on every resume. `nodeTempDir(network, inherited)`: when the inherited TMPDIR is too long (`pvfSocketsFit`), the network's processes get `TMPDIR=/tmp/pl-pvf-<12 hex of the network directory>` (0700), on the first boot (`OwnedEngineDependency`: Engine, zombie-cli and so every node) and on each resume (`persistentNetwork`: every saved process), with a warning naming the byte counts; it is removed on stop, and the next start of the same network removes one a crashed run left. A TMPDIR that fits changes nothing. `tests/node-temp-dir.test.ts` (both sides of the limit on macOS and Linux), `tests/finality-stall.test.ts` (a resume), `tools/verify/tests/engine-owned-start.test.ts` (a first boot); each fails with the override removed |
@@ -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