@parity/product-lab 0.1.1 → 0.2.0

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -18,3 +18,9 @@ export declare const LIGHT_TOPOLOGY_OVERLAY: {
 };
 /** The descriptor overlays a fork layout names (`ForkLayout.descriptors`), by manifest entry. */
 export declare const DESCRIPTOR_OVERLAYS: Readonly<Record<string, unknown>>;
+/** Optional repository-only fix; stock preparation remains the default. */
+export declare const NODE_WORKSPACE_PATCH: {
+    readonly name: "node-workspace";
+    readonly base: "e11792b234ca0c39a5fc1d47af491f82fc8e2670";
+    readonly sha256: "a4b866a6da4cbb636bd614271c9691280490b00172dae02a8b113ad161055757";
+};

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

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

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

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

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

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

package/adapters/features/cucumber/README.md

@@ -83,3 +83,7 @@ and the run report. `error` remains the original failure text, so explanation ru
 text-judged controls cannot match diagnostic words. Status and failure reason remain those of the original result. A normal
 settled step gets no extra attachment. `entrypoints/cli/tests/abort-diagnostics.test.ts` exercises
 this through a timed-out generated step.
+
+## Held feature demos
+
+registerFeatureSteps calls the optional startStep/finishStep observers for direct/custom definitions. Generated steps time themselves. The recording AfterStep hook is registered after the pause hook because Cucumber runs AfterStep hooks in reverse order, so video recording's bounded after-state capture finishes before a pause. Default frames-only capture stays asynchronous. In-process tests cover this order and custom definitions.

package/adapters/features/cucumber/src/steps/register-feature-steps.js

@@ -156,8 +156,9 @@ export function registerFeatureSteps(session, options = {}) {
     });
     api.BeforeStep(function ({ pickleStep }) {
         const state = scenarios.get(this);
-        if (state)
+        if (state) {
             state.current = state.ids.indexOf(pickleStep.id);
+        }
     });
     if (options.beforeStep) {
         const gate = options.beforeStep;
@@ -166,6 +167,10 @@ export function registerFeatureSteps(session, options = {}) {
             await gated(gate({ scenario: pickle.name, index: state ? state.ids.indexOf(pickleStep.id) : -1, text: pickleStep.text, status: "pending" }));
         });
     }
+    api.BeforeStep(function () {
+        const state = scenarios.get(this);
+        state?.scenario.startStep?.(state.current);
+    });
     for (const view of sentences) {
         const body = async function () {
             const state = scenarios.get(this);
@@ -199,6 +204,15 @@ export function registerFeatureSteps(session, options = {}) {
             await gated(gate({ scenario: pickle.name, index: state ? state.ids.indexOf(pickleStep.id) : -1, text: pickleStep.text, status: String(result.status).toLowerCase() }));
         });
     }
