@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/ports/src/driven/lab/lab-configuration.d.ts

@@ -0,0 +1,86 @@
+import type { EnvironmentOption } from "@parity/product-lab/domain";
+import type { AppNavigation } from "@parity/product-lab/domain/navigation";
+import type { VersionResolution } from "@parity/product-lab/domain/versions";
+import type { EnvironmentStartup, EnvironmentUpdate } from "../environment/running-environment.js";
+import type { StartPhaseSink } from "../environment/start-phases.js";
+import type { LabEnvironment } from "./lab-environment.js";
+import type { RememberedRpc } from "../storage/rpc-choices.js";
+import type { EnvironmentRpcRequest } from "../../driving/environment-rpc.js";
+export type { AppNavigation, AppRoute, RouteField } from "@parity/product-lab/domain/navigation";
+/**
+ * A component a run reports running (Phase 7, the compatibility report): a
+ * host's resolved artifact (`host:<kind>`), a chain's runtime
+ * (`runtime:<chain>`). A suite row records what its run observed beside its
+ * version resolution, so two runs can say whether the host or a runtime changed.
+ */
+export interface RunObservation {
+    /** `<kind>:<name>`, as in lab.lock.json (`host:truapi-cli`, `runtime:people`). */
+    readonly id: string;
+    readonly version: string;
+    /** Named digests (`sha256` of a host artifact, `code` of a runtime). */
+    readonly digests: Readonly<Record<string, string>>;
+    /** Where it came from (an artifact path, a transaction version); never a secret. */
+    readonly detail?: string;
+}
+/**
+ * One environment start a run measured (Phase 7, suite reports): how long
+ * StartEnvironment took from the request to a running environment, on the
+ * run's own clock, and how the start began as the environment declared it
+ * (absent: not declared). A suite row reads what its run recorded; a row whose
+ * run recorded nothing has no environment start time (not measured).
+ */
+export interface EnvironmentStartMeasurement {
+    /** The environment's id (`default` for a legacy lab's own start). */
+    readonly environment: string;
+    readonly durationMs: number;
+    readonly startup?: EnvironmentStartup;
+    /** What the started environment reported (chain or service id → URL), for judging parallel workers' isolation (backlog 34). */
+    readonly endpoints?: Readonly<Record<string, string>>;
+}
+/** What a start may carry besides its signal: the run's version resolution (Phase 6), resolved once at run start. */
+export interface EnvironmentStartOptions {
+    readonly versions?: VersionResolution;
+    /** One line per start stage (the chain being started, the host, the browser), for whoever waits: `product-lab dev` prints them. */
+    readonly progress?: (message: string) => void;
+    /** The start's phases as the environment and its sessions observe them (`product-lab dev` renders them as a checklist). */
+    readonly phase?: StartPhaseSink;
+    /** Phase 7: told each host the sessions resolve and each chain's runtime once the environment runs. Must not throw. */
+    readonly observe?: (component: RunObservation) => void;
+    /** An update asked of this start (`EnvironmentStartContext.update`); refused unless the environment lists it in `updates`. */
+    readonly update?: EnvironmentUpdate;
+    /**
+     * A fixture restore follows this start at once (fixtures, 30 September 2026): the lab's sessions open without the
+     * work the restore replaces (`SessionContext.restoring`), and open again, in full, after the restore.
+     */
+    readonly restoring?: {
+        readonly fixture: string;
+    };
+    /** The lab's RPC per chain for this start beyond lab.config's: the lab window's remembered choice and the request's. */
+    readonly rpc?: {
+        readonly remembered?: RememberedRpc;
+        readonly request?: EnvironmentRpcRequest;
+    };
+    /** Keep the chains and people as the last start left them (backlog 183): `EnvironmentStartContext.keep`, `SessionContext.keep`. */
+    readonly keep?: boolean;
+    /** With `keep`: discard the kept chains for new ones (`EnvironmentStartContext.replaceKept`). */
+    readonly replaceKept?: boolean;
+    /** Backlog 184: the option this start runs as (one of the environment's `options`); absent, its default. */
+    readonly option?: string;
+}
+export interface EnvironmentDefinition {
+    id: string;
+    label: string;
+    description: string;
+    /** Backlog 184: the ways it can run, when it has options; the first is the default. */
+    options?: readonly EnvironmentOption[];
+    /** `options.versions`: passed to the environment adapter (`EnvironmentStartContext.versions`) and to the hosts sessions create. */
+    start(signal: AbortSignal, options?: EnvironmentStartOptions): Promise<LabEnvironment>;
+}
+/** What compileLab returns: the lab's name, window port and navigation, its environments and its default start. */
+export interface LabConfig {
+    name: string;
+    port?: number;
+    navigation?: AppNavigation;
+    environments?: readonly EnvironmentDefinition[];
+    start(signal: AbortSignal): Promise<LabEnvironment>;
+}

