@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/application/src/orchestration/integrations/ui-chain-check.d.ts

@@ -0,0 +1,104 @@
+import type { SideReading } from "@parity/product-lab/domain/checks";
+import { type PendingTransaction, type ShownBlock, type UiChainAgreement } from "@parity/product-lab/domain";
+import type { ChainAccess, ChainHistory } from "@parity/product-lab/ports/chain";
+import type { UnsettledTransaction } from "../activity/types.js";
+import type { ChainConnection, ChainHead } from "../chain/chain-connection.js";
+import type { IntegrationChain } from "./define.js";
+/** The block a chain read is at, and why that block. */
+export interface ChainReadAt {
+    /** `finalized` or `best`: that head when the round of readings began; `block`: the block the screen named (pinned mode). */
+    readonly head: "finalized" | "best" | "block";
+    readonly number: number;
+    readonly hash: string;
+}
+/** What a screen reader returns: the claim, read in one capture of one render, and what else the screen says. */
+export interface UiReading<Claim> {
+    readonly claim: Claim;
+    /** The block the screen says it rendered from, when it shows one (recorded; pinned mode compares at it). */
+    readonly block?: ShownBlock | undefined;
+    /** Whose state the screen says it shows (an account), when it says. */
+    readonly subject?: string | undefined;
+}
+/** A pinned check's screen reader always answers for the block: `undefined` when this render shows none. */
+export interface PinnedUiReading<Claim> extends UiReading<Claim> {
+    readonly block: ShownBlock | undefined;
+}
+interface UiChainCheckBase<Claim> {
+    /** What is compared, for messages and the record: "Ada's registration". */
+    readonly what: string;
+    /**
+     * The chain to read: the id of one of the context's `chains` (default: the first), or a connection the integration
+     * owns (its block-by-number lookup is needed in pinned mode and to prove a rollback).
+     */
+    readonly chain?: string | ChainConnection<ChainAccess & ChainHistory>;
+    /**
+     * The chain's side of the claim at `at`, read independently of the app (never through it or its code). Always a
+     * definite block: read state at `at.hash`. A read at a block the node no longer holds may reject with
+     * `BlockUnavailableError`: the round is skipped. Any other failure fails the check as it is.
+     */
+    readChain(at: ChainReadAt): Promise<Claim>;
+    /** Whether the two claims are the same: default structural equality (`sameClaim`); `sameFields("a", "b")` compares chosen fields. */
+    same?(screen: Claim, chain: Claim): boolean;
+    /** The awaited claim: the check ends only when screen and chain agree on a claim that satisfies it. Absent: the first agreement that lasts. */
+    until?(claim: Claim): boolean;
+    /** Whose state the screen must show (the actor's account). A render that names another never agrees. */
+    readonly subject?: string;
+    /** The bound: agreement must begin within it (default 60 000 ms). */
+    readonly withinMs?: number;
+    /** How long agreement must hold (default 2000 ms; 0 in pinned mode). */
+    readonly stableMs?: number;
+    /** Between two rounds of readings (default 250 ms). */
+    readonly pollMs?: number;
+}
+export interface PinnedUiChainCheck<Claim> extends UiChainCheckBase<Claim> {
+    readonly mode: "pinned";
+    /** Read the claim and the block the screen rendered it from, in one capture. */
+    readUi(): Promise<PinnedUiReading<Claim>>;
+    /** How long the screen may show no block before the check is refused (default 10 000 ms, at most the bound). */
+    readonly blockWithinMs?: number;
+}
+export interface EventualUiChainCheck<Claim> extends UiChainCheckBase<Claim> {
+    readonly mode: "eventual";
+    readUi(): Promise<UiReading<Claim>>;
+}
+export interface OptimisticUiChainCheck<Claim> extends UiChainCheckBase<Claim> {
+    readonly mode: "optimistic";
+    readUi(): Promise<UiReading<Claim>>;
+    /**
+     * The actor's transactions that are not final yet and would produce the claim. Default: what the lab knows
+     * (`AssertionContext.unsettled`: step reports and the account watch, on this check's chain). Without either, only
+     * best-block state can back a claim, and the record says so.
+     */
+    pending?(): Promise<readonly PendingTransaction[]> | readonly PendingTransaction[];
+}
+export type UiChainCheck<Claim> = PinnedUiChainCheck<Claim> | EventualUiChainCheck<Claim> | OptimisticUiChainCheck<Claim>;
+/** What the check takes from where it runs: an `AssertionContext` fits as it is. */
+export interface UiChainCheckContext {
+    readonly signal: AbortSignal;
+    readonly chains?: Readonly<Record<string, IntegrationChain>>;
+    /** The head the calling check declared (`reads`): a pinned check passes at a block that is not final only when it is `best`. */
+    readonly reads?: ChainHead;
+    chainView?<Access extends ChainAccess>(connection: ChainConnection<Access>): ChainConnection<Access>;
+    unsettled?(): readonly UnsettledTransaction[];
+    attach?(evidence: Readonly<Record<string, unknown>>): void;
+    /** Backlog 160: each side the check read, as the step's checks (an `AssertionContext` gives it). */
+    reading?(reading: SideReading): void;
+}
+/**
+ * Compare what a screen claims with chain state, in the mode that fits how the app renders; resolves with the record
+ * of how agreement was reached, rejects with `UiChainDisagreementError` (its message names the last screen reading
+ * and the last chain reading; its `agreement` is the record). Either way the record is attached to the step
+ * (`context.attach`, under `uiChainAgreements`), so step evidence, recordings and reports say which mode applied,
+ * what was read and how long it took.
+ *
+ *     const agreement = await checkUiAgainstChain(context, {
+ *       mode: "eventual",
+ *       what: `${context.actor.name}'s seat`,
+ *       subject: context.actor.account,
+ *       readUi: async () => ({ claim: { joined: (await seat.getAttribute("data-joined")) === "true" } }),
+ *       readChain: async (at) => ({ joined: (await chain.access.storage("Seats", "Holders", [account], at.hash)) !== undefined }),
+ *       until: (claim) => claim.joined,
+ *     });
+ */
+export declare function checkUiAgainstChain<Claim>(context: UiChainCheckContext, check: UiChainCheck<Claim>): Promise<UiChainAgreement<Claim>>;
+export {};