+    api.AfterStep({ timeout: hookTimeout }, async function ({ result }) {
+        const state = scenarios.get(this);
+        if (!state)
+            return;
+        const status = String(result.status).toUpperCase();
+        if (status === "SKIPPED")
+            return;
+        await state.scenario.finishStep?.(state.current, { status: status === "PASSED" ? "passed" : "failed", ...(result.message ? { error: result.message } : {}) });
+    });
     api.After({ name: "product-lab: end the scenario", timeout: hookTimeout }, async function ({ pickle, result }) {
         const state = scenarios.get(this);
         scenarios.delete(this);

package/adapters/system/node/README.md

@@ -9,7 +9,7 @@ Node implementations of the system ports in [`@product-lab/ports/system`](../../
 | `GitChangeSource` | `ChangeSource` | Phase 7: files changed between the merge base of a base revision and HEAD, plus uncommitted and untracked ones, relative to the lab's directory (`../` outside it); read-only git, no fetch; an unknown base or an option-like revision is refused; every git command runs through a `CommandRunner` (default `NodeCommandRunner`) bounded by `timeoutMs` (default 30 000 ms), a non-zero exit rejects with git's first stderr line, and an uncommitted file that cannot be read rejects `revision` rather than counting as deleted (`tests/git-change-source.test.ts`, a real temporary repository). Backlog 37: `commits` (first-parent commits that changed the lab's directory between two, oldest first; refused when the first is not an ancestor), `checkout` (`git worktree add --detach` into a new directory, with the lockfile at its top and its sha256; the lab's checkout untouched) and `removeCheckout` (forced remove, the directory deleted, `git worktree prune`) |
 | `NodeSourceWatcher` | `SourceWatcher` | Hot reload of app code (backlog item 5): `fs.watch`, recursive on a watched directory (FSEvents on macOS, inotify on Linux), a watched file or a path not created yet through its nearest existing parent directory; reports changed paths relative to the lab with `/` separators (a watch of `.`, the lab's directory, reports every change under it, an editor's safe write by rename included), not debounced (the application's `AppReloads` debounces). `digest`: sha256 over each regular file's relative path and content in path order, an ignored directory skipped whole, symbolic links not followed. `tests/node-source-watcher.test.ts` (real temporary directory) |
 | `NodeConditionedLinks` | `ConditionedLinks` (backlog 31) | One identity's conditioned link to one loopback endpoint (`node-conditioned-links.ts`): a TCP proxy on a port the caller reserved, carrying every byte as sent through the domain's `ConditionedWire` (one per direction of each connection: in order, a burst at its speed, half the round trip each way while throttled); offline refuses new connections and cuts the open ones; half-closes travel through the wire, so an answer sent before its server closes still arrives. A plain `http:` or `ws:` endpoint is named as the request's `Host` in the first request head of each connection (`request-head.ts`: a local Substrate node answers "Provided Host header is not whitelisted" to any other), and a plain request is made its connection's only one (`Connection: close`); a WebSocket upgrade keeps its connection, and bytes that do not start a request pass as sent. A public endpoint is refused, never proxied. Backpressure is not modelled. `tests/node-conditioned-links.test.ts` (real loopback sockets) |
-| `NodeChainGates` | `ChainGates` (backlog 92) | Origin gates in front of local chain nodes (`node-chain-gates.ts`): one loopback TCP relay per plain `ws:` loopback chain route that accepts connections (a closed port, TLS and a public node are kept as they are). It holds each connection's first request head, decides it once, then pipes bytes both ways (backpressure, no per-message parsing). A request with neither `Origin` nor `Sec-Fetch-Site` (a native host, Node's fetch and WebSocket) passes; a browser's passes only from an admitted origin (`admit`), otherwise the connection is reset unanswered (a 403 would still resolve a no-cors fetch) and recorded (`refused()`: chain, gate URL, kind, origin, time). The node sees its own address as `Host` and a plain request is its connection's only one (`request-head.ts`), so no later request on a kept-alive connection skips the gate. A half-close travels on for a grace (5 s, `halfCloseGraceMs`), then both sides are cut; either side closing or failing destroys both; `close()` cuts everything. Substrate's own `--rpc-cors` cannot do this: its RPC server adds CORS headers but refuses no WebSocket upgrade. `tests/node-chain-gates.test.ts` (real loopback sockets: a closed upstream, a half-closed client, keep-alive, close) |
+| `NodeChainGates` | `ChainGates` (backlog 92) | Origin gates in front of local chain nodes (`node-chain-gates.ts`): one loopback TCP relay per plain `ws:` loopback chain route that accepts connections (a closed port, TLS and a public node are kept as they are). It holds each connection's first request head, decides it once, then pipes bytes both ways (backpressure, no per-message parsing). A request with neither `Origin` nor `Sec-Fetch-Site` (a native host, Node's fetch and WebSocket) passes; a browser's passes only from an admitted origin (`admit`), otherwise the connection is reset unanswered (a 403 would still resolve a no-cors fetch) and recorded (`refused()`: chain, gate URL, kind, origin, time). The node sees its own address as `Host` and a plain request is its connection's only one (`request-head.ts`), so no later request on a kept-alive connection skips the gate. A half-close travels on for a grace (5 s, `halfCloseGraceMs`), then both sides are cut; either side closing or failing destroys both; `close()` cuts everything. Substrate's own `--rpc-cors` cannot do this: its RPC server adds CORS headers but refuses no WebSocket upgrade. `tests/node-chain-gates.test.ts` (real loopback sockets: a closed upstream, a half-closed client, keep-alive, close; the fake node does not record a plain `GET` with no browser mark, which is what a local port probe sends, and the test sends one to both ports) |
 | `NodeAppProxies` | `AppProxies` | The lab's proxy in front of an app's dev server (backlog items 64 to 66; `src/app-proxy/`): an HTTP reverse proxy on a loopback port that passes every request and answer as sent, except that an HTML document the browser loads gets the host's bridge script (the domain's `injectScriptTag`; then `no-store`, no validators), bodies are asked for uncompressed and documents unconditionally, a redirect to exactly the dev server's origin names the proxy, and the connection to the dev server is the proxy's own (one per request, since dev servers close idle kept-alive sockets). It reads the document's framing headers and never changes them (`framing()`). WebSockets are tunnelled byte for byte (`web-socket-tunnel.ts`); an update socket it understands (`VITE_UPDATES` in `vite-updates.ts`, Vite's `vite-hmr` subprotocol, checked against Vite 7.3.7) is read message by message: each announced update is put to the policy and forwarded or dropped, the same announcement on several pages' sockets is one update, and the page's side stays open when the dev server's closes (`lost`). A socket or an event stream it does not understand passes untouched and is reported once (`unknown-socket`), never for a declared dev server. `tests/node-app-proxy.test.ts` (real loopback servers, Node's WebSocket client; controls: an asset, a fragment, a conditional request, a dead dev server) |
 | `RandomIdGenerator` | `IdGenerator` | random UUIDs |
 | `ConsoleLogger` | `Logger` | level filter; details as JSON; with `redactor` (a `Redactor`'s `text`), every line scrubbed before it is written (backlog 89: the composition root passes the runtime's, so a provider logging a secret of the lab never prints it) |