package/core/ports/src/driven/lab/lab-configuration.js

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

package/core/ports/src/driven/lab/lab-definition-source.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads a lab's exported definition without validating or compiling it.
+ * A module adapter owns the import and reload policy; the application owns
+ * the distinction between declarative and legacy definitions and compiles it.
+ * The returned value is untrusted and must be validated before any use.
+ */
+export interface LabDefinitionSource {
+    /** The configuration file, or a descriptive source for a definition supplied in code. */
+    readonly path: string;
+    /** Base directory for paths declared by the definition. */
+    readonly root: string;
+    /** Returns an untrusted value; re-evaluates when the adapter's reload policy requests it. */
+    load(): Promise<unknown>;
+    /** True after the adapter observes an edit since the last load. */
+    changed?(): boolean;
+}

package/core/ports/src/driven/lab/lab-definition-source.js

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

package/core/ports/src/driven/lab/lab-environment.d.ts

@@ -0,0 +1,505 @@
+import type { SideReading } from "@parity/product-lab/domain/checks";
+import type { ActorSession, HostBypassEvidence, HostBypassPolicyData, NavigationEvidence, TagCondition, TransactionDeclaration } from "@parity/product-lab/domain";
+import type { HostOptionSetting, HostOptionValues } from "@parity/product-lab/domain/actors";
+import type { ActivitySink } from "../../driving/activity.js";
+import type { EnvironmentSnapshots, EnvironmentStartup } from "../environment/running-environment.js";
+import type { ChainDay, EnvironmentTime } from "../environment/environment-time.js";
+import type { ChainHistory } from "../chain/chain-history.js";
+import type { ChainReaders } from "../chain/chain-readers.js";
+import type { ConditionControl } from "../browser/conditions.js";
+import type { HostSession, SessionPlacements, SigningDecision } from "../host/host-session.js";
+import type { HostProbe, HostProbeRequest } from "../host/host-provider.js";
+import type { DestinationDirectory } from "../deploy/destination-directory.js";
+import type { LabRegistry } from "../../driving/lab-registry.js";
+import type { ActiveApplication, NavigationSnapshot } from "../../driving/navigation-view.js";
+import type { ScenarioDefinition } from "./scenario.js";
+import type { LabSentences } from "./lab-sentences.js";
+import type { FrameCapture } from "../recording/frame-capture.js";
+import type { ConsoleWatch } from "../recording/console-watch.js";
+import type { AppProxyEvent, DevServerUpdate } from "../system/app-proxy.js";
+export interface WorkspaceStatus {
+    id: string;
+    directory: string;
+    status: "starting" | "running" | "stopped" | "failed";
+    network: "owned" | "attached";
+    processes: {
+        id: string;
+        status: "running" | "stopped" | "failed";
+        processes: number;
+        error?: string;
+    }[];
+}
+/** Backlog 35c: an account's free balance on one chain at one finalized block (planck, as a decimal string). */
+export interface ActorFunds {
+    readonly chain: string;
+    readonly account: string;
+    readonly block: number;
+    readonly hash: string;
+    readonly free: string;
+}
+/** Identities an environment keeps ready for `createActor` (LabEnvironment.identityReserve). Counts only, no identity. */
+export interface IdentityReserveStatus {
+    /** How many it keeps ready; 0 when the reserve is turned off. */
+    readonly capacity: number;
+    /** Ready now: the next `createActor` takes one without waiting. */
+    readonly ready: number;
+    /** Being prepared now. */
+    readonly preparing: number;
+    /** Why preparing stopped, when it did (the reserve then creates identities directly). */
+    readonly error?: string;
+}
+/** One declared host as a running session sees it (`LabEnvironment.hosts`, backlog 28). */
+export interface EnvironmentHost {
+    /** The lab's `hosts` id. */
+    readonly id: string;
+    /** Backlog 247: the capabilities it can probe (`HostProvider.probes`, `LabEnvironment.probeHost`); absent: none. */
+    readonly probes?: readonly HostProbeRequest["capability"][];
+    readonly kind: string;
+    /** The short name views show for it, as on a tile ("truAPI CLI", "truAPI WASM"; `HostProvider.label`); absent: views show `kind`. */
+    readonly label?: string;
+    /** One line on what it is for: the lab's `description` for it, else its adapter's label ("truAPI CLI host (…)"). */
+    readonly description?: string;
+    /** The hue views mark it with (`#rrggbb`): the lab's `color` for it, else its adapter's; absent: the neutral slate. */
+    readonly color?: string;
+    /** The host actors get when a scenario names none. */
+    readonly default: boolean;
+    readonly available: boolean;
+    /** Why an actor cannot be created on it here; the planner's refusal says exactly this. */
+    readonly reason?: string;
+    /**
+     * Per-identity conditions (backlog 31) on an actor put on this host: what its sessions cannot apply, with why. Absent:
+     * the host declares none, and a condition on an actor put on it is refused before the run.
+     */
+    readonly conditions?: {
+        readonly unavailable?: {
+            readonly network?: string;
+            readonly cpu?: string;
+        };
+    };
+    /**
+     * Backlog 185: the options its adapter declares (`HostAdapterFactory.hostOptions`), each with the value the lab sets
+     * for this host. Absent: its adapter declares none.
+     */
+    readonly options?: readonly HostOptionSetting[];
+    /** Other names for this host with some options set (`hosts.<id>.aliases`), which `createActor({ host })` accepts. */
+    readonly aliases?: Readonly<Record<string, HostOptionValues>>;
+    /** Names its adapter's hosts went by before (`HostAdapterFactory.formerNames`), which a host reference still accepts; never shown. */
+    readonly formerNames?: readonly string[];
+}
+/**
+ * Who asked to remove an identity, and why (6 October 2026: a kept person was gone after a restart and nothing said who
+ * had removed them). An environment that keeps its people records it beside them.
+ */
+/** Where a removal was asked: a person in the lab window or the terminal app, an agent over MCP, the CLI, a scenario's own cleanup, or another runtime caller. */
+export type ActorRemovalSource = "window" | "terminal" | "mcp" | "cli" | "scenario" | "api";
+export interface ActorRemoval {
+    readonly from: ActorRemovalSource;
+    /** Why, in plain words ("deleted by a person", "made for this run, removed at its end"). */
+    readonly reason: string;
+    /** The scenario whose cleanup removed it. */
+    readonly scenario?: string;
+    /** The run that made it, when one did. */
+    readonly run?: string;
+}
+/**
+ * A host the lab could run people in but does not declare (docs/feature-map.md, "People and hosts"): views list it
+ * greyed, never hidden, saying what it is, the problem it solves and the config that turns it on.
+ */
+export interface UnconfiguredHost {
+    /** The adapter's kind (`hosts.<id>.kind` in the lab config). */
+    readonly kind: string;
+    /** Its plain name ("truAPI WASM"). */
+    readonly label: string;
+    /** What it is and the problem it solves, in one line. */
+    readonly why: string;
+    /** The config that turns it on, as a person would add it to the lab config. */
+    readonly turnOn: string;
+}
+/**
+ * A pre-onboarded identity an environment can open (backlog A3): declared in lab.config (`actors`), its wallet in a
+ * secret. Names only: no secret value, no entropy.
+ */
+export interface PreOnboardedActorView {
+    /** The actor name a scenario uses (`Ada`). */
+    readonly name: string;
+    /** The secret's name (never its value; not called `secret`, which redaction blanks). */
+    readonly secretName: string;
+    readonly liteUsername?: string;
+    /** The account the lab expects, when declared. */
+    readonly account?: string;
+    /** Why it cannot be opened here (its secret is not set, or not a wallet phrase); absent when it can. */
+    readonly problem?: string;
+    /** The running actor session id once opened. */
+    readonly openedAs?: string;
+}
+/** What scenarios and assertions read: recorded bridge evidence only. */
+export interface NavigationRecords {
+    evidence(): readonly NavigationEvidence[];
+    activeApplication(actorId: string): ActiveApplication | undefined;
+    waitFor(predicate: (evidence: readonly NavigationEvidence[]) => boolean, options?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<readonly NavigationEvidence[]>;
+}
+/**
+ * What a session keeps on disk for its identities (fixtures, 29 September 2026): the directories a fixture copies
+ * while the session is closed (host state, saved identity records). A session that restores its identities from them
+ * when it opens again gets them back after a fixture is restored.
+ */
+export interface SessionFixtureState {
+    /** Absolute, distinct directories; none may contain another. */
+    readonly directories: readonly string[];
+    /**
+     * Until when state saved now stays usable (30 September 2026): state that follows the chain's clock (an event
+     * scheduled for a date) expires with it. Read on the running session before a save; `at` is epoch milliseconds, and
+     * a restore after it is refused with `reason`. Undefined: it does not expire.
+     */
+    expires?(): Promise<FixtureExpiry | undefined>;
+}
+/** When saved state stops being usable, and why (SessionFixtureState.expires). */
+export interface FixtureExpiry {
+    readonly at: number;
+    readonly reason: string;
+}
+/**
+ * What a fixture needs from the running environment (the lab's wrapper provides it when the environment offers
+ * snapshots): the state's lineage and runtimes, the session's state, and a way to run work with the session closed.
+ */
+export interface EnvironmentFixtures {
+    /** `EnvironmentSnapshots.lineage` of the environment. */
+    readonly lineage: string;
+    /** `EnvironmentSnapshots.runtimes` of the environment. */
+    runtimes(): Promise<Readonly<Record<string, string>>>;
+    /** The session's state directories; undefined when the session keeps none (a fixture then holds the environment only). */
+    sessionState(): SessionFixtureState | undefined;
+    /**
+     * Close the session and its services, run `work` with the environment's snapshots, then open a new session and
+     * services (also after `work` failed). Old actor sessions are invalid afterwards, as after a reset.
+     */
+    suspended<T>(work: (snapshots: EnvironmentSnapshots) => Promise<T>): Promise<T>;
+    /**
+     * Undefined when a restored state can be upgraded in place (`EnvironmentSnapshots.upgrade`), else why not
+     * (`fixture refresh`, 30 September 2026). Absent: it cannot.
+     */
+    upgradable?(): string | undefined;
+}
+/** One proxied app of a session: its id, and the protocol of its dev server's update socket once it is known. */
+export interface FollowedApp {
+    readonly app: string;
+    readonly label?: string;
+    /** Undefined: not known (yet), so the lab cannot hold this dev server's updates. */
+    readonly protocol?: string;
+    /** The lab declared that this dev server never updates a page by itself (`devServer.updates: "none"`): there is nothing to follow. */
+    readonly quiet?: boolean;
+}
+/** What a dev server told the pages of one identity's app (`AppProxyEvent`), with whose pages they are. */
+export type AppUpdateEvent = (AppProxyEvent | {
+    readonly type: "identity-ready";
+} | {
+    readonly type: "identity-detached";
+}) & {
+    readonly app: string;
+    readonly actorId: string;
+};
+export interface AppUpdateIdentity {
+    readonly actorId: string;
+    readonly app: string;
+    readonly status: "starting" | "ready";
+}
+/**
+ * The dev servers' own updates, for a session that serves its apps through the lab's proxy (backlog item 65): the
+ * runtime learns of a change from the dev server's update socket, and says when an update may reach an identity's
+ * pages. Without a policy no update reaches any page (a run is never disturbed); `product-lab dev` sets one that
+ * lets an in-place update through while no step acts as the identity.
+ */
+export interface AppUpdates {
+    /** The apps whose dev server the session serves through the proxy. */
+    apps(): readonly FollowedApp[];
+    /** Attached pages, including identities not yet listed in the environment's ready roster. */
+    identities?(): readonly AppUpdateIdentity[];
+    /** Asked for every update as it arrives: may `actorId`'s pages have it now? Undefined (the default): never. */
+    deliverWhen(policy: ((actorId: string, app: string, update: DevServerUpdate) => boolean) | undefined): void;
+    /** Ordinary observations are isolated; a hub ready boundary may await a returned promise. */
+    subscribe(listener: (event: AppUpdateEvent) => unknown): () => void;
+}
+/** Per-identity conditions in an environment (backlog 31): each identity's control, and what its sessions cannot apply. */
+export interface EnvironmentConditions {
+    /** What this environment's sessions cannot apply, with why (read before the run, also for identities not yet made). */
+    readonly unavailable?: {
+        readonly network?: string;
+        readonly cpu?: string;
+    };
+    /** The control of an identity's session; undefined when it has none (not started, or its host cannot condition it). */
+    control(actorId: string): ConditionControl | undefined;
+}
+export interface LabEnvironment {
+    /**
+     * Per-identity conditions (backlog 31) on the identities' own sessions. Absent: this environment cannot condition an
+     * identity, and a scenario that sets a condition is refused before it runs.
+     */
+    conditions?: EnvironmentConditions;
+    /** Every primary, viewer, adopted and navigation-created session, including sessions opened during a run. */
+    hostSessions?(): Promise<readonly HostSession[]>;
+    /**
+     * Backlog 108: open each person's sessions on a host that declares `capabilities.placement` in the place given for
+     * them (a lab-window tile), reopening the running ones there with the same identity, and later ones there from the
+     * start; `undefined` takes them back to the hosts' own browsers. Absent: this environment cannot place sessions.
+     */
+    placeSessions?(placements: SessionPlacements | undefined): Promise<void>;
+    /**
+     * Backlog 218: hold the environment's own background work (an identity pool onboarding spare identities, which
+     * re-roots rings and signs with accounts a scenario's steps also use) for the length of a feature scenario, so it never
+     * changes what the scenario's steps read or sign. Resolves once background work already under way has finished; the
+     * release lets it go on. Absent: the environment does no background work.
+     */
+    holdBackground?(signal?: AbortSignal): Promise<() => void>;
+    readonly hostBypassPolicies?: Readonly<Record<string, HostBypassPolicyData>>;
+    /** Local chains account for every extrinsic. Public networks explicitly cover only run identities. */
+    readonly hostBypassScope?: "all-local-extrinsics" | "run-accounts-only";
+    /** Exact setup/service transactions with a written reason; declarations never suppress ledger entries. */
+    transactionDeclarations?(): readonly TransactionDeclaration[];
+    /** Current active-run evidence for generic sentences. The runtime installs this while a run executes. */
+    hostBypassEvidence?(previous?: HostBypassEvidence): Promise<HostBypassEvidence>;
+    name: string;
+    provider: string;
+    provenance: Record<string, unknown>;
+    notices?: readonly string[];
+    /** How its start began (cold, warm, attached), as its environment adapter declares it; absent: not declared. */
+    startup?: EnvironmentStartup;
+    actors(): readonly ActorSession[];
+    scenarios: readonly ScenarioDefinition[];
+    /** Declarative labs (Phase 4): the sentence registry and the atomic calls feature steps run. */
+    sentences?: LabSentences;
+    /** Declarative labs: apps, integrations, services and availability for the panel. Never contains secret values. */
+    registry?: LabRegistry;
+    /** Host navigation (`withNavigation`): each actor's active application and the bridge evidence. */
+    navigation?: NavigationRecords & {
+        snapshot(): NavigationSnapshot;
+    };
+    observe(actor: ActorSession): Promise<unknown>;
+    /**
+     * Open `app` for an actor at a root-relative `path` (the generic sentence `{actor} opens {app} at {route}`,
+     * Phase 4). Environments whose sessions can navigate an actor's app offer it; resolves with what was opened.
+     */
+    openApp?(request: {
+        actorId: string;
+        app: string;
+        path: string;
+    }): Promise<unknown>;
+    /** Phase 5: read a resource an integration publishes (`<integration>.<name>`), as one identity when given. */
+    resources?: {
+        read(id: string, request?: {
+            actor?: string;
+        }): Promise<unknown>;
+        /**
+         * Phase 5 rest: watch a resource that declared `watch`, as one identity when given. `notify` is called on
+         * every change; resolves to how to stop watching, or undefined when the resource declares no `watch` (the
+         * caller falls back to reading on its own schedule).
+         */
+        watch?(id: string, notify: () => void, request?: {
+            actor?: string;
+        }): Promise<(() => void | Promise<void>) | undefined>;
+    };
+    /**
+     * The scenario conditions its integrations declare (`scenarioConditions`), read from this environment: which
+     * scenario tags fit it and why, merged per tag. Absent: the environment declares none. The runtime reads them once
+     * per environment session (a start, switch or reset) and never while nothing runs.
+     */
+    scenarioConditions?(signal?: AbortSignal): Promise<readonly TagCondition[]>;
+    /** Optional live diagnostics; unsubscribe must release readers/subscriptions. */
+    subscribe?(emit: ActivitySink): () => void;
+    /**
+     * Its running environment lost something it owns (RunningEnvironment.onLost, backlog item 70): the runtime fails
+     * the active run with the error and refuses new runs until a reset, switch or restart. Returns the unsubscribe.
+     */
+    onLost?(listener: (error: Error) => void): () => void;
+    /**
+     * Create a saved identity; `name` is the scenario actor it is created for (manual binding's "Create new identity").
+     * `signal` aborts the creation (the run stopped, or creating another actor of the same scenario failed).
+     * `conditions` (backlog 31): the scenario sets this identity's conditions, so its host sessions are opened ready
+     * for them (a native host's own links); without it nothing changes. `host` (backlog 28): the lab's `hosts` id the
+     * identity's sessions run in, one `hosts()` says is available, or a host reference (`hostReference`: the id with
+     * option values, an alias); absent: the session's default host. `hostOptions` (backlog 185): values of the host's
+     * per-identity options (`EnvironmentHost.options`), over the reference's own. `funds: "none"`
+     * (backlog 35c): the lab never funds this identity; only an environment that offers `fundsOf` takes it.
+     */
+    createActor?(options?: {
+        name?: string;
+        signal?: AbortSignal;
+        conditions?: boolean;
+        host?: string;
+        hostOptions?: HostOptionValues;
+        funds?: "none";
+    }): Promise<ActorSession>;
+    /**
+     * Backlog 35c: what an actor's account holds on each chain the session connects, read at the finalized head: its
+     * free balance (`System.Account`), with the block read. What `{actor} is a new actor with no funds` checks.
+     */
+    fundsOf?(actorId: string): Promise<readonly ActorFunds[]>;
+    /**
+     * Backlog 160: what the lab reads of a new identity once it is made, on each side: the chain (what it became there:
+     * recognised as a person, in a ring, at which block) and the screen (its app shows its account ready). The step that
+     * introduced it (`{actor} is a new actor`) shows them as its chain and screen checks. Absent: the environment says
+     * nothing of its identities, and those steps show no check.
+     */
+    actorReadings?(actorId: string, signal?: AbortSignal): Promise<readonly SideReading[]>;
+    /**
+     * The lab's declared hosts as this session sees them (backlog 28): which one an actor gets by default, and whether an
+     * actor may be created on each, with why not. The planner refuses a scenario naming an unavailable host with
+     * exactly that `reason`, so every surface says the same. Absent: actors run on the session's one host and a
+     * scenario that names a host is refused.
+     */
+    hosts?(): readonly EnvironmentHost[];
+    /**
+     * Backlog 247: probe a capability of declared host `hostId` (`HostProvider.probe`), created if need be but not prepared.
+     * Undefined when the host probes nothing. Absent: this session's hosts are not probed.
+     */
+    probeHost?(hostId: string, request: HostProbeRequest): Promise<HostProbe | undefined>;
+    /** The host adapters this lab can use but does not declare, to show greyed with how to turn each on. Absent: none. */
+    unconfiguredHosts?(): readonly UnconfiguredHost[];
+    /**
+     * The pre-onboarded identities this environment can open (backlog A3), in declaration order. Absent: none.
+     */
+    preOnboarded?(): readonly PreOnboardedActorView[];
+    /**
+     * Open the pre-onboarded identity declared as `name`: its host session signs with the wallet in its secret, like any
+     * actor's, and the lab never creates, funds or deletes it (`ActorSession.kind: "preOnboarded"`). Opening one that is
+     * already open returns its session. Rejects naming the problem (an unset secret, an account other than declared).
+     */
+    openPreOnboarded?(request: {
+        name: string;
+        signal?: AbortSignal;
+    }): Promise<ActorSession>;
+    /**
+     * How many `createActor` calls may run at once when a scenario introduces several actors. Opt-in: absent means one
+     * after another. An environment declares more only when its identity creation is safe to overlap.
+     */
+    readonly actorCreation?: {
+        readonly concurrency: number;
+    };
+    /**
+     * Root calls (calls dispatched with the chain's Root origin through its own Sudo pallet), when the lab declares a
+     * policy for this environment (`defineLab({ rootCalls })`). None is made until the runtime confirms this session
+     * (`LabRuntime.allowRootCalls` with the session's confirmation); then each call is still decided and checked.
+     */
+    readonly rootCalls?: RootCallControl;
+    /**
+     * Identities the environment prepares ahead, so `createActor` returns one at once. They are not actors until
+     * `createActor` hands one out: `actors()` never lists them. What the panel shows ("3 identities ready").
+     */
+    identityReserve?(): IdentityReserveStatus;
+    /**
+     * The environment's chains the runtime may read, by the ids its activity
+     * uses (`people`): finalized state and block contents, for "did this
+     * transaction land" (CheckTransactionLanded). The environment owns them and
+     * closes them with itself; the runtime never closes them.
+     */
+    chains?(): Readonly<Record<string, ChainHistory>>;
+    /**
+     * Every chain "did this transaction land" (CheckTransactionLanded) and the host check (HostBypassMonitor) read: each
+     * chain the lab connected for this environment, the session's own `chains()` readers in their place. Absent:
+     * `chains()`. Backlog A7 (6 October 2026): a session that names People alone made a Bulletin store unreadable after a
+     * failure ("no chain bulletin to read"). The account watch keeps reading `chains()`, the chains the session answers
+     * for; the host check reads these since it credits a host's own Bulletin account (`HostSession.resourceAccounts`, `signs`).
+     */
+    landingChains?(): Readonly<Record<string, ChainHistory>>;
+    /**
+     * Backlog 99: the lab's own readers of the environment's content stores (Bulletin's content, a chain's Statement
+     * Store), which "did this transaction land" asks about what a landed transaction stored. Absent, or undefined: the lab
+     * connected no chains, and such a write is reported unread.
+     */
+    storeReaders?(): ChainReaders | undefined;
+    /** Actual declared node URLs by chain id; distinguishes direct node GETs from ordinary app resources. */
+    chainEndpoints?(): Readonly<Record<string, string>>;
+    /**
+     * Every signing request identity `actorId`'s host decided since its session started, in order
+     * (`HostSession.approvals.signing`), or undefined when its host keeps no record (backlog item 63). With the
+     * chains above it lets the runtime settle a failed step from what the host and the chain saw of the identity's
+     * account, without reading the app's page. Absent: the environment offers no such record.
+     */
+    signing?(actorId: string): Promise<readonly SigningDecision[] | undefined>;
+    /**
+     * Backlog 41: every confirmation identity `actorId`'s apps asked their hosts for since each session started, in
+     * order, as each host words them (`HostSession.approvals.decisions`: `approved sign transaction`, `denied remote
+     * permission`), by app; an app whose host keeps no record is undefined. Undefined when the identity is not running.
+     * A record restarts with its host: a shorter later record is a restart. Absent: the environment offers no record.
+     */
+    hostRequests?(actorId: string): Promise<Readonly<Record<string, readonly string[] | undefined>> | undefined>;
+    /**
+     * What navigation destinations resolve against: the lab's apps, the
+     * namespace and, in `deployed-local`, the environment's name service
+     * (ResolveNavigationDestination; `LabRuntime.resolveDestination`). The
+     * environment owns the name service; the runtime never closes it.
+     */
+    destinations?(): DestinationDirectory;
+    /**
+     * Phase 9: how run recordings take a frame of an identity's app in this environment (its actors' own headless
+     * pages, `PageFrameCapture`). Absent: frames are recorded as unavailable unless the lab window registered a source.
+     */
+    frames?(): FrameCapture | undefined;
+    /**
+     * Backlog 23: watch what every identity's app prints from now on (console errors and warnings, uncaught script
+     * errors), including apps opened later, and which apps cannot be watched; the disposer stops the watch. Run
+     * recordings keep each message with the step that was running. Absent: recordings say the console was not watched.
+     */
+    console?: ConsoleWatch;
+    /** Backlog 23: console errors each app is known to print (literal parts, `apps.<id>.consoleAllowed`); others are flagged. */
+    readonly consoleAllowed?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Hot reload of app code (backlog item 5): load `app` again in identity `actorId`'s own page (the headless page
+     * background runs drive), keeping its host session, bridge and wallet, and resolve once the app is ready again with
+     * the same account. The runtime calls it only between the identity's steps (`AppReloads`), after a change of the
+     * app's watched source. Throw when this session cannot reload the app without losing state (the reason is shown).
+     * Absent: the lab refuses to hot reload and says so.
+     */
+    reloadApp?(actorId: string, request: {
+        readonly app: string;
+        readonly build: number;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * The dev servers' own updates (backlog item 65), when the session serves its apps through the lab's proxy: the
+     * runtime then needs no `watch` declaration to hot reload. Absent: the session's dev servers are not followed.
+     */
+    appUpdates?(): AppUpdates | undefined;
+    startActor?(id: string): Promise<void>;
+    stopActor?(id: string): Promise<void>;
+    /** `removal`: who asked and why, for the environment's own record of the removal (absent from older callers). */
+    deleteActor?(id: string, removal?: ActorRemoval): Promise<void>;
+    workspace?: WorkspaceStatus;
+    startWorkspace?(): Promise<void>;
+    stopWorkspace?(): Promise<void>;
+    /** Release app-owned resources after a job; paused checkpoints keep ownership. */
+    afterRun?(): Promise<void>;
+    /** Only owned providers expose reset; it must invalidate old actor sessions. */
+    reset?(): Promise<void>;
+    /** The lab's wrapper: each chain's day (`RunningEnvironment.chainDays`). */
+    chainDays?(): readonly ChainDay[];
+    /** The lab's wrapper: what a reset discards of the environment's chains (`RunningEnvironment.resetDiscards`). */
+    readonly resetDiscards?: string;
+    /** The lab's wrapper: why there is no reset (`RunningEnvironment.resetUnsupported`, or that neither offers one). */
+    readonly resetUnsupported?: string;
+    /** A session: the directories its identities' state lives in, for fixtures (absent: it keeps none). */
+    fixtureState?(): SessionFixtureState;
+    /** The lab's wrapper: saving and restoring fixtures, when the environment offers snapshots. */
+    readonly fixtures?: EnvironmentFixtures;
+    /** The lab's wrapper: why fixtures are unsupported here (the environment's `snapshotsUnsupported`, or that it offers none). */
+    readonly fixturesUnsupported?: string;
+    /**
+     * The environment's control over its chains' progress (`RunningEnvironment.time`, backlog 16): the generic sentences
+     * `the chain advances {int} blocks` and `time advances by {int} minutes` run through it. Absent: `timeUnsupported`.
+     */
+    readonly time?: EnvironmentTime;
+    /** Why the environment cannot advance its chains (its `timeUnsupported`, or that it offers no control). */
+    readonly timeUnsupported?: string;
+    close(): Promise<void>;
+}
+/** An environment's root calls, as the runtime sees them. */
+export interface RootCallControl {
+    /** The calls the policy allows, as `Pallet.call`. */
+    readonly allowed: readonly string[];
+    /** Whether root calls were confirmed for this session. */
+    readonly confirmed: boolean;
+    /** Root calls are confirmed for this session (the runtime checked the session's confirmation first). */
+    confirm(): void;
+}

package/core/ports/src/driven/lab/lab-environment.js

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