package/core/application/src/orchestration/integrations/ui-chain-check.js

@@ -0,0 +1,191 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { AGREEMENTS_KEY, AgreementJudge, AgreementSettings, BlockUnavailableError, UiChainDisagreementError, namesBlock, sameClaim, } from "@parity/product-lab/domain";
+const HASH = /^0x[0-9a-f]{64}$/i;
+const lower = (value) => value.toLowerCase();
+const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split("\n")[0].trim();
+const attachedBy = new WeakMap();
+function attach(context, record, chain) {
+    if (context.reading) {
+        const ok = record.outcome === "agreed";
+        const shown = record.screen?.unreadable ?? (record.screen && "claim" in record.screen ? `showed ${JSON.stringify(record.screen.claim)}` : "nothing read");
+        const block = record.agreedAt ?? record.chain?.block;
+        context.reading({ side: "screen", place: "the screen", expected: `${record.what}, as the chain holds it`, found: shown, ok });
+        context.reading({ side: "chain", place: chain ? chain.charAt(0).toUpperCase() + chain.slice(1) : "the chain", expected: record.proves, found: record.failure?.message ?? record.reached, ok, ...(chain ? { at: { chain, ...(block ? { block: { number: block.number, hash: block.hash } } : {}), head: record.agreedAt?.head ?? (record.chain?.head === "best" ? "best" : "finalized") } } : {}) });
+    }
+    if (!context.attach)
+        return;
+    const records = [...(attachedBy.get(context.attach) ?? []), record];
+    attachedBy.set(context.attach, records);
+    context.attach({ [AGREEMENTS_KEY]: records });
+}
+function chainOf(context, chain) {
+    if (chain !== undefined && typeof chain !== "string")
+        return { connection: context.chainView ? context.chainView(chain) : chain };
+    const chains = context.chains ?? {};
+    const id = chain ?? Object.keys(chains)[0];
+    const connection = id !== undefined ? chains[id] : undefined;
+    if (!connection)
+        throw new Error(chain !== undefined
+            ? `No chain "${chain}" (available: ${Object.keys(chains).join(", ") || "none"})`
+            : "A UI and chain agreement check needs a chain to read: name one of the context's chains (load the lab through the composition root) or pass a connection as `chain`");
+    return { connection, id: id };
+}
+async function readScreen(check, signal) {
+    let reading;
+    try {
+        reading = await check.readUi();
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        return { unreadable: firstLine(error) };
+    }
+    if (!reading || typeof reading !== "object" || !("claim" in reading))
+        throw new Error(`${check.mode} check of ${check.what}: readUi must return { claim, block?, subject? }`);
+    const subject = typeof reading.subject === "string" && reading.subject ? { subject: reading.subject } : {};
+    const shown = reading.block ?? undefined;
+    const number = shown?.number ?? undefined;
+    const hash = shown?.hash ?? undefined;
+    const hasNumber = number !== undefined && !Number.isNaN(number);
+    const hasHash = hash !== undefined && hash !== "";
+    if (!hasNumber && !hasHash)
+        return { claim: reading.claim, ...subject };
+    const block = { ...(hasNumber ? { number } : {}), ...(hasHash ? { hash } : {}) };
+    const screen = { claim: reading.claim, block, ...subject };
+    if (hasNumber && !(Number.isSafeInteger(number) && number >= 0))
+        return { invalidBlock: `the screen names block ${String(number)}, which is not a block number`, reading: screen };
+    if (hasHash && !HASH.test(hash))
+        return { invalidBlock: `the screen names block ${hash}, which is not a block hash`, reading: screen };
+    return screen;
+}
+async function readAt(check, at) {
+    try {
+        return { claim: await check.readChain(at) };
+    }
+    catch (error) {
+        if (error instanceof BlockUnavailableError)
+            return { unavailable: `the node does not hold the state of ${at.head === "block" ? "" : `${at.head} `}block #${at.number} (${at.hash}): ${firstLine(error)}` };
+        throw new Error(`${check.mode} check of ${check.what}: reading the chain at ${at.head === "block" ? "" : `${at.head} `}block #${at.number} (${at.hash}) failed: ${firstLine(error)}`, { cause: error });
+    }
+}
+async function readPinned(connection, check, shown) {
+    const access = connection.access;
+    if (typeof access.blockAt !== "function" || typeof access.block !== "function")
+        throw new Error(`pinned check of ${check.what}: the chain connection cannot look blocks up by number and hash (ChainHistory), which a pinned check needs`);
+    const finalizedHead = await access.finalizedHead();
+    let at;
+    if (shown.hash !== undefined) {
+        at = await access.block(shown.hash);
+        if (!at)
+            return { status: "unknown", detail: `the chain does not know block ${shown.hash}, which the screen names` };
+        if (shown.number !== undefined && at.number !== shown.number)
+            return { status: "unknown", detail: `the screen names block #${shown.number} with hash ${shown.hash}, which the chain has at #${at.number}` };
+    }
+    else {
+        at = await access.blockAt(shown.number);
+        if (!at)
+            return { status: "unknown", detail: `the chain has no block #${shown.number} yet, which the screen names` };
+    }
+    const onChain = shown.hash !== undefined ? await access.blockAt(at.number) : at;
+    const canonical = onChain !== undefined && lower(onChain.hash) === lower(at.hash);
+    const read = await readAt(check, { head: "block", number: at.number, hash: at.hash });
+    if ("unavailable" in read)
+        return { status: "unavailable", detail: read.unavailable };
+    return { status: "read", block: { number: at.number, hash: at.hash }, canonical, finalized: canonical && at.number <= finalizedHead.number, claim: read.claim };
+}
+function pendingReader(context, check, chainId) {
+    if (check.mode !== "optimistic")
+        return undefined;
+    const own = check.pending;
+    if (own)
+        return { source: "the integration's reader", read: async () => own() };
+    const unsettled = context.unsettled;
+    if (!unsettled)
+        return undefined;
+    return {
+        source: `the lab's record of the actor's transactions${chainId !== undefined ? ` on ${chainId}` : ""} (step reports and the account watch)`,
+        read: async () => unsettled()
+            .filter((item) => chainId === undefined || item.chain === chainId)
+            .map((item) => ({ ...(item.hash ? { hash: item.hash } : {}), status: item.status, source: item.source, ...(item.label ? { label: item.label } : {}) })),
+    };
+}
+async function round(context, check, connection, judge, pending, atMs) {
+    const read = await readScreen(check, context.signal);
+    if ("invalidBlock" in read)
+        return { atMs, screen: read.reading, pinned: { status: "unknown", detail: read.invalidBlock } };
+    const screen = read;
+    if ("unreadable" in screen)
+        return { atMs, screen };
+    const access = connection.access;
+    if (check.mode === "pinned")
+        return namesBlock(screen.block) ? { atMs, screen, pinned: await readPinned(connection, check, screen.block) } : { atMs, screen };
+    const finalizedHead = await access.finalizedHead();
+    const finalizedRead = await readAt(check, { head: "finalized", ...finalizedHead });
+    if ("unavailable" in finalizedRead)
+        return { atMs, screen, chainUnavailable: finalizedRead.unavailable };
+    const finalized = { block: { number: finalizedHead.number, hash: finalizedHead.hash }, claim: finalizedRead.claim };
+    if (check.mode === "eventual")
+        return { atMs, screen, finalized };
+    const bestHead = await access.bestHead();
+    let best = finalized;
+    if (bestHead.number > finalizedHead.number || (bestHead.number === finalizedHead.number && lower(bestHead.hash) !== lower(finalizedHead.hash))) {
+        const bestRead = await readAt(check, { head: "best", ...bestHead });
+        if ("unavailable" in bestRead)
+            return { atMs, screen, chainUnavailable: bestRead.unavailable };
+        best = { block: { number: bestHead.number, hash: bestHead.hash }, claim: bestRead.claim };
+    }
+    const backing = judge.backingBlock;
+    const retracted = backing && finalizedHead.number >= backing.number && typeof access.blockAt === "function" ? await retractedFrom(access, backing) : undefined;
+    return { atMs, screen, finalized, best, pending: pending ? await pending.read() : [], ...(retracted !== undefined ? { retracted } : {}) };
+}
+async function retractedFrom(access, backing) {
+    const now = await access.blockAt(backing.number);
+    return now ? lower(now.hash) !== lower(backing.hash) : undefined;
+}
+export async function checkUiAgainstChain(context, check) {
+    const declared = {
+        mode: check.mode,
+        what: check.what,
+        ...(check.subject !== undefined ? { subject: check.subject } : {}),
+        ...(check.withinMs !== undefined ? { withinMs: check.withinMs } : {}),
+        ...(check.stableMs !== undefined ? { stableMs: check.stableMs } : {}),
+        ...(check.pollMs !== undefined ? { pollMs: check.pollMs } : {}),
+        ...(check.mode === "pinned" && check.blockWithinMs !== undefined ? { blockWithinMs: check.blockWithinMs } : {}),
+        ...(check.mode === "pinned" && context.reads ? { finality: context.reads } : {}),
+    };
+    let settings = AgreementSettings.of(declared);
+    if (typeof check.readUi !== "function" || typeof check.readChain !== "function")
+        throw new Error(`${settings.mode} check of ${settings.what}: give readUi (the screen's claim) and readChain (the chain's, read independently)`);
+    const { connection, id } = chainOf(context, check.chain);
+    if (connection.publicWaits && settings.withinMs < connection.publicWaits.agreementMs)
+        settings = AgreementSettings.of({ ...declared, withinMs: connection.publicWaits.agreementMs });
+    const pending = pendingReader(context, check, id);
+    const judge = new AgreementJudge(settings, {
+        same: check.same ?? sameClaim,
+        ...(check.until ? { until: check.until } : {}),
+        ...(pending ? { pendingSource: pending.source } : {}),
+    });
+    const { clock } = connection;
+    try {
+        const record = await connection.tracked(`${settings.mode} check: ${settings.what}`, settings.withinMs + settings.stableMs, settings.finality, async () => {
+            const started = clock.now();
+            for (;;) {
+                context.signal.throwIfAborted();
+                connection.signal.throwIfAborted();
+                const verdict = judge.observe(await round(context, check, connection, judge, pending, Math.round(clock.now() - started)));
+                if (verdict.status === "failed")
+                    throw new UiChainDisagreementError(verdict.record);
+                if (verdict.status === "agreed")
+                    return { value: verdict.record, ...(verdict.record.agreedAt ? { block: { number: verdict.record.agreedAt.number, hash: verdict.record.agreedAt.hash } } : {}) };
+                await clock.sleep(settings.pollMs, context.signal);
+            }
+        });
+        attach(context, record, id);
+        return record;
+    }
+    catch (error) {
+        if (error instanceof UiChainDisagreementError)
+            attach(context, error.agreement, id);
+        throw error;
+    }
+}