@@ -70,7 +70,7 @@ The app-proxy fixture registers listener cleanup before proxy startup; an occupi
 
 The process-tree readiness controls count the anchor, command and child separately; the gated child must appear before readiness passes.
 
-`bunx nx run system-node:test`: real process trees for the runner (registry in memory; `tests/owned-group-anchor.test.ts`: a command exiting 0 or non-zero before any refresh with a descendant in its group, an escaped `setsid` descendant pinned as not covered, a stop during a start, a failed recording, a spawn error, a crashed controller (`tests/anchor-controller.ts`, registry on disk through `tests/disk-files.ts`) while the command runs and after it exits, reused pids, the anchor's own bounds, the command's default and named `cwd`, and a start never acknowledged: `tests/unacknowledging-anchor.mjs` as `anchor.path`, silent (stopped) or dying (refused, record kept)), real one-shot commands for `NodeCommandRunner` (exit code, cwd, env overlay and removal, stdin; timeout, abort, pre-aborted, a missing command and a zero timeout rejected; descendants: one holding the output after the command exits (settles within `drainMs`, group killed), a timeout with one in the group (both killed, on time), one that left the group (not killed, still settles by timeout + drain), and controls: a descendant with closed output neither delays nor fails a run, and 4 MiB of output is read in full with a 50 ms drain), fakes for the process table (EPERM, survivors, group capture), locks (liveness, clock), JSON-RPC transports and the connection probe (lsof output, process trees, exit 1 with a partial listing, a bounded `stop()`, and real `ps`/`lsof` with a watched process that exits), real loopback sockets for ports (a block found free at the start of the run from an OS-assigned port, or `SYSTEM_NODE_TEST_PORT_BASE`). `tests/node-process-sandbox.test.ts`: platform selection, construction and profile/plan-wrapping unit tests plus live smoke tests (gated to where `sandbox-exec` is supported) that spawn a wrapped process and assert a public connect gets `EPERM` while loopback still works, and record that the machine's own address counts as `localhost`. `tests/linux-namespace-sandbox.test.ts`: the probe and the wrap against fakes everywhere; on Linux where the probe passes, live smoke tests (this machine's own non-loopback address reachable unsandboxed and `ENETUNREACH` sandboxed, a public address refused at once, a declared loopback port reached through the forwarder and an undeclared one refused although it listens, a declared listen port reached from outside, exit codes and SIGTERM passed through) and a leaky control (a plan left unwrapped fails the same deny check, "reached … outside loopback"). `tools/linux` runs them on Linux in a container. On disk and across a crashed owner process: `tools/verify/tests/system-adapters.test.ts`.
+`bunx nx run system-node:test`: real process trees for the runner (registry in memory; `tests/owned-group-anchor.test.ts`: a command exiting 0 or non-zero before any refresh with a descendant in its group, an escaped `setsid` descendant pinned as not covered, a stop during a start, a failed recording, a spawn error, a crashed controller (`tests/anchor-controller.ts`, registry on disk through `tests/disk-files.ts`) while the command runs and after it exits, reused pids, the anchor's own bounds, the command's default and named `cwd`, and a start never acknowledged: `tests/unacknowledging-anchor.mjs` as `anchor.path`, silent (stopped) or dying (refused, record kept)), real one-shot commands for `NodeCommandRunner` (exit code, cwd, env overlay and removal, stdin; timeout, abort, pre-aborted, a missing command and a zero timeout rejected; descendants: one holding the output after the command exits (settles within `drainMs`, group killed), a timeout with one in the group (both killed, on time), one that left the group (not killed, still settles by timeout + drain), and controls: a descendant with closed output neither delays nor fails a run, and 4 MiB of output is read in full with a 50 ms drain), fakes for the process table (EPERM, survivors, group capture), locks (liveness, clock), JSON-RPC transports and the connection probe (lsof output, process trees, exit 1 with a partial listing, a bounded `stop()`, and real `ps`/`lsof` with a watched process that exits), real loopback sockets for ports (a block found free at the start of the run from an OS-assigned port, or `SYSTEM_NODE_TEST_PORT_BASE`). `tests/node-process-sandbox.test.ts`: platform selection, construction and profile/plan-wrapping unit tests plus live smoke tests (gated to where `sandbox-exec` is supported) that spawn a wrapped process and assert a public connect gets `EPERM` while loopback still works, and record that the machine's own address counts as `localhost`. Their greeter cuts every connection still open when it closes, since it never reads one; the machine-address test sends a local port probe itself and is bounded (30 s), so a close that never ends fails it instead of hanging the file. `tests/linux-namespace-sandbox.test.ts`: the probe and the wrap against fakes everywhere; on Linux where the probe passes, live smoke tests (this machine's own non-loopback address reachable unsandboxed and `ENETUNREACH` sandboxed, a public address refused at once, a declared loopback port reached through the forwarder and an undeclared one refused although it listens, a declared listen port reached from outside, exit codes and SIGTERM passed through) and a leaky control (a plan left unwrapped fails the same deny check, "reached … outside loopback"). `tools/linux` runs them on Linux in a container. On disk and across a crashed owner process: `tools/verify/tests/system-adapters.test.ts`.
 
 
 ## Source revisions for compatibility
