@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/application/src/orchestration/host/lab-navigation.js

@@ -0,0 +1,188 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { NavigationBridge } from "./navigation-bridge.js";
+import { HostSessionRegistry } from "./host-session-registry.js";
+async function pageUrl(session) {
+    try {
+        return (await session.page()).url();
+    }
+    catch {
+        return undefined;
+    }
+}
+export class LabNavigation {
+    options;
+    registry;
+    bridge;
+    active = new Map();
+    sinks = new Set();
+    names = new Map();
+    contents = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        for (const [appId, cid] of Object.entries(options.nameService?.deployments ?? {}))
+            this.contents.set(appId, cid);
+        const nameService = options.nameService;
+        this.registry = new HostSessionRegistry({
+            provider: options.provider,
+            apps: options.apps,
+            ...(options.approvals ? { approvals: options.approvals } : {}),
+            focus: (opened) => this.focused(opened),
+        });
+        this.bridge = new NavigationBridge({
+            registry: this.registry,
+            ...(options.namespace ? { namespace: options.namespace } : {}),
+            record: (evidence) => this.recorded(evidence),
+            clock: options.clock,
+            ...(nameService
+                ? {
+                    resolve: async (url) => (await nameService.resolver.execute(url, this.directory())).target,
+                    serve: async (target) => {
+                        if (!nameService.server)
+                            throw new Error(`${target.product} resolved to content no lab app declares, and this lab has no destination server`);
+                        if (!target.cid)
+                            throw new Error(`${target.product} has no content to serve`);
+                        const app = await nameService.server.app({ appId: target.appId, product: target.product, cid: target.cid });
+                        this.contents.set(app.id, target.cid);
+                        return app;
+                    },
+                }
+                : {}),
+            onStreamError: (session, error) => this.emit({
+                type: "message",
+                message: `Navigation requests from ${session.actor.name}'s ${session.app.id} session stopped: ${error instanceof Error ? error.message : String(error)}`,
+            }),
+        }).start();
+    }
+    directory() {
+        const apps = this.registry.registeredApps().map((app) => {
+            const cid = this.contents.get(app.id);
+            return cid ? { ...app, cid } : app;
+        });
+        return {
+            apps,
+            ...(this.options.namespace ? { namespace: this.options.namespace } : {}),
+            ...(this.options.nameService ? { names: this.options.nameService.names } : {}),
+        };
+    }
+    now() {
+        return this.options.clock.date().getTime();
+    }
+    open(actor, appId, path) {
+        if (this.closed)
+            throw new Error("Lab navigation is closed");
+        this.names.set(actor.id, actor.name);
+        return this.registry.open(actor, appId, path);
+    }
+    adopt(session, path) {
+        if (this.closed)
+            throw new Error("Lab navigation is closed");
+        this.names.set(session.actor.id, session.actor.name);
+        return this.registry.adopt(session, path);
+    }
+    async focused({ session, path }) {
+        const url = await (this.options.sessionUrl ?? pageUrl)(session);
+        this.active.set(session.actor.id, {
+            actorId: session.actor.id,
+            appId: session.app.id,
+            path: path ?? "/",
+            ...(url ? { url } : {}),
+            since: this.now(),
+        });
+    }
+    recorded(evidence) {
+        if ((evidence.outcome === "opened" || evidence.outcome === "focused") && evidence.toApp) {
+            const current = this.active.get(evidence.actorId);
+            if (current && current.appId === evidence.toApp)
+                this.active.set(evidence.actorId, {
+                    ...current,
+                    navigation: {
+                        url: evidence.url,
+                        requestedAt: evidence.requestedAt,
+                        outcome: evidence.outcome,
+                        fromApp: evidence.fromApp,
+                    },
+                });
+        }
+        const actorName = this.options.actorName?.(evidence.actorId) ?? this.names.get(evidence.actorId);
+        const url = evidence.toApp && evidence.outcome !== "failed" ? this.active.get(evidence.actorId)?.url : undefined;
+        this.emit({
+            type: "navigation",
+            evidence,
+            ...(actorName ? { actorName } : {}),
+            ...(url ? { destinationUrl: url } : {}),
+        });
+    }
+    emit(event) {
+        for (const sink of this.sinks) {
+            try {
+                sink(event);
+            }
+            catch {
+            }
+        }
+    }
+    subscribe(sink) {
+        this.sinks.add(sink);
+        return () => this.sinks.delete(sink);
+    }
+    evidence() {
+        return this.bridge.evidence();
+    }
+    activeApplication(actorId) {
+        return this.active.get(actorId);
+    }
+    waitFor(predicate, options) {
+        return this.bridge.waitFor(predicate, options);
+    }
+    snapshot() {
+        return { active: [...this.active.values()] };
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.bridge.stop();
+        this.sinks.clear();
+        try {
+            await this.registry.closeAll();
+        }
+        finally {
+            await this.options.nameService?.server?.close();
+        }
+    }
+}
+export function withNavigation(environment, navigation) {
+    return new Proxy(environment, {
+        get(target, property, receiver) {
+            if (property === "navigation")
+                return navigation;
+            if (property === "hostSessions")
+                return async () => [...new Set([...(await target.hostSessions?.() ?? []), ...await navigation.registry.all()])];
+            if (property === "destinations" && !target.destinations)
+                return () => navigation.directory();
+            if (property === "subscribe")
+                return (sink) => {
+                    const own = target.subscribe?.(sink);
+                    const nav = navigation.subscribe(sink);
+                    return () => {
+                        nav();
+                        own?.();
+                    };
+                };
+            if (property === "close")
+                return async () => {
+                    const errors = [];
+                    await navigation.close().catch((error) => errors.push(error));
+                    await target.close().catch((error) => errors.push(error));
+                    if (errors.length === 1)
+                        throw errors[0];
+                    if (errors.length)
+                        throw new AggregateError(errors, "Closing the environment and its navigation failed");
+                };
+            const value = Reflect.get(target, property, receiver);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}

package/core/application/src/orchestration/host/navigation-bridge.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The navigation bridge (docs/design.md, section 11).
+ *
+ * A real product button calls `navigateTo`; the truAPI core validates and
+ * normalises the URL; a host that declares `navigationEvents` reports it on
+ * `HostSession.navigations`. The bridge resolves the destination to a
+ * registered app and opens that app for the SAME actor (creating or focusing
+ * the actor's session for it), and records every request with its outcome as
+ * evidence a scenario asserts on. The bridge never switches an app on its own:
+ * only a reported request drives it.
+ *
+ * In `deployed-local` the destination is what the name resolves to on the
+ * environment's name service (`resolve`), and content no lab app declares is
+ * served as a new app (`serve`, the local gateway) before it is opened for the
+ * same actor; an unregistered name is recorded and refused.
+ */
+import { type NavigationEvidence, type NavigationRequested, type NavigationTarget } from "@parity/product-lab/domain";
+import type { Clock } from "@parity/product-lab/ports/system";
+import type { HostApp, HostSession } from "./port.js";
+import type { HostSessionRegistry } from "./host-session-registry.js";
+/** What the bridge records per request (the domain's; one kind of `Evidence`). */
+export type { NavigationEvidence } from "@parity/product-lab/domain";
+export interface NavigationBridgeOptions<Session extends HostSession> {
+    registry: HostSessionRegistry<Session>;
+    /** Network namespace (`paseo`, `testnet`); `.dot` names resolve inside it. */
+    namespace?: string;
+    /** Receives every evidence record as it is produced. */
+    record?: (evidence: NavigationEvidence) => void;
+    /** Time for `handledAt` (wall clock) and `waitFor` (deadlines and polling): core reads time only through the Clock port. */
+    clock: Clock;
+    /** Called when a session's navigation stream fails. */
+    onStreamError?: (session: Session, error: unknown) => void;
+    /**
+     * Resolves a request's destination, for example through the environment's
+     * name service (`LabNavigation` wires ResolveNavigationDestination in
+     * deployed-local). Default: the registry's apps, a static map.
+     */
+    resolve?: (url: string) => Promise<NavigationTarget>;
+    /**
+     * Serves a destination the name service resolved that no lab app declares
+     * (`target.discovered`) as a new app, for example through the local gateway.
+     * Without it such a request fails: the lab cannot show content it does not serve.
+     */
+    serve?: (target: Extract<NavigationTarget, {
+        kind: "app";
+    }>) => Promise<HostApp>;
+}
+export declare class NavigationBridge<Session extends HostSession = HostSession> {
+    private readonly options;
+    private readonly log;
+    private readonly watchers;
+    private readonly abort;
+    private queue;
+    private detach?;
+    /** Navigation streams that failed, with the session they belonged to. */
+    readonly streamErrors: {
+        actorId: string;
+        appId: string;
+        error: unknown;
+    }[];
+    constructor(options: NavigationBridgeOptions<Session>);
+    /** Attach to every session the registry creates from now on. */
+    start(): this;
+    /** Consume one session's navigation requests until it stops. Idempotent. */
+    watch(session: Session): Promise<void>;
+    /** Handle requests one at a time, in arrival order across all sessions, so
+     * two requests for one actor cannot race to create the same session. */
+    private enqueue;
+    /** Resolve one request from `source` and open the destination for the same actor. */
+    handle(source: Pick<Session, "actor" | "app">, request: NavigationRequested): Promise<NavigationEvidence>;
+    /** Where a request leads: the configured resolver, else the registry's apps. A failing resolver refuses the request. */
+    private destination;
+    /** Every request handled so far, in order. */
+    evidence(): readonly NavigationEvidence[];
+    /** Wait until `predicate` holds for the evidence (or time out). */
+    waitFor(predicate: (evidence: readonly NavigationEvidence[]) => boolean, { timeoutMs, pollMs }?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<readonly NavigationEvidence[]>;
+    /** Stop following new requests; sessions keep running. */
+    stop(): Promise<void>;
+}

package/core/application/src/orchestration/host/navigation-bridge.js

@@ -0,0 +1,123 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { resolveNavigation } from "@parity/product-lab/domain";
+export class NavigationBridge {
+    options;
+    log = [];
+    watchers = new Map();
+    abort = new AbortController();
+    queue = Promise.resolve();
+    detach;
+    streamErrors = [];
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        this.detach ??= this.options.registry.onCreated((session) => {
+            void this.watch(session);
+        });
+        return this;
+    }
+    watch(session) {
+        const existing = this.watchers.get(session);
+        if (existing)
+            return existing;
+        const stream = session.navigations;
+        const done = stream
+            ? (async () => {
+                for await (const request of stream) {
+                    if (this.abort.signal.aborted)
+                        break;
+                    await this.enqueue(session, request);
+                }
+            })().catch((error) => {
+                this.streamErrors.push({ actorId: session.actor.id, appId: session.app.id, error });
+                this.options.onStreamError?.(session, error);
+            })
+            : Promise.resolve();
+        this.watchers.set(session, done);
+        return done;
+    }
+    enqueue(session, request) {
+        const next = this.queue.then(() => this.handle(session, request));
+        this.queue = next.catch(() => undefined);
+        return next;
+    }
+    async handle(source, request) {
+        const now = () => this.options.clock.date().getTime();
+        const target = await this.destination(request.url);
+        const base = {
+            kind: "navigation",
+            actorId: source.actor.id,
+            fromApp: source.app.id,
+            url: request.url,
+            product: request.product,
+            path: request.path,
+            requestedAt: request.at,
+            target,
+        };
+        let evidence;
+        if (target.kind !== "app") {
+            evidence = { ...base, outcome: "ignored", handledAt: now() };
+        }
+        else {
+            try {
+                if (target.discovered && !this.options.registry.registeredApps().some((app) => app.id === target.appId)) {
+                    if (!this.options.serve)
+                        throw new Error(`${target.product} resolved to ${target.cid ?? "content"}, but this lab serves no content by name (no destination server)`);
+                    this.options.registry.register(await this.options.serve(target));
+                }
+                const opened = await this.options.registry.open(source.actor, target.appId, target.path);
+                evidence = {
+                    ...base,
+                    outcome: opened.created ? "opened" : "focused",
+                    toApp: target.appId,
+                    handledAt: now(),
+                };
+            }
+            catch (error) {
+                evidence = {
+                    ...base,
+                    outcome: "failed",
+                    toApp: target.appId,
+                    handledAt: now(),
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }
+        this.log.push(evidence);
+        this.options.record?.(evidence);
+        return evidence;
+    }
+    async destination(url) {
+        if (!this.options.resolve)
+            return resolveNavigation(url, this.options.registry.registeredApps(), {
+                ...(this.options.namespace ? { namespace: this.options.namespace } : {}),
+            });
+        try {
+            return await this.options.resolve(url);
+        }
+        catch (error) {
+            return { kind: "invalid", url, reason: `resolving the destination failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    evidence() {
+        return this.log;
+    }
+    async waitFor(predicate, { timeoutMs = 30_000, pollMs = 50 } = {}) {
+        const { clock } = this.options;
+        const deadline = clock.now() + timeoutMs;
+        while (!predicate(this.log)) {
+            if (clock.now() > deadline)
+                throw new Error(`navigation evidence did not appear within ${timeoutMs}ms`);
+            await clock.sleep(pollMs);
+        }
+        return this.log;
+    }
+    async stop() {
+        this.detach?.();
+        this.detach = undefined;
+        this.abort.abort();
+        await this.queue;
+    }
+}

package/core/application/src/orchestration/host/port.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The HostProvider port (docs/design.md, sections 3, 9 and 10). The interfaces
+ * moved to `@parity/product-lab/ports/host` in refactor step 7 part b; the capability
+ * vocabulary and the helpers with behaviour (`hostSupports`, `appUrl`,
+ * `appUrlAt`, `UnsupportedHostOperation`) moved to `@parity/product-lab/domain` in L1.
+ * This module re-exports them for core's callers.
+ */
+export type { ApprovalPolicy, BlockedRequest, HostActor, HostApp, HostAppContext, HostCapabilities, HostProvider, HostRequirement, HostSession, HostSessionEvidence, HostSessionRequest, PendingApproval, ResolvedHost, SessionApprovals, VerifiedAccount, } from "@parity/product-lab/ports/host";
+export type { ProvisionedIdentity } from "../identity/port.js";
+/** One navigation request a product made through the host (the domain's). */
+export type { NavigationRequested } from "@parity/product-lab/domain";
+export { UnsupportedHostOperation, appUrl, appUrlAt, hostSupports } from "@parity/product-lab/domain";

package/core/application/src/orchestration/host/port.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { UnsupportedHostOperation, appUrl, appUrlAt, hostSupports } from "@parity/product-lab/domain";

package/core/application/src/orchestration/host/session-records.d.ts

@@ -0,0 +1,11 @@
+import type { HostSession, SigningDecision } from "@parity/product-lab/ports/host";
+type Sessions = () => Promise<readonly HostSession[]>;
+/**
+ * Every request `actorId`'s apps asked their hosts for, by app id, as `LabEnvironment.hostRequests` gives it: an app
+ * whose host keeps no record is undefined; undefined when the identity has no session. Two sessions of one app (a
+ * reopened one) are read in the order the environment lists them.
+ */
+export declare function hostRequestsOf(sessions: Sessions, actorId: string): Promise<Readonly<Record<string, readonly string[] | undefined>> | undefined>;
+/** Every signing request `actorId`'s hosts decided, as `LabEnvironment.signing` gives it; undefined when it has no session or one of them keeps no record. */
+export declare function signingOf(sessions: Sessions, actorId: string): Promise<readonly SigningDecision[] | undefined>;
+export {};

package/core/application/src/orchestration/host/session-records.js

@@ -0,0 +1,23 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export async function hostRequestsOf(sessions, actorId) {
+    const own = (await sessions()).filter((session) => session.actor.id === actorId);
+    if (!own.length)
+        return undefined;
+    const record = {};
+    for (const session of own) {
+        const asked = await session.approvals.decisions?.();
+        const app = session.app.id;
+        if (asked === undefined)
+            record[app] ??= undefined;
+        else
+            record[app] = [...(record[app] ?? []), ...asked];
+    }
+    return record;
+}
+export async function signingOf(sessions, actorId) {
+    const own = (await sessions()).filter((session) => session.actor.id === actorId);
+    if (!own.length || own.some((session) => !session.approvals.signing))
+        return undefined;
+    return (await Promise.all(own.map((session) => session.approvals.signing()))).flat();
+}

package/core/application/src/orchestration/identity/index.d.ts

@@ -0,0 +1 @@
+export * from "./port.js";

package/core/application/src/orchestration/identity/index.js

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

package/core/application/src/orchestration/identity/port.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The IdentityProvisioner port (docs/design.md, section 9).
+ *
+ * Creating an identity (a wallet root, optionally onboarded as a lite person
+ * with a username) is separate from the host that later signs with it: any
+ * host that declares `identityImport` accepts a `ProvisionedIdentity`, and the
+ * same entropy yields the same product accounts in every conforming host.
+ */
+export type { ProvisionedIdentity } from "@parity/product-lab/domain/identity";
+export { BIP39_ENTROPY_LENGTHS, assertBip39Entropy } from "@parity/product-lab/domain/identity";
+export type { IdentityProvisioner, IdentityProvisionerCapabilities, ProvisionRequest } from "@parity/product-lab/ports/identity";

package/core/application/src/orchestration/identity/port.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { BIP39_ENTROPY_LENGTHS, assertBip39Entropy } from "@parity/product-lab/domain/identity";

package/core/application/src/orchestration/index.d.ts

@@ -0,0 +1,52 @@
+export * from "./types.js";
+export * from "./definitions.js";
+export { HostBypassAssertion, HostBypassPolicy, HOST_BYPASS_SENTENCE, type HostBypassEvidence, type HostBypassPolicyData, type AppHostBypassEvidence, type AppNetworkEvidence, type DirectConnection, type FinalizedLedgerEntry, type TransactionDeclaration } from "@parity/product-lab/domain";
+export * from "./activity/types.js";
+export { monitorChains, type ChainReader } from "./activity/monitor.js";
+export { managedEnvironment } from "./managed-environment.js";
+export * from "./capabilities.js";
+export { defineLab, defineEnvironment, isLabDefinition, type AppAvailability, type AppDefinition, type EnvironmentProvider, type EnvironmentStartContext, type LabDefinition, type LabServices, type RunningEnvironment, type SessionContext, } from "./lab/define.js";
+export * from "./lab/product-lab-config.js";
+export { CHECK_FAILED, CHECK_REASONS, CONTROL_TAGS, INFRASTRUCTURE_REASONS, LabFailure, fail, isInfrastructureReason, type CheckReason, type FailureReason, type InfrastructureReason, type StepFailure } from "@parity/product-lab/domain";
+/** The progress port: the phases an environment start reports (`EnvironmentStartContext.phase`, `SessionContext.phase`). */
+export type { StartPhaseSink, StartPhaseState, StartPhaseUpdate } from "@parity/product-lab/ports/environment";
+/** Backlog 16: an environment's control over its chains' progress (`RunningEnvironment.time`). */
+export type { AdvanceBlocksRequest, AdvanceClockRequest, ChainAdvance, ChainMoment, EnvironmentTime } from "@parity/product-lab/ports/environment";
+export { compileLab, describeOffer, type CompiledLab, type CompileOptions } from "./lab/compile.js";
+export { FALLBACK_SESSION_PORTS, SESSION_PORTS_VARIABLE, declaredPortRanges, ephemeralPortsWarning, longestFreeRun, warnOfEphemeralPorts, parseSessionPorts, portBlock, resolveSessionPorts, type DeclaredPorts, type SessionPorts } from "./lab/session-ports.js";
+export type { ActionRootCall, RootCallSupport } from "./lab/root-call-access.js";
+export { DeclaredLabCatalog, type DeclaredLabCatalogOptions } from "./lab/declared-lab-catalog.js";
+export { inspectedLab, loadedLab, type LabModuleOptions, type LoadedDeclarativeLab, type LoadedLabModule, } from "./lab/loaded-lab.js";
+export { preparedLab, SourceLabLoader, type LabPreparation } from "./lab/source-lab-loader.js";
+export { assertEnvironmentStartable, environmentRegistry, EnvironmentRegistry, isTopologyEnvironment, missingCapabilityReason, nameEnvironment, resolveEnvironment, resolveEnvironments, type EnvironmentFactory, type EnvironmentWords, type LabEnvironmentEntry, type ResolvedEnvironment, type TopologyEnvironment, } from "./lab/environments.js";
+export { environmentOptions, isOptionsEnvironment, type EnvironmentOptionEntry, type OptionsEnvironment } from "./lab/environment-options.js";
+export { appAvailability, defaultEnvironmentId, labIntegrations, unavailableNotice, validateLab, } from "./lab/validate.js";
+export { buildRegistry, type LabRegistry } from "./lab/registry.js";
+export { actorSecretProblems, environmentActors } from "./lab/environment-actors.js";
+export { blockingIntegrations, integrationAvailability, type IntegrationAvailability, type IntegrationFailure, type IntegrationStatus, } from "./lab/integration-availability.js";
+export { environmentRetention, stateText, topologyDetails, topologyRetention, type TopologyView, } from "./lab/environment-view.js";
+export { layerTopologyOverrides } from "./lab/topology-overrides.js";
+export { devAccount, fromEnv, isSecretSource, SecretSource, type SecretEntry, type SecretKind, } from "./secrets/sources.js";
+export { SecretError, SecretResolver, type SecretSigner, type SecretTarget } from "./secrets/secret-resolver.js";
+export { AuthorityError, defineService, ServiceError, StaleGenerationError, serviceGraphErrors, type ServiceContext, type ServiceDefinition, type ServiceLifetime, type ServiceLookup, } from "./services/define.js";
+export { ServiceContainer, type ServiceContainerOptions, type ServiceScope, type ScenarioServiceScope } from "./services/service-container.js";
+export { defineAuthorizedService, expectAuthority, type AuthorityVerdict, type AuthorizedServiceContext, type AuthorizedServiceDefinition, } from "./services/authorized-service.js";
+export { defineAction, defineAssertion, defineIntegration, defineStepGroup, defineResource, sentencePattern, sentenceParameters, type ActionContext, type SentenceArgument, type SentenceMapping, type StepOutputs, type ActionDefinition, type AssertionContext, type AssertionDefinition, type EnvironmentActionContext, type EnvironmentActionDefinition, type EnvironmentAssertionContext, type EnvironmentAssertionDefinition, type IntegrationAction, type IntegrationAssertion, type IntegrationChain, type IntegrationDefinition, type IntegrationScenario, type IntegrationScenarioStep, type IntegrationScenarioStepContext, type IntegrationServices, type StepGroupDefinition, type IntegrationUi, type ResourceContext, type ResourceDefinition, type ScenarioConditionContext, type TagCondition, type UiModuleReference, } from "./integrations/define.js";
+export { defineSteps } from "./integrations/define.js";
+export type { ResourceAccount } from "./integrations/define.js";
+export { statementReader, type RefusedStatement, type StatementEntry, type StatementPerson, type StatementRead, type StatementReader, type StatementReaderSpec, type StatementReadOptions, } from "./chain/statement-reader.js";
+export { statementTopic } from "@parity/product-lab/domain/statements";
+export { chainEventAssertion, type ChainEventCheck, type ChainEventObserved } from "./integrations/chain-event-assertion.js";
+export { declaredSubmission, KnownSubmissionError, type DeclaredSubmission } from "./integrations/known-submission-error.js";
+export { checkUiAgainstChain, type ChainReadAt, type EventualUiChainCheck, type OptimisticUiChainCheck, type PinnedUiChainCheck, type PinnedUiReading, type UiChainCheck, type UiChainCheckContext, type UiReading, } from "./integrations/ui-chain-check.js";
+export { AGREEMENT_MODES, AGREEMENT_MODE_USE, UiChainDisagreementError, claimText, sameClaim, sameFields, type AgreementBacking, type AgreementFailure, type AgreementMode, type AgreementState, type AgreementStep, type PendingTransaction, type ShownBlock, type UiChainAgreement, } from "@parity/product-lab/domain";
+export { IntegrationRegistry, type RegisteredSentence } from "./integrations/integration-registry.js";
+export { ACTIVE_APPLICATION_SENTENCE, ACTORS_EXIST_SENTENCE, ADVANCE_BLOCKS_SENTENCE, ADVANCE_TIME_SENTENCE, AT_THE_SAME_TIME_SENTENCE, GENERIC_SENTENCES, NAVIGATION_OUTCOMES, NAVIGATION_REQUESTED_SENTENCE, NEW_ACTOR_SENTENCE, OPEN_APP_SENTENCE, TOGETHER_SENTENCE, isGenericOwner, } from "./integrations/generic-sentences.js";
+export * from "./topology.js";
+export * from "./host/index.js";
+export * from "./identity/index.js";
+export { AccountAddress, AccountFormatError, AmbiguousAccountError, ExpectedAccount, accountPublicKey, accountSs58, expectedAccount, sameAccount } from "@parity/product-lab/domain";
+export type { AccountComparison, AppAccountDeclaration, AppReadyDeclaration, H160Mapping } from "@parity/product-lab/domain";
+export { PreOnboardedActor, PublicTarget, preOnboarded, runScoped, isRunScoped, withholdCapabilities } from "@parity/product-lab/domain";
+export type { ActorDeclarationData, ActorKind, PreOnboardedActorData, PublicAccess, PublicTargetData, PublicTimeouts } from "@parity/product-lab/domain";
+export * from "./run/index.js";

package/core/application/src/orchestration/index.js

@@ -0,0 +1,46 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export * from "./types.js";
+export * from "./definitions.js";
+export { HostBypassAssertion, HostBypassPolicy, HOST_BYPASS_SENTENCE } from "@parity/product-lab/domain";
+export * from "./activity/types.js";
+export { monitorChains } from "./activity/monitor.js";
+export { managedEnvironment } from "./managed-environment.js";
+export * from "./capabilities.js";
+export { defineLab, defineEnvironment, isLabDefinition, } from "./lab/define.js";
+export * from "./lab/product-lab-config.js";
+export { CHECK_FAILED, CHECK_REASONS, CONTROL_TAGS, INFRASTRUCTURE_REASONS, LabFailure, fail, isInfrastructureReason } from "@parity/product-lab/domain";
+export { compileLab, describeOffer } from "./lab/compile.js";
+export { FALLBACK_SESSION_PORTS, SESSION_PORTS_VARIABLE, declaredPortRanges, ephemeralPortsWarning, longestFreeRun, warnOfEphemeralPorts, parseSessionPorts, portBlock, resolveSessionPorts } from "./lab/session-ports.js";
+export { DeclaredLabCatalog } from "./lab/declared-lab-catalog.js";
+export { inspectedLab, loadedLab, } from "./lab/loaded-lab.js";
+export { preparedLab, SourceLabLoader } from "./lab/source-lab-loader.js";
+export { assertEnvironmentStartable, environmentRegistry, EnvironmentRegistry, isTopologyEnvironment, missingCapabilityReason, nameEnvironment, resolveEnvironment, resolveEnvironments, } from "./lab/environments.js";
+export { environmentOptions, isOptionsEnvironment } from "./lab/environment-options.js";
+export { appAvailability, defaultEnvironmentId, labIntegrations, unavailableNotice, validateLab, } from "./lab/validate.js";
+export { buildRegistry } from "./lab/registry.js";
+export { actorSecretProblems, environmentActors } from "./lab/environment-actors.js";
+export { blockingIntegrations, integrationAvailability, } from "./lab/integration-availability.js";
+export { environmentRetention, stateText, topologyDetails, topologyRetention, } from "./lab/environment-view.js";
+export { layerTopologyOverrides } from "./lab/topology-overrides.js";
+export { devAccount, fromEnv, isSecretSource, SecretSource, } from "./secrets/sources.js";
+export { SecretError, SecretResolver } from "./secrets/secret-resolver.js";
+export { AuthorityError, defineService, ServiceError, StaleGenerationError, serviceGraphErrors, } from "./services/define.js";
+export { ServiceContainer } from "./services/service-container.js";
+export { defineAuthorizedService, expectAuthority, } from "./services/authorized-service.js";
+export { defineAction, defineAssertion, defineIntegration, defineStepGroup, defineResource, sentencePattern, sentenceParameters, } from "./integrations/define.js";
+export { defineSteps } from "./integrations/define.js";
+export { statementReader, } from "./chain/statement-reader.js";
+export { statementTopic } from "@parity/product-lab/domain/statements";
+export { chainEventAssertion } from "./integrations/chain-event-assertion.js";
+export { declaredSubmission, KnownSubmissionError } from "./integrations/known-submission-error.js";
+export { checkUiAgainstChain, } from "./integrations/ui-chain-check.js";
+export { AGREEMENT_MODES, AGREEMENT_MODE_USE, UiChainDisagreementError, claimText, sameClaim, sameFields, } from "@parity/product-lab/domain";
+export { IntegrationRegistry } from "./integrations/integration-registry.js";
+export { ACTIVE_APPLICATION_SENTENCE, ACTORS_EXIST_SENTENCE, ADVANCE_BLOCKS_SENTENCE, ADVANCE_TIME_SENTENCE, AT_THE_SAME_TIME_SENTENCE, GENERIC_SENTENCES, NAVIGATION_OUTCOMES, NAVIGATION_REQUESTED_SENTENCE, NEW_ACTOR_SENTENCE, OPEN_APP_SENTENCE, TOGETHER_SENTENCE, isGenericOwner, } from "./integrations/generic-sentences.js";
+export * from "./topology.js";
+export * from "./host/index.js";
+export * from "./identity/index.js";
+export { AccountAddress, AccountFormatError, AmbiguousAccountError, ExpectedAccount, accountPublicKey, accountSs58, expectedAccount, sameAccount } from "@parity/product-lab/domain";
+export { PreOnboardedActor, PublicTarget, preOnboarded, runScoped, isRunScoped, withholdCapabilities } from "@parity/product-lab/domain";
+export * from "./run/index.js";

package/core/application/src/orchestration/integrations/chain-event-assertion.d.ts

@@ -0,0 +1,49 @@
+import { type AccountComparison } from "@parity/product-lab/domain";
+import { type AssertionDefinition } from "./define.js";
+import type { ChainHead } from "../chain/chain-connection.js";
+export interface ChainEventCheck {
+    /** e.g. "System". */
+    pallet: string;
+    /** e.g. "Remarked". */
+    event: string;
+    /**
+     * The event's fields to match, built from the acting actor's account and the sentence's last string argument. A
+     * field whose value is that account is matched as an account, in whatever form the chain writes it (its own SS58
+     * prefix, a public key); name another account with `expectedAccount(...)`. Every other field is compared exactly.
+     */
+    expected(account: string, arg: string): Readonly<Record<string, unknown>>;
+    /**
+     * How this chain relates a 32-byte account to a 20-byte address, for an event that carries the actor as a 20-byte
+     * address (`{ h160: "revive" }` on a pallet-revive chain). Without it such a comparison is refused, not guessed.
+     */
+    accounts?: AccountComparison;
+    /** Which of `AssertionContext.chains` to read; default the first one the context carries. */
+    chain?: string;
+    /** How far back of the head to start scanning when the caller does not track its own "since" (default 200 blocks). */
+    window?: number;
+    timeoutMs?: number;
+    /**
+     * Which block the check needs (backlog 14): `finalized` (the default: the event is chain truth) or `best` (it is in
+     * a block the node follows, which may still be retracted). Recorded in the observation.
+     */
+    reads?: ChainHead;
+}
+export interface ChainEventObserved {
+    /** The head the event was found on: `finalized` or `best`. */
+    readonly head: ChainHead;
+    readonly block: number;
+    readonly blockHash: string;
+    readonly extrinsicIndex: number;
+    readonly value: unknown;
+}
+/**
+ * `defineAssertion` for "the finalized chain shows this event, matching these
+ * fields, from this actor" — the independent chain half of a check, meant to
+ * run alongside the product's own UI assertion. `compare` is a no-op:
+ * `observe` already throws when the event never lands (the same shape every
+ * product's own `waitFor<Thing>` used).
+ */
+export declare function chainEventAssertion(definition: {
+    title: string;
+    sentence: string;
+} & ChainEventCheck): AssertionDefinition<ChainEventObserved, unknown>;