package/core/application/src/orchestration/lab/block-availability.d.ts

@@ -0,0 +1,20 @@
+import type { AppAvailability } from "@parity/product-lab/ports/driving";
+import { RequirementCheck } from "@parity/product-lab/domain";
+import type { EnvironmentOffer } from "../capabilities.js";
+import type { IntegrationRegistry } from "../integrations/integration-registry.js";
+import type { IntegrationFailure } from "./integration-availability.js";
+import type { IntegrationAvailability } from "./integration-availability.js";
+export interface BlockAvailabilityContext {
+    readonly integrations: IntegrationRegistry;
+    readonly availability: readonly AppAvailability[];
+    readonly offer: EnvironmentOffer;
+    readonly environmentId: string;
+    /** Integrations whose services failed to start (a started environment only). */
+    readonly failures?: ReadonlyMap<string, IntegrationFailure>;
+    /** Per-integration readiness, including secrets and dependencies, for standalone integrations. */
+    readonly integrationAvailability?: readonly IntegrationAvailability[];
+    /** The environment's requirement check, which says why a capability is missing (its topology's reasons); default: none said. */
+    readonly requirements?: RequirementCheck;
+}
+/** The reason `owner` (`<integration>.<block>`) cannot run, or undefined. */
+export declare function unavailableBlock(owner: string, context: BlockAvailabilityContext): string | undefined;

