@parity/product-lab 0.0.1-placeholder → 0.1.0

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

@@ -0,0 +1,105 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+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) {
+    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 = [
+            `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}`,
+            `scale=${width}:${height}:force_original_aspect_ratio=decrease`,
+            `pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2:color=0xf6f6f4`,
+            "setsar=1",
+            `tpad=stop_mode=clone:stop_duration=${seconds(segment.holdMs + frame * 2)}`,
+            `trim=duration=${seconds(shown)}`,
+            "setpts=PTS-STARTPTS",
+        ];
+        return `[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}]`);
+    return { graph: [...parts, concat, ...layers].join(";"), output: `cut${overlays.length}` };
+}
+export class FfmpegVideoEditor {
+    commands;
+    ffmpeg;
+    ffprobe;
+    timeoutMs;
+    constructor(options) {
+        this.commands = options.commands;
+        this.ffmpeg = options.ffmpeg ?? "ffmpeg";
+        this.ffprobe = options.ffprobe ?? "ffprobe";
+        this.timeoutMs = options.timeoutMs ?? 600_000;
+    }
+    async run(command, args, options) {
+        const result = await this.commands.run({ command, args, timeoutMs: options.timeoutMs, maxOutputBytes: 64 * 1024 * 1024, ...(options.signal ? { signal: options.signal } : {}) });
+        if (result.code !== 0)
+            throw new Error(`${command} exited ${result.code}: ${result.stderr.trim().split("\n").slice(-4).join(" | ")}`);
+        return result.stdout;
+    }
+    async probe() {
+        try {
+            const version = (await this.run(this.ffmpeg, ["-version"], { timeoutMs: 15_000 })).split("\n")[0].replace(/\s+Copyright.*$/, "").trim();
+            await this.run(this.ffprobe, ["-version"], { timeoutMs: 15_000 });
+            const encoders = (await this.run(this.ffmpeg, ["-hide_banner", "-encoders"], { timeoutMs: 15_000 }));
+            const missing = ["libx264", "libvpx-vp9"].filter((name) => !encoders.includes(` ${name} `));
+            return { available: true, version: missing.length ? `${version} (without ${missing.join(", ")})` : version };
+        }
+        catch (error) {
+            return { available: false, reason: `the video needs ffmpeg and ffprobe (${INSTALL}): ${error.message.split("\n")[0]}` };
+        }
+    }
+    async durationMs(source) {
+        const format = (await this.run(this.ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "default=nw=1:nk=1", source], { timeoutMs: 60_000 })).trim();
+        if (Number.isFinite(Number(format)) && Number(format) > 0)
+            return Number(format) * 1000;
+        const frames = (await this.run(this.ffprobe, ["-v", "error", "-select_streams", "v:0", "-show_entries", "frame=pts_time", "-of", "csv=p=0", source], { timeoutMs: 300_000 })).trim().split("\n");
+        const last = Number(frames.filter(Boolean).at(-1));
+        if (!Number.isFinite(last))
+            throw new Error(`ffprobe could not tell the length of ${source}`);
+        return last * 1000 + 1000 / FRAME_RATE;
+    }
+    async frame(source, atMs) {
+        const work = mkdtempSync(join(tmpdir(), "product-lab-frame-"));
+        try {
+            const file = join(work, "frame.png");
+            await this.run(this.ffmpeg, ["-v", "error", "-y", "-ss", seconds(Math.max(0, atMs)), "-i", source, "-frames:v", "1", file], { timeoutMs: 60_000 });
+            const bytes = new Uint8Array(readFileSync(file));
+            if (!bytes.length)
+                throw new Error(`ffmpeg took no frame of ${source} at ${seconds(atMs)} s`);
+            return bytes;
+        }
+        finally {
+            rmSync(work, { recursive: true, force: true });
+        }
+    }
+    async render(request) {
+        const work = mkdtempSync(join(tmpdir(), "product-lab-demo-"));
+        try {
+            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 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 } : {}) });
+            renameSync(partial, request.out);
+            return { file: request.out, bytes: statSync(request.out).size, durationMs: await this.durationMs(request.out) };
+        }
+        finally {
+            rmSync(work, { recursive: true, force: true });
+        }
+    }
+}

package/adapters/video/ffmpeg/src/index.d.ts

@@ -0,0 +1 @@
+export { FfmpegVideoEditor, demoFilterGraph, type FfmpegVideoEditorOptions } from "./ffmpeg-video-editor.js";

package/adapters/video/ffmpeg/src/index.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { FfmpegVideoEditor, demoFilterGraph } from "./ffmpeg-video-editor.js";

package/adapters/visual/pixelmatch/README.md

@@ -0,0 +1,29 @@
+# @product-lab/visual-pixelmatch
+
+`ImageComparison` adapter (`@product-lab/ports/recording`, backlog 40): two PNG screenshots compared
+pixel by pixel.
+
+- `PixelmatchComparison`: `compare(expected, actual)` decodes both PNGs with pngjs and counts the
+  pixels pixelmatch finds different (per-pixel colour threshold `colourThreshold`, default 0.1;
+  anti-aliased pixels are not counted). It returns `{ differing, total, width, height, diff }`, the
+  diff a PNG with the changed pixels in red (anti-aliased ones in yellow) over a faded copy of the baseline, or `{ size }` when
+  the two images are not the same size (a size change always fails the step). Whether a count
+  fails is the domain's `visualVerdict` with the scenario's threshold (default 0.1% of the pixels).
+  No I/O.
+
+The composition root gives it to the runtime (`composition/src/create-lab-runtime.ts`,
+`stepChecks.compare`), with `FileVisualBaselines` as the baseline store.
+
+| | |
+| --- | --- |
+| Nx project | `visual-pixelmatch` |
+| Tags | `scope:provider`, `type:adapter` |
+| Exports | `src/index.ts`: `PixelmatchComparison`, `PixelmatchOptions` |
+| Implements | `ImageComparison` (`@product-lab/ports/recording`) |
+| Depends on | `@product-lab/ports`, `pixelmatch` 7.2.0 (ISC), `pngjs` 7.0.0 (MIT) |
+| Used by | the composition root |
+
+Tests: `bunx nx run visual-pixelmatch:test` (the same image, a changed pixel with its diff, a size
+change).
+
+Private, workspace-only package. Consumers will install the single umbrella package `@parity/product-lab` once it is published.

package/adapters/visual/pixelmatch/src/index.d.ts

@@ -0,0 +1 @@
+export { PixelmatchComparison, type PixelmatchOptions } from "./pixelmatch-comparison.js";

package/adapters/visual/pixelmatch/src/index.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { PixelmatchComparison } from "./pixelmatch-comparison.js";

package/adapters/visual/pixelmatch/src/pixelmatch-comparison.d.ts

@@ -0,0 +1,10 @@
+import type { ImageComparison, ImageDifference } from "@parity/product-lab/ports/recording";
+export interface PixelmatchOptions {
+    /** How different one pixel's colour must be to count, from 0 to 1 (pixelmatch's `threshold`; default 0.1). */
+    colourThreshold?: number;
+}
+export declare class PixelmatchComparison implements ImageComparison {
+    private readonly options;
+    constructor(options?: PixelmatchOptions);
+    compare(expected: Uint8Array, actual: Uint8Array): ImageDifference;
+}

package/adapters/visual/pixelmatch/src/pixelmatch-comparison.js

@@ -0,0 +1,19 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+export class PixelmatchComparison {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    compare(expected, actual) {
+        const before = PNG.sync.read(Buffer.from(expected));
+        const after = PNG.sync.read(Buffer.from(actual));
+        if (before.width !== after.width || before.height !== after.height)
+            return { size: { expected: `${before.width}×${before.height}`, actual: `${after.width}×${after.height}` } };
+        const diff = new PNG({ width: before.width, height: before.height });
+        const differing = pixelmatch(before.data, after.data, diff.data, before.width, before.height, { threshold: this.options.colourThreshold ?? 0.1 });
+        return { differing, total: before.width * before.height, width: before.width, height: before.height, diff: new Uint8Array(PNG.sync.write(diff)) };
+    }
+}

package/composition/README.md