@@ -107,7 +107,7 @@ API-name correction: `bridge()` is a method on the `AppProxy` returned by `NodeA
 
 One 3000 ms deadline covers the exact application-path HEAD collision probe and native GET. Native headers are capped at 16 KiB and the script at 2 MiB. Redirects are never followed; caller cookies and conditionals are never sent to the host. A successful non-HTML application asset at the generated path is refused with 409. HTML SPA fallback is accepted, but an intentional HTML route is indistinguishable from it. Unsupported HEAD replies refuse with explicit 502; this check does not atomically protect against later application route changes. The whole namespace is reserved, including missing/expired URLs; consumers must keep their routes outside it. The native socket remains at its original endpoint, so `script-src 'self'` still needs a suitable `connect-src` allowance. Nonce/hash-only scripts and strict-dynamic are unqualified.
 
-Focused checks: `node --import tsx --test adapters/system/node/tests/node-app-bridge.test.ts adapters/system/node/tests/node-app-proxy.test.ts`. `APP_BRIDGE_TEST_PORT_BASE` selects the new fixture block (default 45300; one distinct ten-port slice per case); `APP_PROXY_TEST_PORT_BASE` optionally selects distinct ports for the older proxy tests, whose default remains independent OS allocation. All fixture listeners close with their tests.
+Focused checks: `node --import tsx --test adapters/system/node/tests/node-app-bridge.test.ts adapters/system/node/tests/node-app-proxy.test.ts`. `APP_BRIDGE_TEST_PORT_BASE` selects the new fixture block (default 45300; one distinct ten-port slice per case); `APP_PROXY_TEST_PORT_BASE` optionally selects distinct ports for the older proxy tests, whose default remains independent OS allocation. All fixture listeners close with their tests. The bridge tests count, and wait for, only reads of a native server's bound path, so a local port probe's `GET /` is not taken for a read.
 
 ## Explicit Next App Router profile (1 October 2026)
 

package/adapters/video/ffmpeg/README.md

@@ -37,3 +37,7 @@ generated video cut into an MP4 and a WebM of the planned length with an overlay
 where ffmpeg is not installed).
 
 Private, workspace-only package. Consumers will install the single umbrella package `@parity/product-lab` once it is published.
+
+## Held feature demos
+
+VideoEditRequest.stills supplies exactly one PNG per segment; the adapter loops each at 25 fps for its planned duration, concatenates them, and encodes the result. No source-video timestamp is substituted for a missing still. The existing trim/speed/overlay path is retained when stills are absent. An offline integration test checks encoded midpoint pixels, duration, caption placement and failure visibility.

package/adapters/video/ffmpeg/src/ffmpeg-video-editor.d.ts

@@ -17,7 +17,7 @@ export declare function demoFilterGraph(plan: DemoPlan, overlays: readonly {
 }[], size: {
     width: number;
     height: number;
-}): {
+}, stills?: boolean): {
     graph: string;
     output: string;
 };

package/adapters/video/ffmpeg/src/ffmpeg-video-editor.js

@@ -6,14 +6,19 @@ import { join } from "node:path";
 const FRAME_RATE = 25;
 const INSTALL = "macOS: brew install ffmpeg; Debian/Ubuntu: apt install ffmpeg; or set PRODUCT_LAB_FFMPEG to its folder";
 const seconds = (ms) => (ms / 1000).toFixed(3);
-export function demoFilterGraph(plan, overlays, size) {
+export function demoFilterGraph(plan, overlays, size, stills = false) {
     if (!plan.segments.length)
         throw new Error("The demo plan has no segment to cut");
     const { width, height } = size;
     const frame = 1000 / FRAME_RATE;
     const parts = plan.segments.map((segment, index) => {
         const shown = segment.outputEnd - segment.outputStart;
-        const filters = [
+        const filters = stills ? [
+            "setpts=PTS-STARTPTS", `fps=${FRAME_RATE}`,
+            `scale=${width}:${height}:force_original_aspect_ratio=decrease`,
+            `pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=0xf6f6f4`, "setsar=1",
+            `trim=duration=${seconds(shown)}`,
+        ] : [
             `trim=start=${seconds(segment.sourceStart)}:end=${seconds(Math.max(segment.sourceEnd, segment.sourceStart + frame + 1))}`,
             `setpts=(PTS-STARTPTS)/${segment.speed.toFixed(4)}`,
             `fps=${FRAME_RATE}`,
@@ -24,10 +29,10 @@ export function demoFilterGraph(plan, overlays, size) {
             `trim=duration=${seconds(shown)}`,
             "setpts=PTS-STARTPTS",
         ];
-        return `[0:v]${filters.join(",")}[s${index}]`;
+        return `[${stills ? index : 0}:v]${filters.join(",")}[s${index}]`;
     });
     const concat = `${plan.segments.map((_, index) => `[s${index}]`).join("")}concat=n=${plan.segments.length}:v=1:a=0[cut0]`;
-    const layers = overlays.map((overlay, index) => `[cut${index}][${index + 1}:v]overlay=0:0:enable='between(t,${seconds(overlay.startMs)},${seconds(Math.max(overlay.endMs - 1, overlay.startMs))})'[cut${index + 1}]`);
+    const layers = overlays.map((overlay, index) => `[cut${index}][${index + (stills ? plan.segments.length : 1)}:v]overlay=0:0:enable='between(t,${seconds(overlay.startMs)},${seconds(Math.max(overlay.endMs - 1, overlay.startMs))})'[cut${index + 1}]`);
     return { graph: [...parts, concat, ...layers].join(";"), output: `cut${overlays.length}` };
 }
 export class FfmpegVideoEditor {
@@ -86,15 +91,23 @@ export class FfmpegVideoEditor {
     async render(request) {
         const work = mkdtempSync(join(tmpdir(), "product-lab-demo-"));
         try {
+            if (request.stills && request.stills.length !== request.plan.segments.length)
+                throw new Error("A demo needs exactly one still per segment");
+            const sources = request.stills ? request.stills.flatMap((png, index) => {
+                const file = join(work, `step-${index}.png`);
+                writeFileSync(file, png);
+                const segment = request.plan.segments[index];
+                return ["-loop", "1", "-framerate", String(FRAME_RATE), "-t", seconds(segment.outputEnd - segment.outputStart), "-i", file];
+            }) : ["-i", request.source];
             const inputs = request.overlays.flatMap((overlay, index) => {
                 const file = join(work, `overlay-${index}.png`);
                 writeFileSync(file, overlay.png);
                 return ["-i", file];
             });
-            const { graph, output } = demoFilterGraph(request.plan, request.overlays, request.size);
+            const { graph, output } = demoFilterGraph(request.plan, request.overlays, request.size, !!request.stills);
             const encode = request.format === "mp4" ? ["-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-pix_fmt", "yuv420p", "-movflags", "+faststart"] : ["-c:v", "libvpx-vp9", "-b:v", "0", "-crf", "34", "-row-mt", "1"];
             const partial = `${request.out}.partial.${request.format}`;
-            await this.run(this.ffmpeg, ["-v", "error", "-y", "-i", request.source, ...inputs, "-filter_complex", graph, "-map", `[${output}]`, "-r", String(FRAME_RATE), ...encode, partial], { timeoutMs: this.timeoutMs, ...(request.signal ? { signal: request.signal } : {}) });
+            await this.run(this.ffmpeg, ["-v", "error", "-y", ...sources, ...inputs, "-filter_complex", graph, "-map", `[${output}]`, "-r", String(FRAME_RATE), ...encode, partial], { timeoutMs: this.timeoutMs, ...(request.signal ? { signal: request.signal } : {}) });
             renameSync(partial, request.out);
             return { file: request.out, bytes: statSync(request.out).size, durationMs: await this.durationMs(request.out) };
         }