package/core/application/src/orchestration/lab/block-availability.js

@@ -0,0 +1,30 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { RequirementCheck } from "@parity/product-lab/domain";
+export function unavailableBlock(owner, context) {
+    const { integrations, availability, offer, environmentId } = context;
+    const requirements = context.requirements ?? new RequirementCheck();
+    const integration = integrations.actions.get(owner)?.integration ?? integrations.assertions.get(owner)?.integration;
+    if (!integration)
+        return `${owner} is not registered`;
+    const failure = context.failures?.get(integration);
+    if (failure)
+        return `Integration ${integration} failed to start: ${failure.message}`;
+    const apps = availability.filter((item) => item.integration && integrations.closure([item.integration]).includes(integration));
+    const standalone = integrations.integrations.get(integration)?.standalone === true;
+    if (!apps.some((item) => item.available) && !standalone)
+        return apps.length
+            ? `Integration ${integration} is unavailable in ${environmentId}: ${apps.map((item) => item.reason).filter(Boolean).join("; ")}`
+            : `Integration ${integration} is used by no app of this lab`;
+    if (standalone) {
+        const state = context.integrationAvailability?.find((item) => item.integration === integration);
+        if (state && !state.available)
+            return `Integration ${integration} is unavailable in ${environmentId}: ${state.reason}`;
+        const own = requirements.check(integrations.requirements(integration), offer);
+        if (!own.available)
+            return `Integration ${integration} is unavailable in ${environmentId}: ${own.reason}`;
+    }
+    const requires = integrations.actions.get(owner)?.action.requires ?? integrations.assertions.get(owner)?.assertion.requires;
+    const check = requirements.check(requires ?? {}, offer);
+    return check.available ? undefined : `${owner} is unavailable in ${environmentId}: ${check.reason}`;
+}