@@ -0,0 +1,281 @@
+# @product-lab/composition
+
+`createLabRuntime` wires `browserPrerequisites` to the selected lab launcher, or its default Playwright launcher before loading. A custom launcher without prerequisite inspection refuses explicitly; inspection never launches it (`tests/composition.test.ts`).
+
+The composition root (refactor step 8).
+`createLabRuntime(options, env)` builds the object graph for one runtime and returns the `LabRuntime`
+driving port (`@product-lab/ports/driving`). It is the only code that constructs adapters; each entry
+point's `src/main.ts` calls it once and passes on only the runtime.
+
+```ts
+import { createLabRuntime, processEnvironment } from "@product-lab/composition";
+
+const runtime = createLabRuntime({ config: "lab.config.ts", allowPublic: true }, processEnvironment());
+await runtime.load();
+```
+
+`@product-lab/composition/process` (`src/process.ts`) is what a process needs before it loads a lab, without the
+rest (the index loads every adapter and the application, about 1,100 modules): `processEnvironment`, `labConfigPath`,
+`stdioWorker()` and `runningLab(configPath, { env, cwd, record })` (the lab running in that lab's folder, read where
+`createLabRuntime` keeps its record: `record`, else `PRODUCT_LAB_RUNNING_DIR`, else the folder's own;
+`tests/running-lab.test.ts`). `product-lab mcp` answers its client with these alone and loads the index in the
+background (entrypoints/mcp/README.md, "Start"). The index re-exports `processEnvironment` and `labConfigPath`.
+
+`createLabRuntime` reads and moves the lab window's remembered choices (the RPC per chain, each environment's option,
+and their move to renamed environment ids) in `stateDir`, else in `PRODUCT_LAB_STATE_DIR` (`STATE_DIR_VARIABLE`,
+against `cwd`), else in the lab folder's `.product-lab/state` (backlog 226). A test that loads an example's lab gives
+its own, so its result never depends on a developer's running lab and never rewrites its file
+(`tests/old-environment-state.test.ts`, "backlog 226").
+
+## What it builds
+
+| Part | Built from |
+| --- | --- |
+| System ports | `NodeSystem` (`src/node-system.ts`, `new NodeSystem(env, { redactor })`): files, clock, ids, logger (a `ConsoleLogger` that scrubs each line with `redactor`; `createLabRuntime` passes the runtime's own `SecretRedactor`, backlog 89), processes, bounded asynchronous and synchronous commands, locks, ports, JSON-RPC (`@product-lab/system-node`, `@product-lab/storage-filesystem`); run manifests under `<lab root>/.product-lab/runs` |
+| Engine setup CLI | `src/engine-setup.ts` parses setup options (`--engine-ref`, `--network`, `--state-dir`, `--dry-run`; since 16 October 2026 `--engine-repository <url\|path>` and `--no-patch`, stock Engine recorded as such) and supplies `NodeSyncCommandRunner` to env-engine's synchronous `prepareEngine`, keeping adapter construction in composition. A product prepares the saved forks' Engine with `product-lab fetch --environment paseo-copy` instead (the fork's `EnvironmentProvider.tooling`, reached through `LabRuntime.prepareEnvironmentTooling`; the attached runtime answers it locally) |
+| Console redaction (backlog 89) | `redactConsole(redactor, console?)` (`src/redact-console.ts`, exported): every `console.log`/`info`/`debug`/`warn`/`error` line goes through the runtime's redactor until restored, so a lab or provider printing a secret of the lab (a `fromEnv` URL with its token) never shows it. The CLI's `src/main.ts` installs it for one invocation, `featureRuntime` (bundled runs) and the Cucumber runner's `cucumberRuntime` for their process; the MCP server scrubs its captured console itself (`captureConsole`'s `redact`). Tests: `tests/redact-console.test.ts`, `tests/composition.test.ts` (the logger a provider gets, `system.logger`), and end to end `entrypoints/cli/tests/secret-console.test.ts`, `entrypoints/cli/tests/rpc-flags.test.ts`, `entrypoints/mcp/tests/stdio.test.ts` |
+| Protected stdio worker | `NodeSystem.stdioWorker` constructs the Node adapter for MCP's fd-3 protocol channel; `NodeSystem.syncCommands` supplies bounded synchronous CLI/AI commands; `NodeSystem.terminalCommands` runs an interactive program on the terminal (the terminal app's agent beside the lab) |
+| Environment adapters | the kinds the lab selects in `defineLab({ environmentAdapters: { <kind>: <settings> } })`, from `ENVIRONMENT_ADAPTERS` (`engine`, `relayless`, `chopsticks` with the attached adapter's probe); imported when first selected |
+| Host adapters | `defineLab({ hostAdapters })`, from `HOST_ADAPTERS` (`truapi-cli`, `truapi-wasm`, `dotli`); `product-lab host fetch\|build\|rebase-check` offers `HOST_TOOL_KINDS` (`truapi-cli` first, then `dotli`: `host build --host dotli` builds the locked dot.li) |
+| Host tool services | `src/host-tool-services.ts`: `hostToolServices({ clock, env })` gives the runtime a `NodeCommandRunner`, a `NodeProcessSandbox` (the official build's behavioural probes run under it) and `githubUpstreamResolver`, an `UpstreamResolver` on the GitHub version adapter (`latest` = newest release in the request's tag family, skipping other packages' tags, drafts and prereleases; `GITHUB_TOKEN` when set). `host rebase-check` receives all three in its tool context (`tests/host-tool-services.test.ts`, a fake API) |
+| What a lab's own code gets (refactor step 9) | `SessionContext.system` and `EnvironmentStartContext.system` (the lab's system ports, `NodeSystem.forLab`, including `commands: NodeCommandRunner` for bounded one-shot commands), `SessionContext.browsers` (`BROWSERS`: `PlaywrightBrowserLauncher`, imported on first launch; `defineLab({ browsers })` overrides) |
+| Local copies of live networks (the user's decision 5) | `paseoCopy(options?)` and `previewnetCopy(options?)` (`src/network-copies.ts`): one line of a lab's config, `environments: { ...paseoCopy() }`, gives it "Local copy of Paseo", Full or Light (backlog 184), each env-engine's `savedForkEnvironment` in its own folder (`<lab>/.product-lab/environments/<id>`, `<id>-light`) with the live reads composed here (`readLiveRuntimes`, `liveCodeFetcher`), the lab's cache (PRODUCT_LAB_CACHE_DIR) and seeds (PRODUCT_LAB_SHARED_FIXTURES), and a port block (`portBase`, else PRODUCT_LAB_FORK_PORT_BASE, else 42000). `savedForkOptions` builds the options for a lab's own forks (Notes). `tests/network-copies.test.ts` |
+| The product config (config redesign, lane L1) | `labDefinitionFrom(config, { root, env, environmentPorts?, path? })` (`src/default-lab.ts`, exported): `defineLab({ app, … })` (core/application's `product-lab-config.ts`) onto the definition the runtime runs, starting nothing. The app's id is its first step set's; the others are offered beside it as standalone integrations, available wherever their own requirements hold (7 October 2026: before, each was "used by no app of this lab" and every sentence of theirs refused). Sr25519 keys; fixture `inputs` default `FIXTURE_INPUTS`. It also returns `resolvedConfig` (`@product-lab/ports/driving`'s `ResolvedLabConfig`: every value and where it came from, a secret by its variable's name only), which `createLabRuntime` passes to the registry (`LabRegistry.config`). `createLabRuntime` translates every product config through it, object or function form (`PRODUCT_LAB_MODE` is the function's `mode`; it may be async). `tests/default-lab.test.ts` |
+| The product config's environments | `fast` is `relaylessTopology` over People and the app's chains it can make; `paseo-copy` `paseoCopy`; `previewnet-copy` and `chopsticks` only when listed; `live.<network>` `liveNetworkEnvironment` (read only without `people`; with them read-write, each person pre-onboarded from the variable named, `newPeople.fund` in planck on the first app chain). `defaultEnvironment` and a mode may name the lab's environments or the keys of `advanced.environments`. Each environment's run folders are under `<output>/environments` (`PRODUCT_LAB_OUTPUT_DIR`, default `<lab>/.product-lab`; Chopsticks' in `chopsticks/` there, its adapter also when `advanced` brings a Chopsticks topology). `tests/default-lab.test.ts` |
+| The product config's people on `fast` | Persons (`persons` launch option; the default session's `src/default-session-persons.ts` calls people-dev's `peopleOnboarding` and `standInForXcm`, People's genesis from `peopleDevGenesis`) when the app's chains include bulletin or its requires name the Statement Store, else funded wallets. `environments.fast.personProduct` names the label of the person product their member keys are derived under (`"<label>"` alone; the lab adds each network's suffix), shown as `environments.fast.personProduct`; unset, the released truAPI host's, so the keys are today's; refused when it is not a label, and, when the app needs persons, with `onboarding: "truapi-cli"` (the CLI host derives under its own preset). `tests/default-lab.test.ts`, `tests/people-dev-member-key.test.ts` |
+| Released hosts in a product | `src/checkout.ts`: product-lab's checkout or an installed `@parity/product-lab` (the root `package.json`'s name). The WASM host factory gets `shortEntropy` only in the checkout, so a product is served the released truAPI WASM test host page byte for byte; new people (`newIdentity`, people-dev's lab attester) are made from 24-word phrases (`NEW_PERSON_ENTROPY_BITS`, 7 October 2026). `tests/checkout.test.ts`, `tests/people-dev-onboarding.test.ts` |
+| The product config's hosts and keep | The truAPI CLI and WASM hosts on (their option defaults read from the adapters' declarations and `TRUAPI_WASM_LAB_DEFAULTS`), dot.li off (`hosts: { dotli: {} }` turns it on; its port is `hostPort` or a free port the lab reserves when it starts, shown as `hosts.dotli.hostPort`, `tests/dotli-port.test.ts`); root calls on local copies with the copy's sudo key. What a kept start keeps of the people (`keepBetweenStarts`, which the window's switch says): each person and their wallet when the default host is the truAPI CLI host (as `src/default-session-keep.ts` keeps them), else that each start makes new people and how to keep them (in a product: to make the truAPI CLI host the default once its locked release takes the lab's local endpoints, else that no host it can run keeps them yet, with #1166; `hostLockFile` in the context names another host lock, for tests); nothing with `keepBetweenStarts: false`. Declared fixtures on such a host carry `limits` (`ResolvedConfigEntry.limits`), which `check` lists on each fixture's environment: a fixture whose setup makes people cannot be saved there (the application refuses its person steps at plan, `fixturePeopleRefusal`). `tests/default-lab.test.ts` |
+| The product config's launch | `app.launch` (`dev`, `deployed-local`, `deployed`; default `dev`, or `deployed` when `app.deployed` is set): the lab adds what the launch needs to the app's chains and requires (deployed-local: deploy-bulletin's `deployedLocalRequirements`; deployed: asset-hub and bulletin), serves a dev server only for `dev`, and gives a session of the lab's own the app's `launch` option. The default session does all three (`DEFAULT_SESSION_LAUNCHES`, `src/deployed-app-server.ts`): `deployed-local` (backlog 200, `src/deployed-local-app.ts`) builds the app with `vite build` and the settings its dev server would get, deploys it to the environment's Bulletin and DotNS under a fresh name and serves it as `deployed` serves a name; an app whose dev server is not Vite is refused by name before anything starts (`refuseUnbuildable`), never served from the dev server. A launch and `app.deployed` that disagree are refused. `tests/default-lab.test.ts`, `tests/default-session.test.ts` ("app.launch", with a planted control) |
+| The product config's machine inputs (lane NS-B) | `src/machine-inputs.ts`: variables of one machine, never a product's choice, each optional (unset changes nothing) and shown in `resolvedConfig` as `machine.<VARIABLE>` with source `machine`, greyed when unset with how to set it. `CHOPSTICKS_BIN` (the Chopsticks adapter's `bin`), `PRODUCT_LAB_WORKER_CACHES` (absolute caches, worker i its PRODUCT_LAB_CACHE_DIR), `PRODUCT_LAB_BASELINE` (fast's People runtime and node from a verified fast baseline), `PRODUCT_LAB_NODE_LOG` (fast's nodes' `-l<targets>`), `PRODUCT_LAB_LIVE_ACCOUNTS` (`Person=<SS58 address>`: the account the host gives the app for a live person; addresses only, a wrong entry refused by its position and never echoed; not for the deployed launch). `tests/machine-inputs.test.ts` |
+| The product config's copies (lane NS-B) | `paseo-copy` and `previewnet-copy` are saved forks in `<output>/environments/<id>` (a worker's own with its output folder), in the lab's name's words, on the 1000-port block `forkPortBase` gives, in this order: `PRODUCT_LAB_FORK_PORT_BASE`, then `PRODUCT_LAB_PORT_BASE` + 1000, then 42000; plus 1000 per worker index (`PRODUCT_LAB_WORKER`), so worker 1 of a block at 13000 is at 15000. The entry shows the block and the variables that gave it; never a claimed block (a saved fork resumes only on the block it was made on). Pinned to Notes' folder, saved-folder ids and blocks. `PRODUCT_LAB_FORK_ATTACH=<base>` (with `PRODUCT_LAB_FORK_SNAPSHOT`) makes `paseo-copy` attach a running Engine fork of paseo-next-v2 instead (`src/fork-attach.ts`), and refuses `previewnet-copy` by name while set. `tests/machine-inputs.test.ts` |
+| The product config's Chopsticks copy of the local dev chain (lane NS-B) | `environments: { chopsticks: { chains, from: "fast" } }` (`src/chopsticks-of-fast.ts`, from Notes' `localChopsticksEnvironment`): the lab starts the chains relay-less from the locked release files lab.lock.json pins as the upstream (`<output>/environments/chopsticks-upstream`), then Chopsticks over them (`chopsticks/`, `CHOPSTICKS_BIN`); closed the other way, and a failed Chopsticks start closes the upstream and keeps its error. Each chain's copy is 2 ports after the local dev chain's port for it and its upstream 4 after, inside the lab's block; a chain the local dev chain does not make, or `fast: false`, is refused by name. No public network. `tests/chopsticks-of-fast.test.ts` (the definition equal to Notes' for a block at 13000) |
+| The product config's dev server | When none is written: `detectDevServer` (`src/default-dev-server.ts`) reads the `app/` folder's `package.json`, else the lab root's (an `app/` folder without one of its own keeps the dev server in `app/`; no `app/` folder runs it at the root: `appFolder`; Vite, Next, webpack-dev-server); a bare command is resolved to the app's `node_modules/.bin`, else the root's (`declaredDevServer`). A detected Vite dev server passes `VITE_PRODUCT_ID` and one `VITE_<CHAIN>_GENESIS` per chain (`VITE_DEV_SERVER_SETTINGS`, shown as `app.settings`, detected) unless `app.settings` names others. `tests/default-lab.test.ts` |
+| The product config's ports and workers | A lab without `ports` claims blocks of 100 in 20000-32699 (`NodeSystem.ports.next()`, `@product-lab/system-node`'s `claimPortBlock`; the window's and the local dev chain's blocks seeded by the lab's directory, so a reopened lab finds them again); `ports` or `PRODUCT_LAB_PORTS` names a range instead, carved from the top. The function form's `claimPorts(size)` (`LabPreparation.claimPorts`) gives exactly `size` ports from the same allocator for what the config runs itself (Notes' own sessions, 500), or refuses by name. `ports: { size }` (1-10000) makes the window's and its sessions' block exactly that size, seeded `<lab>:config` as `claimPorts` is, with the chains' 100 exactly beside it: under PRODUCT_LAB_PORTS from the top, refused naming the range, the size and what is left when it cannot hold them (before, a lab got at most half of what was left); `resolvedConfig`'s `ports` shows the block ("500 ports: 48100-48599"). A lab that states no size gets the blocks it got before. `tests/ports-size.test.ts` A `workers` declaration: each worker `PRODUCT_LAB_OUTPUT_DIR`, its own claimed ports or a slice of a fixed range. `tests/default-lab.test.ts` |
+| The product config's `advanced` | Today's definition fields the shape does not cover yet, merged over the translation: an app's, a host's or an adapter's fields one by one, `keepBetweenStarts` whole, other records by key, anything else replaces; each listed in `resolvedConfig` with its `advancedWhy`, an adapter by its label (`ADAPTER_LABELS`, `src/adapter-catalogue.ts`, held equal to each factory's by `tests/adapter-catalogue.test.ts`), never its code id; lint warns on a why for a field `advanced` does not set. `tests/default-lab.test.ts` |
+| The product config's versions (lane L4) | `productVersions` (`src/product-versions.ts`): the policy selects every component lab.lock.json pins (runtimes and polkadot-omni-node by `versions.runtime`, a pinned host by `versions.hosts`; `locked` by default) and, at `latest` only, runtimes and hosts the lock does not pin (a `locked` selector the lock cannot answer would refuse every run); sources for every component that can move, with polkadot-omni-node's added (`NODE_VERSION_SOURCES`: paritytech/polkadot-sdk, the whole tag as the version, the assets as the lock records them, ranked by `order` since polkadot-sdk's tags are not dotted versions; checked against the live repository's release listing on 7 October 2026: the lock's `polkadot-stable2606-2` and the newest stable release carry both assets under those names, and the latest published release, `polkadot-stable2603-7`, is a patch of an older line without them, which `order` ranks below 2606-2; `tests/product-versions.test.ts` replays that listing); a lock that is missing or pins nothing is declared under `unsupported["*"]`, so a mode's `latest` row says the lab has nothing to resolve, naming the lock (`tests/product-versions.test.ts`). |
+| The local dev chain's people (backlog 91; from Notes, 6 October 2026) | `src/people-dev/`, product-neutral, for the default session: `peopleDevGenesis(chains)` (People's people and people-lite collections at genesis, `relaylessTopology({ chains, ...peopleDevGenesis(chains) })`); `peopleOnboarding(options)` (a person per new actor: the truAPI CLI provisioner where an identity backend runs, else the lab attester, which reads the wallet's People member key and ring (`environments.fast.onboarding`: `"released"`, the default, with `releasedAllocCheck` in `src/people-dev/member-key.ts`: the ring-VRF entropy in TypeScript, per network (`<label>.<suffix>`: the label `environments.fast.personProduct`, by default the one the released truAPI host derives under, `DEFAULT_PERSON_PRODUCT`; the suffix the routes' namespace) as host-rust-core 0.23 derives it, pinned to its vectors, the released core's `ringVrfMember` and People's `Members` storage at the finalized block, printed in `alloc-check`'s lines; or `"truapi-cli"`, the CLI host's `alloc-check`, in product-lab's checkout, and in a product once the CLI host's locked release takes the lab's local endpoints (the official release, no patches; refused by name with #1166 when it does not; the locked 0.26.0 does; `hostLockFile` names another host lock); `truapiCliAllocCheck` runs it alone), recognises it by //Alice once People's sudo key is checked to be //Alice, prepares the ring on a fresh genesis and waits until the ring includes it; `memberStanding` reads where a member stands); `standInForXcm(environment, options)` (the lab answers each Bulletin allowance a relay-less People cannot send over XCM, by Bulletin's //Alice, declared as lab setup) and `xcmStandIn(environment)` to find it again, `skipNext()` being the lab's self-test hook. `personReadings(person, onboarding, people)` (backlog 160): a new person's screen (the app ready with their account) and People (the member key in a ring, and the lab's own read of `Members.Members` at the finalized head) readings, which the default session offers as `actorReadings` where its people are persons; the window shows them as the step's two checks. Only for apps that write to Bulletin or the Statement Store (the coordinator's rule, 6 October 2026). `tests/people-dev-onboarding.test.ts`, `tests/people-dev-member-key.test.ts` (the vectors, the alloc-check vector, the reader's lines and controls), `tests/people-dev-xcm-stand-in.test.ts`, `tests/people-dev-readings.test.ts`; live cross-check: `tools/verify/tests/member-key-live.test.ts` |
+| Keep chain and people between starts (backlog 183; from Notes, 6 October 2026) | `src/people-keep/`, product-neutral: `keptPeople(options)`, the default session's entry point. A kept start (`keep`, a host that keeps app storage, an environment that names its chain generation) gets the folder `<root>/<environment>/<generation>` with `saved()` (the people to reopen, with their wallets), `remember`, `forget` (a deleted person, with their folders), `hosts()` (the truAPI CLI host's state root in that folder) and `fixtureState()`; at the start a replaced generation's people are discarded and those of generations no longer kept swept (`discard.ts`), each said in `lines`. `SavedPeople` (the records, bound to the generation) and `PeopleLifecycle` (Stop and Start keeping wallet, place and account). `tests/people-keep-*.test.ts` |
+| Default keys | `definition.keys ?? new Sr25519KeyDerivation()`: a lab whose secrets need a signer (`secrets.signer(name)`) does not need to declare a key adapter itself |
+| Default chain connections | `connectChains` (`src/chain-connections.ts`): one live `ChainConnection` (`@product-lab/chain-papi`'s `PapiChainAccess`) per chain the started environment declares (`RunningEnvironment.routes`, and since 30 September 2026 each chain its offer lists with a loopback WebSocket endpoint but no route, such as a Chopsticks fork: backlog 16, so the lab can check a time advance itself; since 3 October 2026, backlog A2, a routed chain off this machine connects only under the routes' own `publicRoutes` reason, passed as `publicEndpoint`, never without one), given to `SessionContext.chains`/`ActionContext.chains`/`AssertionContext.chains` (core/lab's `CompileOptions.chains`) and closed with the environment. Since 4 October 2026 (backlog 91) it also builds `readers` (`ChainReaders`, given to `AssertionContext.readers`): `statements(chain)` (`RpcStatementStoreReader` on that chain's endpoint) and `bulletin()` (`BulletinContentReader` through the runtime's `JsonRpcClient`), on this machine only (a chain the environment does not run, or one routed off this machine, is refused, without printing its URL); `chainConnector` (same file) is the matching `ChainConnector` a lab-level integration (`defineLab({ integrations })`, for example `@product-lab/deploy-bulletin`'s platform integration) uses instead of building its own `PapiChainAccess`/`PapiTransactionSubmitter` pair |
+| Default session | `defaultSessions` (`src/default-session.ts`, core/lab's `CompileOptions.defaultSessions`): used only when a lab declares environment, host and app but no `sessions()` of its own. Since backlog item 71 (1 October 2026) it serves every declared app the environment offers (one dev server each; one it cannot offer is skipped with a notice) and creates any number of actors (`createActor({ name, signal })`): each actor has one wallet (one identity) for all its apps, opens the first declared app when it is created and another with `openApp` (`{actor} opens {app} at {route}`), each in a host session of its own behind a proxy of its own (the first actor of an app uses the proxy it was served with; later actors get a new proxy in front of the same dev server), so bridges, updates and readiness never mix between actors. `defaultSessionPage(actorId)` (`src/default-session-page.ts`) is the page of the app the actor has open. Closing it runs every stop step (session, host, app server, browser) and rejects with every failure (an `AggregateError` for more than one), so a process left running is reported; a start that fails keeps its own error first and adds any cleanup failure to it. Live proof: `examples/minimal`, `examples/counter-contract` (docs/verification/2026-09-25-minimal-example.md). |
+| Default session: browser, host, app server and funding | One browser, the declared host, routes to every declared chain plus closed loopback routes for the well-known ones it does not (`@product-lab/core/host`'s `hostRoutesFor`), the app's dev server as the lab declares it (`apps.<id>.devServer`; default: Vite for `<lab root>/app` with `VITE_PRODUCT_ID` and one `VITE_<CHAIN>_GENESIS` per declared chain) behind the lab's proxy (see "App server" below), one throwaway host wallet (created lazily, on the scenario's own "{actor} is a new actor" step, not eagerly), and dev-authority funding on every chain with `Balances.transfer_keep_alive` (best-effort per chain; an app-level `fundingSigning` names a runtime's own signed-extension needs, by chain id). |
+| Default session: readiness and account | Since backlog item 62 it asks the app's page for nothing: the actor's account is `HostSession.account()` (derived from the identity; the adapter catalogue gives the truAPI CLI and WASM test host factories a `Sr25519ProductAccounts`), funded by public key in whatever form it is written, and the app is ready as `apps.<id>.ready` declares, by default when the host reports it connected (`src/app-readiness.ts`: `waitUntilReady`, `locate`, `readPageAccount`, exported for a lab's own `sessions()`). A host that cannot tell the account falls back to a declared `apps.<id>.account`, and otherwise the session refuses with what to declare. Since item 63 it hands the runtime the host's record of the actor's signing requests (`LabEnvironment.signing`). A lab's own action or assertion code reaches the actor's page through `defaultSessionPage(actorId)` (headless runs get no `ActionContext.ui`) and can navigate it (`AppPage.open(path)`, `.reload()`) for a product whose app takes its subject from the URL. |
+| Default session: readings and funds | What the window shows of a person (7 October 2026). Where people are persons (the `persons` launch option), `actorReadings(actorId)` gives the step that introduced them its two readings (`personReadings`, `src/people-dev/readings.ts`): their screen (the app ready, with their account) and People (the member reader's standing, named in the reading's `how`, and the lab's own read of `Members.Members` at the finalized head), a side it cannot read a failed reading. `observe(actor)` (the window's "Finalized chain state") adds `funds`, the person's free balance on every connected chain at its finalized head, or `fundsUnread` with why (`observedFunds`, `src/actor-funds.ts`); `fundsOf` is the same read for `{actor} is a new actor with no funds` ("Someone with no funds" below). Tests: `tests/people-dev-readings.test.ts`, `tests/actor-funds.test.ts`, `tests/default-session.test.ts` ("observe shows the actor's funds…", backlog 160) |
+| Default session: kept people (backlog 183, 6 October 2026) | `src/default-session-keep.ts` (`sessionKeep`, over people-keep's `keptPeople`): with "Keep chain and people between starts" on and the truAPI CLI host, the default session puts the host's state root in `<lab>/.product-lab/kept/<environment>/<generation>`, opens every person kept there again at its start with their own wallet (never funded again; one that cannot open is said in the notices and stays kept; not when a fixture restore replaces them), keeps each new person it makes, and offers Stop (listed, stopped, wallet kept), Start (same wallet, same account, else refused; back in their place) and Delete (gone for the next start too), and its `fixtureState`; a person opened again carries `origin` "saved" (made when, stored where). Another host or an environment that names no chain generation: new people, said. `tests/default-session.test.ts` ("backlog 183", with controls: deleted saved identities, another generation, keep off) |
+| Session placement | Backlog 108 (5 October 2026): the default session takes the lab window's placements (`LabEnvironment.placeSessions`). An identity on a host that declares `capabilities.placement` (the WASM test host) opens its sessions where the window places it (its tile); running ones reopen there with the same identity and account, never funded again (`src/session-placement.ts`, `reopenPlaced`), and go back to the host's own browser with `undefined`. Run recordings' frames of each identity's page: `src/session-frames.ts` |
+| Session ports (backlog 101) | What the default session starts on its own (its apps' dev servers and proxies, the closed routes, the origin gates) takes `SessionContext.sessionPorts`, which core resolves when it opens the session (`resolveSessionPorts`, `core/application/src/orchestration/lab/session-ports.ts`): `PRODUCT_LAB_SESSION_PORTS` when set; else the lab's own block, the hundred ports holding `defineLab({ port })` minus every port the lab declares in it (the lab's port, the environment's endpoints, any `port` or `{ from, to }` in its hosts' options, its apps' fixed dev-server ports), the longest run left (examples/minimal: 60000-60049); else, for a lab with no `port`, the fallback 40000-40999 (`FALLBACK_SESSION_PORTS`). The first progress line says which range and why; the fallback is also a warning. A block with no run of four free ports refuses to start, naming the ports and the variable. A lab with `sessions()` of its own reserves its own ports, so its hosts' gates get the variable or the fallback, never its block. Until 4 October 2026 the default was free ports from 1024, outside every lab's block. Tests: `core/application/tests/session-ports.test.ts`, `tests/default-session.test.ts` |
+| Identities created together | `identityFunding` (`src/identity-funding.ts`, 4 October 2026, fork cut 2 in the framework): the default session creates the identities a scenario names together at once (`actorCreation: { concurrency: 4 }`, unless the host declares `HostCapabilities.concurrentSessions: false`, as truapi-wasm and dot.li do) and funds them in one `Utility.batch_all` per app and chain that waits for finality once (`FundingBatch`, `@product-lab/core/chain`). A chain without it funds each alone; a batch the chain reverts is sent again identity by identity, so the one that fails is named; identities are listed in the order their creation started. |
+| Someone with no funds | `actorFunds` (`src/actor-funds.ts`, backlog 35c): the default session's `createActor({ funds: "none" })` opens the actor's apps with no funding pass, and its `fundsOf(actorId)` reads the actor's free balance (`System.Account`) on every connected chain at that chain's finalized head (an account a chain has never seen holds 0), which `{actor} is a new actor with no funds` checks. Not offered on a public network, where the session creates no identity of its own. Since 7 October 2026 the session's `observe(actor)` (the panel's "Finalized chain state") shows the same read as `funds`, on every network with a connected chain, or `fundsUnread` with why it could not be read (`observedFunds`). Tests: `tests/actor-funds.test.ts`, `tests/default-session.test.ts` ("observe shows the actor's funds…"). |
+| New identities on a public network | `publicIdentityCreation` (`src/public-identities.ts`, 4 October 2026): when a writable public target declares `newIdentities`, the default session's `createActor` has the network's own identity backend onboard the identity (`truapiCliProvisioner({ network: { preset } })`) and funds it from the `funder` secret on the chains named (`identityFunding` with `chainIds`, `beforeSubmit` reading the funder's balance, `required`). Refused by name before the backend is contacted: another host, a network the CLI has no preset for, a People genesis that is not the network's, the session's cap, a funder that cannot sign or does not hold the amount and a tenth more, a chain to fund that is not connected. Every identity made is appended to `<run>/identities/identities.jsonl` ([the domain README's `newIdentities`](../core/domain/README.md#folders-and-exports)) |
+| Root calls | `rootCallSupport` (`src/root-call-support.ts`, 4 October 2026): what `defineLab({ rootCalls })` needs to make a call (core's `CompileOptions.rootCalls`): a transaction submitter per chain (`transactionSubmitter`, with the policy's signed extensions for that chain) and a journal of each environment's root calls under `<lab root>/.product-lab/root-calls/<environment>-<time>/`. The decision and the checks are core's ([the domain README's `root-calls/`](../core/domain/README.md#folders-and-exports)) |
+| The lab | core's `SourceLabLoader` over `ModuleLabSource` (a lab.config.ts, reloaded when edited with `reload`) or `DefinitionLabSource` (a definition given in code), from `@product-lab/lab-module` (L1: the adapter reads, core validates and compiles); the selected factories are appended to those the lab registers itself (`environmentFactories`, `hostFactories`) |
+| Feature files and runs | `GlobFeatureSource` and `CucumberFeatureRunner` (`@product-lab/features-cucumber`), given core's `customStepSource` |
+| Host verification | `ModuleHostVerifier` (`@product-lab/contract-host`), `ModuleHostTools` (`@product-lab/lab-module`) |
+| UI extension bundles | `TranspiledClientBundles` (`@product-lab/lab-module`, Phase 5): the `ClientBundleChecker` `LabRuntimeService` uses for `extensions()` and `product-lab lint`'s `client-bundle` rule |
+| Fixtures | `NodeSystem.trees` (`NodeTreeCloner`, also in `forLab` as `SystemPorts.trees`, so environment adapters copy their state copy-on-write) and `NodeSystem.fixtures(root)`: a `FileFixtureStore` at `<lab root>/.product-lab/fixtures`, the runtime's `fixtures` port |
+| Fixture sharing | `fixtureSharingPorts()` (`src/fixture-sharing.ts`): `FileFixtureArchives` and `checkoutVersions(root, engineState)` (the lab lock's components, the truAPI host lock, and the Engine build prepared in `<PRODUCT_LAB_CACHE_DIR>/engine`: its `resolvedRef`, `tested: false` with `testedRef` for a non-pin `--engine-ref` build, or `testedEngineRef` with `prepared: false` when none is prepared) for a bundle's provenance, the runtime's `fixtureSharing` port. `fixtureSources(declared, labRoot, env)` builds one source per declaration: `GithubReleaseFixtureSource` (global `fetch`, `GITHUB_TOKEN` or `GH_TOKEN` when set, a `NodeCommandRunner` for `gh attestation verify`) or `DirectoryFixtureSource` (its path relative to the lab root). The fixture cache is `<PRODUCT_LAB_CACHE_DIR>/fixtures`. Test: `tests/fixture-sources.test.ts` |
+| Remembered RPC | `NodeSystem.rpcChoices(root)`: a `FileRpcChoices` at `<lab root>/.product-lab/state/rpc.json`, passed to the runtime as `rpcChoices` (the lab window's RPC per chain, 3 October 2026) |
+| Remembered options | `NodeSystem.optionChoices(root)`: a `FileEnvironmentOptionChoices` at `<lab root>/.product-lab/state/environment-options.json`, passed to the runtime as `optionChoices` with `system.machine` (backlog 184). `createLabRuntime({ stateDir })` moves both remembered files into a test run's own folder, so a run never changes what a person chose |
+| Renamed environments' state | `moveOldEnvironmentState(root, { offered, stateDir })` (`src/old-environment-state.ts`, config redesign): on a lab's first load, before anything starts, what the machine keeps under a pre-redesign id (`OLD_ENVIRONMENT_IDS`, the four the redesign renamed) moves to the new id once: saved forks and kept dev chains (`.product-lab/environments/<id>[-light]`), kept people (`.product-lab/kept/<id>`) and the remembered option; a kept local dev chain (`environments/workspaces/<id>[.versions-<key>]`) takes the new id in its folder and its `workspace.json` name, and the local dev chain's folders move once out of `environments/relayless/` into `environments/`. One logged line each; with both present nothing moves and the line says which one is used; a lab still offering the old id keeps its folders (`tests/old-environment-state.test.ts`) |
+| The running lab | `NodeSystem.runningLab(root, path?)`: a `LockRunningLabRecord` at `<lab root>/.product-lab/running/<config name>` (`runningLabRecordPath`, one per configuration: `lab.config.ts` and `lab.live.config.ts` in one folder never refuse each other) on the lab's `FileLockManager`, passed to the runtime as `runningLab` (B1 step a, backlog B2). Not moved by `stateDir`: it belongs to the folder. `PRODUCT_LAB_RUNNING_DIR` (`src/running-lab-variable.ts`) keeps it elsewhere, for labs that share a folder on purpose and never a chain or port (the CLI's test fixtures, one directory per test file; an example's test and e2e scripts, `@product-lab/cli/own-running-record`); a person's lab leaves it unset. `tests/running-lab.test.ts` holds it from a real second process, reads it, kills that process (the record is stale, never read) and releases a new one |
+| Beside the lab window | B1 (6 October 2026; [the MCP README's Tools](../entrypoints/mcp/README.md#tools)), `src/attached/`: `connectLabRuntime(running, local)` drives a window's lab through its runtime API (`/api/runtime`, the record's token as a bearer; `WindowClient`): the runtime's live calls (`ATTACHED_RUNTIME_CALLS`) go to the window, declarations and files stay the local runtime's, a mirror keeps `environmentState()` and `snapshot()` current at each `sync()`, and runs are handles over long-polls (`startScenario`). `followRunningLab(own)` attaches or leaves at each `sync()` as the record changes. `labWindowLauncher` (MCP `lab_open`, `lab_close`) starts the window detached through `ProcessRunner`, recorded in `<lab root>/.product-lab/lab-window`; `headlessLab` (MCP `where: "headless"`) starts `product-lab dev --own-lab --record <dir>` on the lab's second worker block. `createLabRuntime({ runningRecord })`: `false` keeps no record, a path records elsewhere. Contract test: `entrypoints/panel/tests/attached-runtime-contract.test.ts`, the same behaviours on a lab of its own and through the window |
+| Breakpoints | `NodeSystem.breakpoints(root)`: a `FileBreakpointStore` at `<lab root>/.product-lab/breakpoints.json`, passed to the runtime as `breakpoints` (backlog 17) |
+| Lab window settings | `NodeSystem.labSettings(root)`: a `FileLabSettingsStore` at `<lab root>/.product-lab/settings.json`, passed to the runtime as `labSettings` (panel Settings, read when the lab window starts) |
+| Fork freshness | `src/fork-live.ts` (backlog 17c, moved from an example's own local fork): `readLiveRuntimes` (env-engine's `LiveRuntimeReader`: each forked chain's runtime now through the `deployed` version source, all at once, never rejecting), `downloadLiveCode` and `requireLiveCode`, and `liveCodeFetcher()` (env-engine's `LiveCodeFetcher`: the live code, refused unless it hashes to the live code hash). A lab that owns a saved fork passes them to `savedForkUpdates`. Test: `tests/fork-live.test.ts` |
+| Application | `LabRuntimeService.create` (`@product-lab/application`) |
+| Hot reload sources | `appSources: { watcher: NodeSourceWatcher, commands }` for `LabRuntime.watchApps` (backlog item 5); only `product-lab dev` watches. The default session offers `reloadApp` (its one actor's page loads the app again in its host session and must show the same account) and `appUpdates()` (an `AppUpdateHub`: what its proxy sees on the dev server's update socket), so the runtime holds the dev server's own updates during a step; no variable is passed to the dev server for it |
+| Hosts a lab does not declare (lane H, 6 October 2026) | `SessionHosts.unconfigured()` (`src/session-hosts.ts`, words in `src/host-words.ts`, `unconfiguredHost` exported: "truAPI CLI", "truAPI WASM"): every registered host adapter no declared host uses, in plain words ("truAPI WASM", what it is for) with the config that turns it on; none for a public target. Reported as `LabEnvironment.unconfiguredHosts()`; New identity's menu lists them greyed (`tests/session-hosts.test.ts`) |
+| A host's probed capability (backlog 247, 9 October 2026) | `SessionHosts.entries()` lists what each host can probe (`EnvironmentHost.probes`, from `HostProvider.probes`), and `SessionHosts.probe(reference, request)` asks the host a reference names, created but not prepared, to probe a capability (`HostProvider.probe`; undefined when it has none), which the default session offers as `LabEnvironment.probeHost`; `SessionHosts.current(host, reference)` gives a person's host with the limits it states now, so the default session lists each person with a limit a probe settled since they opened. `XcmStandIn.storeProbeBlob()` stores a small blob on Bulletin by the stand-in's sudo path (the lab's probe account given room by //Alice, then the blob stored with it, each resolved on inclusion, declared as lab setup, `PROBE_BLOB_STORED`) for such a probe. `tests/session-hosts.test.ts` |
+| A person's host as views show it (C4 and C6, 6 October 2026) | `SessionHosts.shown(host, reference)` adds the lab's own line on the host (`hosts.<id>.description`, never its adapter's label), which says what the host's `limits` mean for the app; the default session puts each session's `networkNote` on it (`withNetworkNote`), at its start and when the lab window places it or takes it back, so the row and the tile read one source (`tests/session-hosts.test.ts`, `tests/default-session.test.ts`) |
+| Several hosts (backlog 28) | `SessionHosts` (`src/session-hosts.ts`): the default session's declared hosts, the default one prepared at its start and any other created and prepared the first time `createActor({ host })` puts an actor on it (a host that fails to prepare is disposed and forgotten). Which hosts an actor may be put on is decided at the start without starting anything and reported as `LabEnvironment.hosts()`: a public network keeps its one host, dot.li is never offered per actor (its sessions are not signed in; signing unproven), a host whose factory's `routingProblem` names a missing chain cannot serve the environment, a host not on this machine says what is missing. Each host gives its plain name (`EnvironmentHost.label`: the lab's `hosts.<id>.label`, so variants of one kind read apart, else `HostProvider.label` of the host created but not prepared: "truAPI CLI", "truAPI WASM"), and one line on what it is for (`EnvironmentHost.description`: the lab's `hosts.<id>.description`, else its adapter factory's label), which New identity's host menu shows, and the hue views draw its chips in (`EnvironmentHost.color`, `SessionHosts.color`:
+the lab's `hosts.<id>.color`, else its adapter factory's `color`, so a kind's variants share it; an actor's
+`ActorSession.host.color` is its host's). Each available host also says whether it applies per-actor conditions (`EnvironmentHost.conditions`, read from the host created but not prepared), so a condition on an actor of another host is judged by that host (backlog 31 with 28, 5 October 2026), and `environmentConditions` takes the other hosts' capabilities: when only they declare conditions, the default host's actors are refused by name (`DEFAULT_HOST_HAS_NONE`). `SessionHosts` is exported, so a lab's own `sessions()` can give its actors several hosts the same way (`examples/notes/lab/sessions.ts`). Tests: `tests/session-hosts.test.ts` (the real WASM and dot.li routing rules) Backlog 185: each host carries the options its adapter declares with the lab's values (`EnvironmentHost.options`, `HostRegistry.optionSettings`) and its `aliases`; `choose(reference)` resolves a host reference (an id, an alias or the host's plain name, with per-identity values), refusing by name an option the adapter does not declare per identity; one host is created per reference, with the identity's values over the lab's options (validated by the adapter's schema); `optionsOn(reference)` is what views read after the host's name. Test: `tests/host-options.test.ts` (a third adapter with options of its own). |
+| App server (backlog items 64 to 66) | `serveApp` (`src/app-server.ts`, exported with `ServeAppRequest`, `ServedApp`): starts an app's dev server as declared (the domain's `AppDevServer`), waits until it answers, opens the lab's proxy in front of it (`NodeSystem.appProxies`: `NodeAppProxies`) and asks for the document once, so its framing headers are known. A dev server that exits or never answers fails with the command, its log and the field to fix. `AppUpdateHub` (`src/app-updates.ts`) gathers the proxies of one session for the runtime (`follow`, `attach`). The default session uses both: the page's address is the proxy's, the host's bridge script is given to the proxy through the app address callback, the start says which setting names the dev server was given, an app that refuses every frame is said in the notices and the progress with its header and value (never removed), and a socket the lab does not understand is said once. A lab's own `sessions()` calls the same functions (`examples/notes/lab/actors.ts`). Tests: `tests/default-session.test.ts` (the real proxy, a stand-in dev server and host). Backlog A5: `deployedAppServer` (`src/deployed-app-server.ts`) plans `apps.<id>.deployed` as the app's server: the gateway program (`src/gateway-program.ts`, which wires `fetch` as `--ipfs-gateway`'s transport; it serves `app.<name>`'s contenthash, else the name's own, as hosts do, accepts a pin of either and serves the one it matches, and the served line names which; the product id stays the name) with the name, the pin, the environment's Asset Hub and Bulletin, `--allow-public` and the IPFS gateway on a public network, and with `resolveOn` the read-only public resolution (`--resolve-asset-hub`, `--allow-public-resolve`; the starting and served lines name the endpoint and the block, from the report's `publicRead`); refuses a missing chain or a name of another network by name; the default session serves it through `serveApp` with the name as the product id (`tests/deployed-app-server.test.ts`) |
+| Platform integration (`@product-lab/composition/platform`, L1) | `platformIntegration` and `PLATFORM_REQUIREMENTS`: the opt-in DotNS, Bulletin, statement and contract actions composed from `@product-lab/deploy-bulletin`'s parts with core's authoring (moved from the adapter, which may not author integrations); `examples/counter-contract` and `tools/verify/live/deploy/*` import it. Since 6 October 2026 (backlog 149) the contract deploy acts as no actor (`actor: "none"`: the platform's signer deploys, so it runs as a setup step) and reports its two Asset Hub transactions (`Revive.map_account`, `Revive.instantiate_with_code`) to its step (`reportedPorts`, `src/platform/reported-ports.ts`): the run lists them, and the host-bypass audit counts them as the lab's setup, so a clean deploy no longer reads "Host bypass: warning" |
+
+Pre-onboarded actors and public networks in the default session (3 October 2026, backlog A3 and A6): the lab's pre-onboarded actors (`SessionContext.preOnboarded`) are listed (`preOnboarded()`) and opened by name (`openPreOnboarded({ name })`): `preOnboardedIdentity` (`src/pre-onboarded-identities.ts`) reads the secret and takes the wallet phrase's BIP-39 entropy (a derivation path, a password, a 0x seed or a bad checksum is refused naming the secret, never echoing the value); the identity is never funded, its row says `kind: "preOnboarded"`, a declared `account` must be the one the host gives the first app, and opening it again returns the open session. On an environment with `offer.public` the session offers no `createActor` and funds nothing; on a read-only one an existing identity's host denies every request (`approvals: "deny-all"`).
+
+A default session first stops what an earlier lab process, killed before it stopped them, left running in `.product-lab/sessions/` (`ProcessRunner.reapAbandoned`, backlog 13a; a session whose lab process still runs is left alone) and says so in its progress.
+
+Options: `config` (a file or its directory; default `lab.config.ts` in `cwd`), `definition` and `root`
+(a lab given in code), `cwd`, `allowPublic` (start environments that are not local), `reload`, `inspect`
+(load for `env show` only). An adapter kind the root does not know is refused with the known kinds.
+
+Also exported: `hostRegistry(hostAdapters)` (a host registry over the root's factories for the host
+adapters a lab selects, for a lab's own code outside a session, such as an example's WASM host), `labConfigPath`, `processEnvironment` (the only reader of `process.env`),
+`withSelectedAdapters(definition)` (the definition with its selected adapters' factories, for a lab's
+own tests that resolve topologies without starting anything), `NodeSystem`, the catalogues,
+`GATEWAY_PROGRAM` (the deployed-local gateway executable a host runs as the app,
+`composition/src/gateway-program.ts`; on SIGINT/SIGTERM it closes the gateway and exits 0, or reports a failed close and
+exits 1: `composition/src/gateway-shutdown.ts`), and the default session's pieces a lab with no `sessions()` of its
+own may still need directly: `defaultSessionPage(actorId)`, `readyAccount(app)`, `chainConnector(signing?)`,
+`connectChains`, `transactionSubmitter` (refuses a chain `connectChains` did not open; see "Default chain connections"/"Default session" above). A lab with its own `sessions()` opens its pre-onboarded actors (`defineLab({ actors })`) the way the default session does with `preOnboardedIdentity(actor, secrets)` (the wallet phrase's entropy, refused without echoing it) and lists them with `preOnboardedViews` (`src/pre-onboarded-identities.ts`; Notes since backlog A7).
+
+`src/feature-runtime.ts` (Phase 4): `featureRuntime()` builds the runtime of a bundled feature run inside the run's
+own process (the lab from `PRODUCT_LAB_CONFIG`); the root gives its path to `CucumberFeatureRunner` as
+`runtimeModule`, and the runner's support imports it by path (the adapter never imports the composition root).
+
+Subpath `@product-lab/composition/cucumber` (Phase 4): `registerFeatureSteps` and `scenarioOf` from
+`@product-lab/features-cucumber`, for a Cucumber support process only (the testing kit's
+`registerLabSteps`), so generated steps register with the Cucumber copy the feature adapter runs. Its
+`registerFeatureSteps` passes core's `customStepSource` (the lab's `step()`s) unless the caller gives another; the
+root also passes it to `CucumberFeatureRunner` (`customSteps`) and exports it from `src/feature-runtime.ts` for
+bundled runs (L1: the adapter no longer imports core). The CLI,
+the MCP server and the panel never import it, so they never load Cucumber.
+
+## Who calls it
+
+| Caller | File |
+| --- | --- |
+| CLI | `entrypoints/cli/src/main.ts` |
+| MCP server | `entrypoints/mcp/src/main.ts` |
+| Panel server (standalone) | `entrypoints/panel/src/main.ts` |
+| Cucumber hooks | `entrypoints/cucumber/src/main.ts` (`registerLabEnvironmentHooks`) |
+| Examples | `examples/minimal`, `examples/counter-contract`, the notes E2E panel tests; another example (its Node system, the WASM host through `hostRegistry`, its acceptance runner). `tools/verify` does not use it: it wires its own Node system (`tools/verify/src/node-system.ts`) |
+
+Versions (`src/versions/`, Phase 6): `FileLockStore` at `<lab root>/lab.lock.json`; the policy read
+from the loaded lab on every operation (`defineLab({ versions: { policy } })`; a lock entry it does not
+name is `locked`); sources built from the lab's declaration through an open registry
+(`VERSION_SOURCES`, `src/versions/version-source-catalogue.ts`). Routing is by selector and by
+provenance, not by component kind (audit G1):
+`sourceKindForSelector` sends `deployed` to the deployed-runtime source (only over the endpoints
+declared in `versions.networks`, opened with `publicEndpoint: { reason: "resolve deployed runtime" }`
+and recorded without credentials) and a latest release, an explicit version, `release:` or `git:`
+to GitHub, runtimes included (a runtime's release needs a `versions.sources` entry naming its
+asset); `sourceKindForLocked` sends a locked `network` entry to the deployed source and a
+`github-release` or `git` entry to GitHub. A latest release or plain version of a component declared in
+`versions.npm` goes to the npm source (`NpmVersionSource`, backlog 27, the WASM test host's package), and so does a
+locked `npm` entry. With no `versions` declaration nothing is resolved, but
+`versions verify` still fetches a self-describing locked artifact (`file`/`file:<target>` digests
+with `asset`/`asset:<target>` attributes) or a git entry from its own recorded repository, so the
+example locks verify. A locked runtime `code` hash is never observed from a release asset: it stays
+in `unobserved` with the note `CODE_NOT_OBSERVED_NOTE`. `GITHUB_TOKEN` only when set, never logged. `deployedRuntimeSource(networks, clock)` (exported) builds the same `deployed` source over given endpoints, for a consumer that compares a fork with the live network outside a versions operation (an example's local-fork freshness line). Environment starts resolve the run's versions through them and pass the resolution to the adapter and the hosts; a resolution recorded at run start (`PRODUCT_LAB_VERSIONS_RESOLUTION`, set by `product-lab test`) is reused as it is (`recordedRunVersions`).
+
+| | |
+| --- | --- |
+| Nx project | `composition` |
+| Tags | `scope:composition`, `type:composition` |
+| Depends on | `scope:core` and `scope:provider` packages |
+| Used by | `src/main.ts` of each entry point (lint: no other entry point file), the four examples; `tools/eval` packs it into the umbrella package |
+
+Tests: `bunx nx run composition:test` (a lab file and a lab in code with selected adapters, feature
+listing, the host tools default, an unknown adapter kind, a lab's own environment and sessions
+receiving the system ports and the browser launcher; the default session's validation (one app,
+one host, the system ports it needs), its close and cleanup failures being reported (loopback app server on
+an ephemeral port), and `connectChains`'s empty case; `tests/error-reporting.test.ts`: a public route connected under its routes' opt-in, the gateway's close on a signal and
+`transactionSubmitter` refusing a foreign chain; `tests/chain-readers.test.ts` (backlog 91): the readers `connectChains` builds, Bulletin's bytes read through the lab's RPC client and checked against their CID, and a missing chain, a missing RPC client and an endpoint off this machine refused; version routing, and
+`tests/versions-verify.test.ts`: the example locks verified against a loopback fake GitHub API,
+with a changed asset, a missing release or asset, an undeclared entry and a `deployed` runtime as
+controls). `tests/fake-chain-access.ts` is a typed `ChainAccess`/`ChainHistory` stub for those tests (every read throws
+unless the test assigns it), in place of double type assertions (q10-types). The default session and default chain connections were checked live against examples/minimal and examples/counter-contract.
+
+## Locked setup artifacts
+
+The composition root supplies `GitHubReleaseArtifacts` through `ArtifactStore` and applies `PRODUCT_LAB_HOST_BIN` when a lab's host names no path of its own; together with a resolved `host:truapi-cli` it is refused (`TruapiCliHostFactory.create`), never silently ignored. `PRODUCT_LAB_HOST_ROUTE` (backlog 27), set by a suite for a row's run, becomes the truAPI CLI and WASM factories' `routeFile`: the row's resolved release runs as its route says. The WASM factory also gets the lab's cache directory (`PRODUCT_LAB_CACHE_DIR`), where it installs a release a row resolved from npm. The default session accepts optional `PRODUCT_LAB_SESSION_PORTS=from-to` (at least four ports) for app/closed-route isolation; without it, the lab's own block (see "Session ports" above), never ports from 1024.
+
+## Local compatibility reports
+
+`createLabRuntime` supplies suite file access, optional observed-version collection (`PRODUCT_LAB_OBSERVED_VERSIONS`), optional environment-start timing (`PRODUCT_LAB_RUN_TIMINGS`: a `RunTimingsFile` as `recordEnvironmentStart`; both variables are set per suite row by `RunSuite`, never by hand), and a `NotifierFactory` choosing `FileNotifier` or `NoopNotifier`. No notifier contacts an external service. Consumers still use the `LabRuntime` driving port. Test with `bunx nx run composition:test`.
+
+The default single-actor session advertises `createActor` only until it has created its one actor, so clients can distinguish a full session from one able to create an identity.
+
+`tests/scenario-scope.test.ts` exercises the actual composed runtime and compiled
+sentences with fixture environment/session I/O: multiple actors share a feature
+service, identical scenario titles remain isolated, legacy run cleanup preserves
+feature owners, and a failed check does not clear another feature’s state. These
+are orchestration tests, not browser or real-chain evidence.
+
+The default runtime wires `FileSuiteEvidenceBundles` as the optional local suite execution-evidence store. It preserves row resolution/report correspondence for lock proposals (`LabRuntime.proposeLock`, G2); it introduces no network access or version-source routing changes. `tests/propose-lock.test.ts` runs the real producer (`RunSuite` with a fake feature runner and version source) into `FileSuiteEvidenceBundles` and `FileLockStore` on disk, proposes and writes, and tampers each sealed file, a dry-run suite, failed and unsupported rows and a changed lock (each refuses with its own code, nothing written).
+
+## Checks after each step
+
+`createLabRuntime` gives the runtime what backlog 40's checks need:
+`PixelmatchComparison` (`@product-lab/visual-pixelmatch`), `FileVisualBaselines` on the lab's directory
+(`@product-lab/storage-filesystem`) and `PRODUCT_LAB_BASELINES` (an invalid value is refused when the runtime is
+created). The default session's `LabEnvironment.frames` also offers `accessibility`: `PageFrameCapture`'s scan with
+axe-core, imported only when a scan runs. A lab's own sessions that build `PageFrameCapture` get the same scan.
+
+On a device profile (backlog 31c), `PRODUCT_LAB_DEVICE=<name>` (set by
+`product-lab test --devices` on each run) resolves against the browser adapter's named devices when the lab loads (an
+unknown name refuses the load, with the nearest names) and `deviceBrowsers` (`src/device-browsers.ts`) wraps the lab's
+launcher so every browser its sessions launch emulates the device in each page and context; the device's name goes to
+the step checks for its baselines. `LabRuntimePorts.devices` gives the runtime the same catalogue
+(`playwrightDevices`, imported when asked).
+
+## Run recordings
+
+`createLabRuntime` wires Phase 9's recordings: a
+`FileRecordingStore` per recordings directory (`<lab root>/.product-lab/recordings`, or `PRODUCT_LAB_RECORDINGS_DIR`,
+relative to the working directory) and `RecordingSettings.fromVariables` over the process's variables
+(`PRODUCT_LAB_RECORDINGS` `frames`/`steps`/`off`, `PRODUCT_LAB_RECORDINGS_KEEP`, `_MAX_AGE_DAYS`, `_MAX_MB`; an invalid
+value is refused when the runtime is created, naming the variable). The default session (a lab without `sessions()`)
+offers `LabEnvironment.frames`: its actor's own page, imaged by `PageFrameCapture` from `@product-lab/browser-playwright`,
+imported on the first frame. `tests/recordings.test.ts`. Since backlog 23 it also offers `LabEnvironment.console`: what
+each identity's apps print, followed by `PageConsoleWatch` from `@product-lab/browser-playwright` on every app document
+it opens, again after a reload or a new path, and no longer once the app closes; an app whose document reports nothing
+is named as unwatched (`tests/default-session.test.ts`). Since backlog 41 it offers `LabEnvironment.hostRequests`: each
+app's host record of what it was asked (`approvals.decisions`), by app, `undefined` for a host without one. Since
+backlog 31 it offers `LabEnvironment.conditions` when its host declares `conditions` (`src/actor-conditions.ts`): an
+identity's control applies to every host session it has open (one per app), none when any of them carries no control;
+what the host declares it cannot apply is the environment's `unavailable`; the control also names the identity's local
+links to its hosts (`localLinks()`, lab-window finding 2d: a lab-window tile exempts them). `NodeSystem.conditionedLinks`
+(`NodeConditionedLinks`) reaches the host as `system.conditionedLinks`. Since backlog 92 the session opens origin gates
+in front of its local nodes (`sessionChainGates` from `@product-lab/core/host`, over `NodeSystem.chainGates`): once,
+the first time a host asks (the hosts get `chainGates` with their dependencies; a deny-by-default truAPI CLI or WASM
+host asks in `prepare()`, every other host ignores it and keeps the routes as they are), on ports from the session
+range, kept from a failed opening and closed with the session. `PRODUCT_LAB_CHAIN_GATES=off` opens none (a negative
+control only; the session says so). A host a lab's own `sessions()` creates through the runtime's host registry gets
+a set of its own, closed with it (`core/application`, `hostRegistryGates`). `tests/actor-conditions.test.ts`.
+
+Demo mode (backlog 36): `src/demo-ports.ts` gives the runtime
+`FfmpegVideoEditor` (`@product-lab/video-ffmpeg`) over `NodeSystem.commands`, using the system's `ffmpeg` and `ffprobe`
+on `PATH` or in the folder `PRODUCT_LAB_FFMPEG` names (never bundled), and a slide renderer that imports
+`PlaywrightSlideRenderer` from `@product-lab/browser-playwright` on the first slide and closes it after each demo.
+
+Page video (backlog 18b, headless half; 52): with
+`PRODUCT_LAB_RECORDINGS_VIDEO=on` (`product-lab test --video`) the launcher a lab's sessions get
+(`SessionContext.browsers`) is wrapped by `recordingBrowsers` (`src/recording-browsers.ts`): every launch records its
+pages into `<recordings>/videos` (`recordingsDirectory`, `src/recordings-directory.ts`, the same directory the store
+uses), so a lab needs no change. The default session's `frames` also offers `video(actorId)` (`PageFrameCapture.video`).
+`tests/recording-browsers.test.ts`.
+`createLabRuntime` passes `NodeSystem.machine` (`NodeMachineMetrics`) as the runtime's `machine`: recordings sample it
+on their timeline (backlog 25).
+
+Run bundles (backlog 20, 3 October 2026): `createLabRuntime` gives the runtime `FileRunBundleArchives` and a
+`FileRecordingStore` on any directory (`runBundles.recordingsAt`, where an opened bundle's recordings were extracted);
+`LabRuntime.runBundles()` bundles a recording, opens a bundle and reproduces one. `tests/run-bundles.test.ts` runs them on real files
+and git (`fixtures/bundle-lab`, copied per test into `composition/.bundle-lab-*`, outside `src` and `tests`, ignored by the checkout and committed in a git repository of its own, removed after each test): a bundle moved to another directory and opened, the app's source
+changed (opening and reproducing both refuse, naming the app; nothing starts), an identity whose key comes from a lab secret (withheld and named; no entry holds
+the value), a secret's value in a recording (refused), a recording that is not a feature scenario's.
+
+The default environment exposes its original host context through `LabEnvironment.hostSessions()` for passive network and exact signing evidence. `observeBrowserPage(page)` adopts a consumer-owned Playwright page before its first navigation and preserves its native page API with `networkEvidence()`; it does not own or close that page. `observeBrowserPages(browser, opened?)` instruments each page the consumer-owned browser or one of its contexts creates, calling `opened` before returning the page so failed later provisioning can retain its evidence. Observation gaps remain in the returned evidence. Successful default actor-funding receipts are declared as lab setup by exact transaction hash.
+
+Closed contexts retain their evidence through the environment session. An unsupported historical context can therefore keep later runs incomplete conservatively until that environment session closes; resetting app or chain state within the same session and absent later traffic do not erase a coverage gap. Scope comes from the declared environment offer or the known local fork model, never from an endpoint address.
+
+Compiled/default sessions supply host-bypass node inventories from actual environment routes and offered-chain endpoints; custom sessions may forward additional verified node URLs.
+
+App update wiring (item82): `AppUpdateHub` is re-exported from the application layer. The default session attaches its pages as starting and marks them ready after inserting the actor view, awaiting updates withheld during startup. Attachment source is the actual proxy target, so unrelated dev servers do not share restart episodes.
+
+
+Framing reuse (item82): `NodeSystem` constructs `NodeDocumentHeaders` and one standalone application `InspectAppFraming` use case over that raw reader, then supplies its callable inspection through the system ports. `createLabRuntime`, default session wiring and the two framing host factories consume that shared callable. The use case depends on the raw reader, avoiding recursive inspection. Host legacy callbacks remain optional compatibility seams; missing reader/inspection remains unknown.
+
+## Declared launcher environment removal (1 October 2026)
+
+`serveApp` accepts `unsetEnvironment`, an optional validated list of environment variable names removed from inherited process values. Explicit values in the declared plan take precedence. Default callers keep their existing behavior. The unset/override/refusal controls run in `tests/app-server.test.ts`; `AppUpdateHub` remains an application re-export and now preserves explicit reader refusal. Tests: `bunx nx run composition:test`.
+
+Restart readiness probes now check the actual bounded HTTP endpoint after an original dev process exits. Initial startup retains its process-exit refusal and `exited()` keeps the historical diagnostic. The restored-listener control in `tests/app-server.test.ts` uses two real HTTP fixture listeners; it does not claim that the composition root automatically restarts an app.
+
+For a declared `updates: "webpack-dev-server"`, `serveApp` adds the dev servers' own proxy setting
+(`client.webSocketURL: "auto://0.0.0.0:0/ws"`) to the start command: webpack-cli merges a lab file over the app's
+config, Rspack loads a lab file that imports it. Both are written beside the dev server's log, as
+`<processName>.lab-socket.{cjs,mjs}`; the app's config is not changed. A command the lab cannot read starts as declared, and
+`ServedApp.notices` (said by the default session) says the setting is missing. Tests: `tests/app-server.test.ts`.
+
+Backend onboarding chooses the locked official CLI host whenever that release provides `localNetwork`, including in
+this checkout. It needs routing rather than the remaining lab patches. Older releases and an explicit unqualified
+binary retain the checkout's routing-patch declaration. This keeps an all-released-host run from silently using a
+patched provisioner for its identities. `tests/people-dev-onboarding.test.ts` checks a verified official cache hit and
+the older-release fallback with no host process or network request.
+
+Engine setup (`src/engine-setup.ts`) prepares stock v0.11.0 without a patch by default.
+The compatible `--no-patch` flag is optional; the release pin and build checks live in env-engine.

package/composition/src/actor-conditions.d.ts

@@ -0,0 +1,14 @@
+import type { HostCapabilities } from "@parity/product-lab/domain";
+import type { ConditionControl } from "@parity/product-lab/ports/browser";
+import type { EnvironmentConditions } from "@parity/product-lab/ports/lab";
+/** Why an actor on the default host cannot be conditioned when only another declared host can (the planner's refusal). */
+export declare const DEFAULT_HOST_HAS_NONE = "the session's default host declares no per-identity conditions; put the actor on a host that does";
+/**
+ * The environment's conditions, when its host declares them; `sessions(actorId)`: the identity's host sessions now.
+ * `others`: what the other hosts an actor may be put on declare (backlog 28). When only they declare conditions, the
+ * environment still has them for their actors, and the default host's actors are refused by name, before the run.
+ */
+export declare function environmentConditions(capabilities: HostCapabilities | undefined, sessions: (actorId: string) => readonly {
+    readonly conditions?: ConditionControl;
+    localLinks?(): readonly string[];
+}[] | undefined, others?: readonly (HostCapabilities | undefined)[]): EnvironmentConditions | undefined;