package/core/application/src/orchestration/lab/checked-environment-time.d.ts

@@ -0,0 +1,29 @@
+import type { ChainAccess } from "@parity/product-lab/ports/chain";
+import type { ChainMoment, EnvironmentTime } from "@parity/product-lab/ports/environment";
+type Reader = Pick<ChainAccess, "finalizedHead" | "storage">;
+/** What the check reads with: the lab's own connection to one chain (an `IntegrationChain`). */
+export interface TimeReader {
+    readonly access: Reader;
+    /** `ChainConnection.waitFor`: polls through the lab's clock until `read` returns a value. */
+    waitFor<T>(label: string, read: (at: {
+        at: string;
+    }) => Promise<T | undefined>, timeoutMs?: number): Promise<T>;
+}
+/**
+ * The chain now, read through the lab's own connection: its finalized head, and its clock there when it keeps one. A
+ * head the client has not pinned yet (BlockUnavailableError, right after it was finalized) is read again, through the
+ * connection's clock; a runtime without `Timestamp.Now` keeps no clock (a clock advance is then refused by
+ * TimeAdvance.shortfall).
+ */
+export declare function readChainMoment(chain: TimeReader): Promise<ChainMoment>;
+/**
+ * `time` with each advance checked through `chains` (the lab's connections by chain id). A chain the lab has no
+ * connection to is advanced on the environment's report alone, and the result says so (`unchecked`).
+ */
+export declare function checkedEnvironmentTime(time: EnvironmentTime, chains: () => Readonly<Record<string, TimeReader>> | undefined): EnvironmentTime;
+/** Why the environment cannot advance its chains, or undefined when it offers a time control. */
+export declare function timeUnsupported(running: {
+    time?: EnvironmentTime;
+    timeUnsupported?: string;
+}, environmentId: string): string | undefined;
+export {};

package/core/application/src/orchestration/lab/checked-environment-time.js

@@ -0,0 +1,52 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { BlockUnavailableError, TimeAdvance } from "@parity/product-lab/domain";
+const UNPINNED_TIMEOUT_MS = 15_000;
+export function readChainMoment(chain) {
+    return chain.waitFor("Read the finalized head and the chain's clock there", async () => {
+        const head = await chain.access.finalizedHead();
+        const moment = { number: head.number, hash: head.hash, finalized: head.number };
+        try {
+            const now = await chain.access.storage("Timestamp", "Now", [], head.hash);
+            return typeof now === "bigint" || typeof now === "number" ? { ...moment, timestamp: Number(now) } : moment;
+        }
+        catch (error) {
+            if (error instanceof BlockUnavailableError)
+                return undefined;
+            return moment;
+        }
+    }, UNPINNED_TIMEOUT_MS);
+}
+export function checkedEnvironmentTime(time, chains) {
+    const checked = async (chain, advance, run) => {
+        if (!time.chains.includes(chain))
+            throw new Error(`This environment advances ${time.chains.join(", ") || "no chain"}, not ${chain}`);
+        const reader = chains()?.[chain];
+        const before = reader ? await readChainMoment(reader) : undefined;
+        const reported = await run();
+        const claimed = advance.shortfall(reported.from, reported.to);
+        if (claimed)
+            throw new Error(`${chain}: the environment reported an advance that falls short of ${advance.describe()}: ${claimed}`);
+        if (!reader || !before)
+            return { ...reported, unchecked: `the lab has no connection to ${chain}; the environment's report is not checked against the chain` };
+        const after = await readChainMoment(reader);
+        const observed = advance.shortfall(before, after);
+        if (observed)
+            throw new Error(`${chain}: the environment reported ${advance.describe()}, but the lab's own reading of the chain shows ${observed}`);
+        return { ...reported, checked: { before, after } };
+    };
+    return {
+        chains: time.chains,
+        production: time.production,
+        advanceBlocks: (request) => checked(request.chain, TimeAdvance.blocks(request.count), () => time.advanceBlocks(request)),
+        ...(time.advanceClock
+            ? { advanceClock: (request) => checked(request.chain, TimeAdvance.clock(request.ms), () => time.advanceClock(request)) }
+            : {}),
+        ...(time.clockUnsupported !== undefined ? { clockUnsupported: time.clockUnsupported } : {}),
+    };
+}
+export function timeUnsupported(running, environmentId) {
+    if (running.time)
+        return undefined;
+    return running.timeUnsupported ?? `Environment ${environmentId} cannot advance its chains (its adapter offers no time control)`;
+}

package/core/application/src/orchestration/lab/compile.d.ts

@@ -0,0 +1,66 @@
+import type { FeatureSource } from "@parity/product-lab/ports/features";
+import type { RunManifestStore } from "@parity/product-lab/ports/storage";
+import type { EnvironmentOffer } from "../capabilities.js";
+import type { IntegrationRegistry } from "../integrations/integration-registry.js";
+import type { IntegrationChain } from "../integrations/define.js";
+import type { ChainReaders } from "@parity/product-lab/ports/chain";
+import type { EnvironmentDefinition, LabConfig, LabEnvironment } from "../types.js";
+import type { LabDefinition, RunningEnvironment, SessionContext } from "./define.js";
+import type { RootCallSupport } from "./root-call-access.js";
+export interface CompileOptions {
+    /** Directory of lab.config.ts (feature globs and relative paths resolve against it). */
+    root: string;
+    /** Environment variables secrets read from, read at the edge (an entry point passes `process.env`; tests a record). */
+    env: NodeJS.ProcessEnv;
+    /**
+     * Where the lab records a topology environment's run manifest when its
+     * provider wrote none (`FileRunManifestStore` from
+     * @product-lab/storage-filesystem, conventionally under `<root>/.product-lab/runs`).
+     */
+    runManifests: RunManifestStore;
+    /** Lists the lab's feature globs for the live registry (refactor step 8: core no longer globs); none listed without it. */
+    features?: FeatureSource;
+    /**
+     * Opens one connection per chain the running environment declares (the
+     * composition root, over `@parity/product-lab/chain-papi`), given to `sessions()`
+     * (`SessionContext.chains`) and to every action and assertion
+     * (`ActionContext.chains`/`AssertionContext.chains`), closed when the
+     * environment stops. Absent: `chains` is empty everywhere (tests, a lab
+     * compiled without a composition root). `readers` (backlog 91) are the lab's own reads of what apps stored, given to
+     * every assertion (`AssertionContext.readers`).
+     */
+    chains?: (running: RunningEnvironment) => {
+        chains: Readonly<Record<string, IntegrationChain>>;
+        readers?: ChainReaders;
+        close(): void;
+    };
+    /**
+     * Used when the lab declares no `sessions()` of its own (the composition
+     * root's default single-actor session, built from the declared environment,
+     * host and app). A lab with a custom `sessions()` is unaffected.
+     */
+    defaultSessions?: (context: SessionContext) => Promise<LabEnvironment>;
+    /** What root calls need from the composition root (a submitter per chain, the evidence journal); none without it. */
+    rootCalls?: RootCallSupport;
+}
+export interface CompiledLab extends LabConfig {
+    /** Environment started when none is selected. */
+    defaultEnvironment: string;
+    environments: EnvironmentDefinition[];
+    definition: LabDefinition;
+    integrations: IntegrationRegistry;
+}
+/**
+ * Turn a declarative lab into the runtime configuration the controller, shell
+ * and CLI already use. Each environment start:
+ * 1. starts the environment provider and reads its offer;
+ * 2. reports apps whose requirements (chains, services, capabilities, secrets) it cannot meet;
+ * 3. initialises environment-lifetime services of the available integrations in dependency order
+ *    (an integration whose service fails, e.g. an operator failing `verifyAuthority`,
+ *    makes its apps unavailable with that error, without affecting unrelated apps);
+ * 4. calls `sessions()` for actor sessions and scenarios, adds each available integration
+ *    action as a one-step scenario, and wraps lifecycle hooks so actor services are released
+ *    with their actor, scenario services after each run, and every service on reset/close.
+ */
+export declare function compileLab(definition: LabDefinition, options: CompileOptions): CompiledLab;
+export declare function describeOffer(offer: EnvironmentOffer): string;

package/core/application/src/orchestration/lab/compile.js

@@ -0,0 +1,54 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { LabConfigurationError } from "@parity/product-lab/domain";
+import { resolveEnvironment } from "./environments.js";
+import { defaultEnvironmentId, labIntegrations, validateLab } from "./validate.js";
+import { startLabEnvironment } from "./start-lab-environment.js";
+import { warnOfEphemeralPorts } from "./session-ports.js";
+export function compileLab(definition, options) {
+    const integrations = labIntegrations(definition);
+    const errors = validateLab(definition, integrations);
+    if (errors.length)
+        throw new LabConfigurationError(errors);
+    const defaultEnvironment = defaultEnvironmentId(definition);
+    const environments = Object.keys(definition.environments).map((id) => {
+        const resolved = resolveEnvironment(definition, id);
+        return {
+            id,
+            label: resolved.label,
+            description: resolved.description ?? describeOffer(resolved.offer),
+            ...(resolved.options ? { options: resolved.options } : {}),
+            start: async (signal, start) => {
+                await warnOfEphemeralPorts(definition, start?.progress ?? ((line) => definition.system?.logger?.warn(line)), environmentPorts(definition, id, start?.option));
+                return startLabEnvironment(definition, integrations, id, signal, options, start);
+            },
+        };
+    });
+    return {
+        name: definition.name,
+        ...(definition.port !== undefined ? { port: definition.port } : {}),
+        ...(definition.navigation ? { navigation: definition.navigation } : {}),
+        defaultEnvironment,
+        environments,
+        start: environments.find((item) => item.id === defaultEnvironment).start,
+        definition,
+        integrations,
+    };
+}
+export function describeOffer(offer) {
+    const parts = [`chains: ${offer.chains.join(", ") || "none"}`];
+    if (offer.services?.length)
+        parts.push(`services: ${offer.services.join(", ")}`);
+    if (offer.capabilities?.length)
+        parts.push(`capabilities: ${offer.capabilities.join(", ")}`);
+    parts.push(offer.local ? "local" : "remote");
+    return parts.join(" · ");
+}
+function environmentPorts(definition, id, option) {
+    try {
+        return resolveEnvironment(definition, id, undefined, option).provider?.ports;
+    }
+    catch {
+        return undefined;
+    }
+}