@parity/product-lab 0.0.1-placeholder → 0.1.0

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

@@ -0,0 +1,33 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { AccountAddress, ExpectedAccount } from "@parity/product-lab/domain";
+import { matchFields, waitForEvent } from "../chain/events.js";
+import { defineAssertion } from "./define.js";
+function chainOf(context, id) {
+    const chains = context.chains ?? {};
+    const key = id ?? Object.keys(chains)[0];
+    const connection = key ? chains[key] : undefined;
+    if (!connection)
+        throw new Error(id ? `No chain "${id}" (available: ${Object.keys(chains).join(", ") || "none"})` : "This assertion needs AssertionContext.chains (load the lab through the composition root)");
+    return connection;
+}
+export function chainEventAssertion(definition) {
+    const { title, sentence, pallet, event, expected, accounts, chain, window = 200, timeoutMs, reads = "finalized" } = definition;
+    return defineAssertion({
+        title,
+        sentence,
+        reads,
+        async observe(context, args) {
+            const arg = String(Object.values(args).at(-1) ?? "");
+            const connection = chainOf(context, chain);
+            const head = reads === "best" ? await connection.access.bestHead() : await connection.access.finalizedHead();
+            const since = Math.max(0, head.number - window);
+            const account = context.actor.account;
+            const asAccount = AccountAddress.tryParse(account) ? new ExpectedAccount(account, accounts) : undefined;
+            const want = Object.fromEntries(Object.entries(expected(account, arg)).map(([key, item]) => [key, asAccount && item === account ? asAccount : item]));
+            const found = await waitForEvent(connection, `${context.actor.name}'s account shows ${pallet}.${event}`, pallet, event, (value) => matchFields(value, want), since, timeoutMs, reads);
+            return { head: reads, block: found.block, blockHash: found.blockHash, extrinsicIndex: found.extrinsicIndex, value: found.value };
+        },
+        compare() { },
+    });
+}

package/core/application/src/orchestration/integrations/define.d.ts

@@ -0,0 +1,472 @@
+import { type OutputKind, type RowExpansion, type TableRow, type TableSpec, type TagCondition, type ValueToneDeclaration } from "@parity/product-lab/domain";
+import { type SideReading, type StepWrite } from "@parity/product-lab/domain/checks";
+import type { AppSurface } from "@parity/product-lab/ports/browser";
+import type { ChainAccess, ChainHistory, ChainReaders } from "@parity/product-lab/ports/chain";
+import type { EnvironmentHost, SentenceArgument, SentenceScenarioContext, StepOutputs } from "@parity/product-lab/ports/lab";
+import type { HostProbe, HostProbeRequest } from "@parity/product-lab/ports/host";
+import type { ChainConnection, ChainHead } from "../chain/chain-connection.js";
+/** A chain connection an integration can read and wait on independently, with the port's block-by-number lookup (ChainConnection.waitFor + ChainHistory.blockAt). */
+export type IntegrationChain = ChainConnection<ChainAccess & ChainHistory>;
+export type { SentenceArgument, SentenceScenarioContext, StepOutputs } from "@parity/product-lab/ports/lab";
+import type { ActivityEvent, UnsettledTransaction } from "../activity/types.js";
+import type { AppRequirements } from "../capabilities.js";
+import type { ServiceDefinition } from "../services/define.js";
+import type { ActorSession, InputField, Inputs, ScenarioContext, ScenarioDefinition, ScenarioStep } from "../types.js";
+import type { ActionRootCall } from "../lab/root-call-access.js";
+/** Services as an integration sees them: its own by short name, others as `integration.service`. */
+export interface IntegrationServices {
+    get<T = unknown>(name: string): Promise<T>;
+}
+export interface ActionContext {
+    readonly actor: ActorSession;
+    /** The feature execution and its role-to-identity bindings, when called from a feature. */
+    readonly scenario?: SentenceScenarioContext;
+    readonly signal: AbortSignal;
+    progress(message: string): void;
+    report(event: ActivityEvent): void;
+    /** Scenario-scoped view: scenario services are fresh for this run, actor/environment services are shared. */
+    readonly services: IntegrationServices;
+    /**
+     * The actor's app as the run shows it, when the run supplies one: in the
+     * visible lab window, the actor's displayed iframe (every primitive proves
+     * the target is on screen). Absent in headless runs, where the integration
+     * drives the actor's own page (for example `new HeadlessAppSurface(page)`
+     * from `@parity/product-lab/browser-playwright`).
+     */
+    readonly ui?: AppSurface;
+    /** Outputs of earlier steps (feature runs). */
+    readonly outputs?: StepOutputs;
+    /**
+     * A live, opened connection per chain the running environment declares
+     * (`{ people: access }`), so an integration needs no chain SDK and no
+     * connection of its own to read or submit independently of the app (the
+     * composition root opens and closes them; absent without one, for example
+     * a lab compiled for tests only).
+     */
+    readonly chains?: Readonly<Record<string, IntegrationChain>>;
+    /**
+     * A root call: `call` dispatched with `chain`'s Root origin through its own Sudo pallet. Present when the lab declares
+     * root calls for this environment (`defineLab({ rootCalls })`); refused until the session is confirmed
+     * (`LabRuntime.allowRootCalls`, the CLI's `--root-calls`), on a mainnet, on a chain the lab neither started nor knows,
+     * for a call off the allow-list, or with a key that is not the chain's `Sudo.Key`. Resolves once final and applied;
+     * every call is recorded as evidence.
+     */
+    readonly rootCall?: ActionRootCall;
+    /**
+     * Which block this call's chain waits rest on (its definition's `reads`, default `finalized`; backlog 14).
+     */
+    readonly reads?: ChainHead;
+    /**
+     * The same view of a connection the integration owns (its own `ChainConnection`) that `chains` gives of the lab's:
+     * waits on `reads` by default, reported to this step with their head; for a check that needs finality, a wait on
+     * the best block is refused.
+     */
+    chainView?<Access extends ChainAccess>(connection: ChainConnection<Access>): ChainConnection<Access>;
+    /**
+     * Backlog 160: what the action read back of its own effect, as its step's chain check (a source the lab reads itself:
+     * what, where, at which block) or screen check (what the person's app showed), kept on the step whether it passes or
+     * fails, as an assertion's `reading`. Every action that changes something records both sides. Absent outside a run.
+     */
+    reading?(reading: SideReading): void;
+    /**
+     * Backlog 161: a write the action caused that is not one of the lab's transactions (a Statement Store statement, a
+     * transaction the person's host signed, content stored for the person), once read back, so the run's Transactions
+     * view lists it. Absent outside a run.
+     */
+    write?(write: StepWrite): void;
+    /** The lab's own reads of what an app stored, as a check gets them (AssertionContext.readers): read an action's effect. */
+    readonly readers?: ChainReaders;
+    /**
+     * A person's resource accounts, as a check gets them (AssertionContext.resourceAccounts): the acting actor's, or the
+     * scenario actor `actorName`'s. Absent for an action that acts as no actor, and where the lab cannot derive them.
+     */
+    resourceAccounts?(actorName?: string): Promise<readonly ResourceAccount[]>;
+}
+/**
+ * How one sentence's words become the action's inputs. Data only in spirit:
+ * a mapping names inputs, it never decides outcomes.
+ *
+ * - `{}` (or listing the sentence in an array): the first `{actor}` is the
+ *   acting actor; the other values fill the action's `inputs` in declaration order.
+ * - a function: receives every value (actors included) and returns the inputs.
+ * - `{ table, map }`: a sentence ending in ":" declares its table shape;
+ *   `map` receives the values and the table's rows.
+ */
+export type SentenceMapping = ((...values: SentenceArgument[]) => Readonly<Record<string, unknown>>) | {
+    readonly table?: TableSpec;
+    readonly map?: (values: readonly SentenceArgument[], rows: readonly TableRow[] | undefined) => Readonly<Record<string, unknown>>;
+    /** Fixed inputs this sentence always sets. */
+    readonly inputs?: Readonly<Record<string, unknown>>;
+};
+/** One unit of real work (docs/design.md, section 12). Counts and repeats are composition, not actions. */
+export interface ActionDefinition {
+    readonly title: string;
+    readonly description?: string;
+    /** How the action reaches the product: through its UI, the chain, root, or a backend. */
+    readonly via?: "ui" | "chain" | "chain:root" | "backend";
+    readonly inputs?: Readonly<Record<string, InputField>>;
+    /** Extra requirements for this action only (for example `devAuthority` for a root shortcut). */
+    readonly requires?: AppRequirements;
+    /** Defaults to true. Read-only actions may fail without blocking later mutations. */
+    readonly mutates?: boolean;
+    /**
+     * Backlog 160: an action that changes something records a chain and a screen reading (`reading`). One whose change
+     * the person's app does not show at all says why here (`{ none: "the app shows no balance" }`): its step then shows
+     * that reason instead of a screen check. Never for an action whose app shows what it changed.
+     */
+    readonly screenCheck?: {
+        readonly none: string;
+    };
+    /**
+     * `false`: model-based exploration (`product-lab explore`) never picks this action, for example a negative control
+     * that breaks what the lab checks on purpose. Absent: it may.
+     */
+    readonly explore?: false;
+    /**
+     * Backlog 165: this action dispatches root calls (`rootCall`), so it runs only on an environment the lab declares
+     * them for (`defineLab({ rootCalls })`). A scenario that uses it fits only those, as one tagged `@root-calls` does.
+     */
+    readonly rootCalls?: true;
+    /**
+     * Every path in run(), including delegated services and app interactions,
+     * reports a step-scoped `transaction` activity event (`report`, status
+     * `signing` or later) before anything it does can reach a chain. A report
+     * sent only to the environment activity feed does not satisfy this promise.
+     * A failure before
+     * that report submitted nothing: the run says so at once ("Nothing was
+     * sent") without asking a chain. Declare it only when it holds on every
+     * path (a UI action reports `signing` before it clicks the control that
+     * submits). Default false: after a failed mutating action without a
+     * recorded transaction the lab checks, in the background, what the chain
+     * and the host saw of the identity's account while it ran, and adds the
+     * answer to the failed run (docs/design.md, section 17). Nothing blocks.
+     */
+    readonly reportsSubmission?: boolean;
+    /** Resources the scheduler serialises, e.g. `ledger.slot`. */
+    readonly resources?: readonly string[];
+    /**
+     * Which block this action's chain waits rest on (backlog 14): `finalized` (the default) or `best`, for an
+     * intermediate action that only needs its transaction included before the scenario moves on; the checks after it
+     * confirm finality. The chains the lab gives it (`chains`) wait on that head unless a wait names another, and the
+     * step's trace and evidence record it.
+     */
+    readonly reads?: ChainHead;
+    /** The sentences `.feature` steps use for this action, mapped to its inputs (see SentenceMapping). */
+    readonly sentences?: Readonly<Record<string, SentenceMapping>> | readonly string[];
+    /**
+     * Plural sentences the framework expands with repeat, each mapped to one of
+     * this action's sentences: `"{actor} submits {count} entries in a row": "{actor} submits an entry"`.
+     */
+    readonly repeatable?: Readonly<Record<string, string>>;
+    /** Fields of run()'s result that later steps may reference (`$Ada.entry`), with their kind. */
+    readonly outputs?: Readonly<Record<string, OutputKind>>;
+    /** An action acts as an actor; one that acts as none is an EnvironmentActionDefinition (`actor: "none"`). */
+    readonly actor?: undefined;
+    run(context: ActionContext, inputs: Inputs): Promise<unknown>;
+}
+/** What an action that acts as no actor sees: no `actor`, no app surface (`ui`). */
+export type EnvironmentActionContext = Omit<ActionContext, "actor" | "ui">;
+/**
+ * An action that acts as no actor (`actor: "none"`): its sentences name none and it works on the running environment
+ * (its chains, its services), not on an identity. A feature step runs it even before the scenario has an actor: in a
+ * scenario with actors it is setup work, a setup step in a run the setup principal owns (never run as, credited to,
+ * locked as or shown in the app of a participant) and still sees none; before the first actor it runs outside a run,
+ * so it must be read-only there (`mutates: false`).
+ */
+export interface EnvironmentActionDefinition extends Omit<ActionDefinition, "actor" | "run"> {
+    readonly actor: "none";
+    run(context: EnvironmentActionContext, inputs: Inputs): Promise<unknown>;
+}
+/**
+ * An account a person's host claims a chain resource for on a product's behalf (RFC-0010): the person's statement
+ * account (`statement-store`, `//allowance//statement-store//<product id>`) or Bulletin account (`bulletin`), derived
+ * by the lab from the identity it started the host with, never read from the host or the app.
+ */
+export interface ResourceAccount {
+    /** 0x-prefixed public key. */
+    readonly account: string;
+    readonly resource: string;
+    readonly productId: string;
+}
+export interface AssertionContext {
+    readonly actor: ActorSession;
+    /** The feature execution and its role-to-identity bindings, when called from a feature. */
+    readonly scenario?: SentenceScenarioContext;
+    readonly signal: AbortSignal;
+    readonly services: IntegrationServices;
+    /** The actor's app as the run shows it (see ActionContext.ui). */
+    readonly ui?: AppSurface;
+    /** Outputs of earlier steps (feature runs). */
+    readonly outputs?: StepOutputs;
+    /**
+     * The step's table rows (a sentence ending in ":"), as a hint only: what to
+     * wait for or which surface to read (Phase 4). `observe` never compares;
+     * `compare` receives the same rows as its expected value.
+     */
+    readonly rows?: readonly TableRow[];
+    /** A live, opened connection per chain the running environment declares (see ActionContext.chains). */
+    readonly chains?: Readonly<Record<string, IntegrationChain>>;
+    /**
+     * Backlog 91: the lab's own reads of what an app stored, independent of the app and its host: `statements(chain)`
+     * (statements by topic, decoded, each proof's signer and signature checked) and `bulletin()` (bytes by content id,
+     * every block checked against it). Absent where the composition root gives none (tests, a lab compiled without one).
+     */
+    readonly readers?: ChainReaders;
+    /**
+     * A person's resource accounts, one set per app their host runs (statementReader checks a statement's signer against
+     * the `statement-store` one): the acting actor's, or with `actorName` another actor of the scenario's (by the name the
+     * feature gives it; a name the scenario does not bind is refused by name). Absent for a check that acts as no actor,
+     * and where the lab cannot derive them (no host session gives them).
+     */
+    resourceAccounts?(actorName?: string): Promise<readonly ResourceAccount[]>;
+    /**
+     * Which block this call's chain waits rest on (its definition's `reads`, default `finalized`; backlog 14).
+     */
+    readonly reads?: ChainHead;
+    /**
+     * The same view of a connection the integration owns (its own `ChainConnection`) that `chains` gives of the lab's:
+     * waits on `reads` by default, reported to this step with their head; for a check that needs finality, a wait on
+     * the best block is refused.
+     */
+    chainView?<Access extends ChainAccess>(connection: ChainConnection<Access>): ChainConnection<Access>;
+    /**
+     * What the lab knows of this actor's transactions that are not final yet (30 September 2026): those its steps
+     * reported through their step-scoped `report`, and those its app sent that the account watch saw in the pool or in a
+     * best block. `checkUiAgainstChain` in optimistic mode reads it as what may still back a screen's claim. Absent
+     * outside a feature run.
+     */
+    unsettled?(): readonly UnsettledTransaction[];
+    /**
+     * Record evidence on the step this check runs in, kept whether it passes or fails (`ScenarioContext.attach`).
+     * `checkUiAgainstChain` attaches its record here. Absent outside a run.
+     */
+    attach?(evidence: Readonly<Record<string, unknown>>): void;
+    /**
+     * Backlog 110: record what one side of this check read (a person's screen, or a chain or store the lab reads itself),
+     * with what was expected and what was found, as it is read: kept on the step whether the check passes or fails, so
+     * a failure says which side disagreed. A side the check did not read gets none. Absent outside a run.
+     */
+    reading?(reading: SideReading): void;
+}
+/**
+ * Independent observation plus comparison. Expectations reach assertions
+ * only, never actions. `observe` receives the sentence's values by kind
+ * (`actor`, `string`, … and `actor2`, `string2`, … for repeats); `compare`
+ * receives the expected value: the table's rows (the single row when its
+ * shape has `rows: "one"`), else the same values.
+ */
+export interface AssertionDefinition<Observed = unknown, Expected = unknown> {
+    readonly title: string;
+    readonly sentence?: string;
+    /** The table the sentence takes (it then ends with ":"). */
+    readonly table?: TableSpec;
+    readonly requires?: AppRequirements;
+    /**
+     * Which block this check needs (backlog 14): `finalized` (the default: chain truth) or `best` (inclusion is enough,
+     * for a check whose point is that a transaction is in a block, not that it is final). The chains the lab gives it
+     * wait on that head; a check that needs `finalized` has every wait on the best block refused, so it can never pass
+     * on a block that may still be retracted. The step's trace and evidence record it.
+     */
+    readonly reads?: ChainHead;
+    /** An assertion observes as an actor; one that observes as none is an EnvironmentAssertionDefinition (`actor: "none"`). */
+    readonly actor?: undefined;
+    observe(context: AssertionContext, args: Readonly<Record<string, string>>): Promise<Observed>;
+    compare(observed: Observed, expected: Expected): void | Promise<void>;
+}
+/** What an assertion that observes as no actor sees: no `actor`, no app surface (`ui`). */
+export type EnvironmentAssertionContext = Omit<AssertionContext, "actor" | "ui">;
+/**
+ * An assertion that observes as no actor (`actor: "none"`): its sentence names none and it checks the running
+ * environment (its chains, its services), not an identity. A feature step runs it even before the scenario has an
+ * actor; it never sees one.
+ */
+export interface EnvironmentAssertionDefinition<Observed = unknown, Expected = unknown> extends Omit<AssertionDefinition<Observed, Expected>, "actor" | "observe"> {
+    readonly actor: "none";
+    observe(context: EnvironmentAssertionContext, args: Readonly<Record<string, string>>): Promise<Observed>;
+}
+/** Every action an integration may declare: one that acts as an actor, or one that acts as none. */
+export type IntegrationAction = ActionDefinition | EnvironmentActionDefinition;
+/** Every assertion an integration may declare: one that observes as an actor, or one that observes as none. */
+export type IntegrationAssertion<Observed = unknown, Expected = unknown> = AssertionDefinition<Observed, Expected> | EnvironmentAssertionDefinition<Observed, Expected>;
+/** True when the action or assertion acts as no actor (`actor: "none"`). */
+export declare function actsAsNoActor(definition: IntegrationAction | IntegrationAssertion): definition is EnvironmentActionDefinition | EnvironmentAssertionDefinition;
+/**
+ * A data-only composite: a sentence that expands to registered sentences. It
+ * cannot contain logic or functions (a function fails `defineStepGroup`, the
+ * registry and `product-lab lint`). A step may use the group's parameters:
+ * `{actor}`, `{string}`, `{count}`, … (the group's first parameter of that
+ * kind) or `{1}`, `{2}`, … (by position); a string is written with its quotes.
+ *
+ *     defineStepGroup({
+ *       sentence: "{actor} has been flagged after skipping six entries",
+ *       steps: ["{actor} submits an entry", "{actor} opens an account", "{actor} skips 6 entries in a row"],
+ *     })
+ */
+export interface StepGroupDefinition {
+    readonly sentence: string;
+    /** Sentences run first (may be empty for a table step group). */
+    readonly steps: readonly string[];
+    /**
+     * A table step group (a sentence ending in ":", Phase 4): the table's shape, and what each row expands to: the
+     * sentences its `by` column's value names (`<column>` is the row's cell), then `then` with the row's other columns
+     * as a one-row table. Data only, like `steps`.
+     *
+     *     defineStepGroup({
+     *       sentence: "{actor} completes the following timeline:",
+     *       steps: [],
+     *       table: { columns: { step: "integer", action: ["submit", "skipEntry"], score: "text" } },
+     *       eachRow: { by: "action", sentences: { submit: ["{actor} submits an entry"], skipEntry: ["{actor} skips an entry"] }, then: "{actor}'s account is:" },
+     *     })
+     */
+    readonly table?: TableSpec;
+    readonly eachRow?: RowExpansion;
+}
+/**
+ * A browser module (Phase 5, docs/design.md section 16): a `file:` URL (`new URL("./ui/board.ts", import.meta.url)`)
+ * or a path relative to lab.config.ts. Its default export is `{ mount(element, api) }` (returning an unmount function).
+ * The lab serves it only when it imports nothing but files of its own folder, so services, signers and secrets
+ * never reach the browser. A URL rather than `() => import(...)`: the lab serves the source, never runs it in Node.
+ */
+export type UiModuleReference = string | URL;
+/** Optional UI (levels 2 and 3): an integration without it keeps the generated forms and results. */
+export interface IntegrationUi {
+    /** `<action>.<input>` → a module replacing that generated field (its value is validated like the field's). */
+    readonly inputRenderers?: Readonly<Record<string, UiModuleReference>>;
+    /** `<action>` → a read-only view over the action's result and evidence. */
+    readonly resultRenderers?: Readonly<Record<string, UiModuleReference>>;
+    /** Extra panels in the lab panel (never inside the app). */
+    readonly panels?: readonly {
+        readonly id: string;
+        readonly title: string;
+        readonly module: UiModuleReference;
+    }[];
+}
+/** What a resource reads with: its services, the identity asked for, and the lab's chains. */
+export interface ResourceContext {
+    readonly services: IntegrationServices;
+    readonly actor?: ActorSession;
+    /**
+     * The same live, opened connection per chain the running environment declares that steps get (`ActionContext.chains`),
+     * so a resource reads a chain (a balance, the finalized block) with no connection of its own. Absent without one.
+     */
+    readonly chains?: Readonly<Record<string, IntegrationChain>>;
+}
+/** Read-only data UI extensions may show (`lab.resource(id)`); services stay on the server. */
+export interface ResourceDefinition<T = unknown> {
+    readonly title?: string;
+    read(context: ResourceContext): Promise<T>;
+    /**
+     * Push change notifications instead of the panel polling `read()` (Phase 5 rest, docs/design.md section 16):
+     * for example new finalized blocks through the chain port. `notify` may be called any number of times, at any
+     * rate; each call makes the lab re-read the resource and push the (redacted) value over the panel's existing
+     * loopback server-sent-events endpoint. Returns how to stop watching (called once, when the last subscriber
+     * leaves). A resource without `watch` keeps the panel's polling fallback.
+     */
+    watch?(context: ResourceContext, notify: () => void): (() => void | Promise<void>) | Promise<() => void | Promise<void>>;
+}
+export declare function defineResource<T>(resource: ResourceDefinition<T>): ResourceDefinition<T>;
+export type { TagCondition } from "@parity/product-lab/domain";
+/** What a step of an integration's own scenario runs with: what an action gets, and the run's inputs and `attach`. */
+export type IntegrationScenarioStepContext = ActionContext & Pick<ScenarioContext, "inputs" | "attach">;
+/** A step of an integration's own scenario: a scenario step whose `run` gets an action's context (above). */
+export interface IntegrationScenarioStep extends Omit<ScenarioStep, "run"> {
+    run(context: IntegrationScenarioStepContext): Promise<unknown>;
+}
+/**
+ * A panel scenario written by hand (lane L5a, 7 October 2026, from Notes' sessions): inputs, several steps, several
+ * actors (`actors`, bound when a run starts), listed by its own id (lower-case, no dot: never an action's
+ * `<integration>.<action>`) beside its actions' one-step scenarios, under any session. Its steps are built when a run starts (`steps`, with the run's actor, actors and inputs).
+ */
+export interface IntegrationScenario extends Omit<ScenarioDefinition, "steps"> {
+    steps(context: ScenarioContext): readonly IntegrationScenarioStep[];
+}
+/** What an integration's `scenarioConditions` reads: the running environment, as its services and chains see it. */
+export interface ScenarioConditionContext {
+    /** Its environment services (and those of the integrations it depends on); a scope of its own, released after. */
+    readonly services: IntegrationServices;
+    /** A live, opened connection per chain the running environment declares (see ActionContext.chains). */
+    readonly chains?: Readonly<Record<string, IntegrationChain>>;
+    readonly signal: AbortSignal;
+    /**
+     * Whether a lab window placed this environment's people in its tiles (backlog 108; lane L5a, 7 October 2026): a host
+     * whose page runs in a tile may behave otherwise there (what it locks, what the window observes). The conditions are
+     * read again when the window places or releases them.
+     */
+    readonly placed: boolean;
+    /** The session's hosts (`LabEnvironment.hosts`): each one's kind, whether it is the default, and its options' values. */
+    readonly hosts: readonly EnvironmentHost[];
+    /**
+     * Backlog 247: probe a capability of declared host `hostId` (`LabEnvironment.probeHost`) instead of assuming it from
+     * the host's kind; undefined when the host probes nothing. Absent: the session's hosts cannot be probed.
+     */
+    readonly probeHost?: (hostId: string, request: HostProbeRequest) => Promise<HostProbe | undefined>;
+}
+export interface IntegrationDefinition {
+    /** Namespace for services, actions and assertions: `id.name`. */
+    readonly id: string;
+    /** Product identity, e.g. the DotNS label `polkadot://<label>.dot` resolves to. */
+    readonly product?: {
+        readonly label: string;
+    };
+    readonly requires?: AppRequirements;
+    /** Its sentences may run from a feature without any app using this integration (for environment checks). */
+    readonly standalone?: boolean;
+    /** Integrations whose services this one uses (their requirements are inherited). */
+    readonly dependsOn?: readonly string[];
+    readonly services?: Readonly<Record<string, ServiceDefinition<unknown, never>>>;
+    readonly actions?: Readonly<Record<string, IntegrationAction>>;
+    readonly assertions?: Readonly<Record<string, IntegrationAssertion<unknown, unknown>>>;
+    /**
+     * What must hold after every step of an exploration (`product-lab explore`, 4 October 2026): sentences of this
+     * integration's own assertions whose only parameter is `{actor}`, for example `"{actor}'s list matches the chain"`.
+     * Each is checked for every actor in scope after each step.
+     */
+    readonly invariants?: readonly string[];
+    readonly stepGroups?: readonly StepGroupDefinition[];
+    /** Its own panel scenarios (IntegrationScenario), for what one action is not: a choice of inputs, steps by several actors. */
+    readonly scenarios?: readonly IntegrationScenario[];
+    /** Domain phrasing for a registered sentence: `{ "{actor} is a new participant": "{actor} is a new actor" }` (a step group of one). */
+    readonly aliases?: Readonly<Record<string, string>>;
+    /** Phase 5: read-only resources for UI extensions, by name (`<integration>.<name>`). */
+    readonly resources?: Readonly<Record<string, ResourceDefinition<unknown>>>;
+    /** Phase 5: optional input and result renderers and panels. */
+    readonly ui?: IntegrationUi;
+    /**
+     * Scenario tags whose fit depends on the running environment, for example a tag naming a chain configuration:
+     * `[{ tag: "@mode-b", fits: false, reason: "this chain runs mode a" }]`. Read once per environment session (a start,
+     * switch or reset), after this integration's environment services started, and never while nothing runs. A
+     * scenario with a tag that does not fit is "not for this chain": the panel marks it, and a run of it is refused (or
+     * leaves it out) before anything starts, with the reason. A tag no integration names always fits; when several
+     * name one, it fits only when every one says it fits. A hook that throws leaves the conditions unknown.
+     */
+    readonly scenarioConditions?: (context: ScenarioConditionContext) => readonly TagCondition[] | Promise<readonly TagCondition[]>;
+    /**
+     * How the panel colours a table cell holding one of this integration's values, over its product-neutral defaults
+     * (yes, true, passed, ok, included: success; no, false, failed, blocked: danger; none, n/a, -, empty: neutral):
+     * `{ approved: "success", rejected: "danger" }`. Values match any case, surrounding spaces ignored; tones are
+     * `success`, `warning`, `danger` and `neutral`. A declared value overrides a default. Two integrations of one lab may
+     * not give one value different tones.
+     */
+    readonly valueTones?: ValueToneDeclaration;
+    /**
+     * The reasons this product's steps fail for on purpose (`fail(reason, message)`), by id with a description:
+     * `{ "out-of-date": "the record shown is older than the chain's" }`. `@fails-with:<id>` on a negative control may
+     * name them; `product-lab check` lists them and flags an unknown one (config redesign, 6 October 2026).
+     */
+    readonly reasons?: Readonly<Record<string, string>>;
+}
+/** @deprecated Use `defineSteps`: the same declaration under the lab's name for it (config redesign; kept until every lab moved). */
+export declare function defineIntegration<T extends IntegrationDefinition>(integration: T): T;
+/** An action: one that acts as an actor, or with `actor: "none"` one that acts as none (EnvironmentActionDefinition). */
+export declare function defineAction(action: EnvironmentActionDefinition): EnvironmentActionDefinition;
+export declare function defineAction(action: ActionDefinition): ActionDefinition;
+/** An assertion: one that observes as an actor, or with `actor: "none"` one that observes as none (EnvironmentAssertionDefinition). */
+export declare function defineAssertion<Observed, Expected>(assertion: EnvironmentAssertionDefinition<Observed, Expected>): EnvironmentAssertionDefinition<Observed, Expected>;
+export declare function defineAssertion<Observed, Expected>(assertion: AssertionDefinition<Observed, Expected>): AssertionDefinition<Observed, Expected>;
+export declare function defineStepGroup(group: StepGroupDefinition): StepGroupDefinition;
+/** Compile a sentence pattern (`{actor}`, `{string}`, `{int}`, `{count}`, `{word}`) to an anchored RegExp. */
+export declare function sentencePattern(pattern: string): RegExp;
+/** Parameter kinds a sentence pattern declares, in order. */
+export declare function sentenceParameters(pattern: string): string[];
+/** A product's steps: its sentences, actions and checks (config redesign: `lab/steps/`). The name for defineIntegration. */
+export declare const defineSteps: typeof defineIntegration;

package/core/application/src/orchestration/integrations/define.js

@@ -0,0 +1,64 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { SentencePattern, ValueTones } from "@parity/product-lab/domain";
+import { screenCheckReasonProblem } from "@parity/product-lab/domain/checks";
+export function actsAsNoActor(definition) {
+    return definition.actor === "none";
+}
+export function defineResource(resource) {
+    if (typeof resource.read !== "function")
+        throw new Error("A resource needs read()");
+    if (resource.watch !== undefined && typeof resource.watch !== "function")
+        throw new Error("A resource's watch must be a function");
+    return resource;
+}
+export function defineIntegration(integration) {
+    if (!/^[a-z][a-z0-9-]*$/.test(integration.id))
+        throw new Error(`Integration id "${integration.id}" must be lower-case letters, digits and dashes`);
+    if (integration.scenarioConditions !== undefined && typeof integration.scenarioConditions !== "function")
+        throw new Error(`Integration ${integration.id}: scenarioConditions must be a function`);
+    const scenarioIds = (integration.scenarios ?? []).map((scenario) => scenario.id);
+    for (const [index, id] of scenarioIds.entries()) {
+        if (!/^[a-z][a-z0-9-]*$/.test(id))
+            throw new Error(`Integration ${integration.id}: scenario id "${id}" must be lower-case letters, digits and dashes`);
+        if (scenarioIds.indexOf(id) !== index)
+            throw new Error(`Integration ${integration.id}: scenario id "${id}" is used twice`);
+    }
+    const toneErrors = ValueTones.errors(integration.valueTones, `Integration ${integration.id}`);
+    if (toneErrors.length)
+        throw new Error(toneErrors.join("; "));
+    return integration;
+}
+export function defineAction(action) {
+    if (typeof action.run !== "function")
+        throw new Error(`Action "${action.title}" requires run()`);
+    if (action.reads !== undefined && action.reads !== "finalized" && action.reads !== "best")
+        throw new Error(`Action "${action.title}": reads must be "finalized" or "best"`);
+    if (action.reportsSubmission !== undefined && typeof action.reportsSubmission !== "boolean")
+        throw new Error(`Action "${action.title}": reportsSubmission must be true or false`);
+    if (action.screenCheck !== undefined) {
+        const problem = screenCheckReasonProblem(action.screenCheck?.none);
+        if (problem)
+            throw new Error(`Action "${action.title}": screenCheck.none must say what the app does not show, but ${problem}`);
+    }
+    return action;
+}
+export function defineAssertion(assertion) {
+    if (assertion.reads !== undefined && assertion.reads !== "finalized" && assertion.reads !== "best")
+        throw new Error(`Assertion "${assertion.title}": reads must be "finalized" or "best"`);
+    return assertion;
+}
+export function defineStepGroup(group) {
+    const steps = group.steps;
+    const rowSentences = group.eachRow ? Object.values(group.eachRow.sentences ?? {}).flatMap((list) => (Array.isArray(list) ? list : [list])) : [];
+    if (!Array.isArray(steps) || [...steps, ...rowSentences].some((step) => typeof step !== "string") || (group.eachRow?.then !== undefined && typeof group.eachRow.then !== "string"))
+        throw new Error(`Step group "${group.sentence}" may only list sentences (strings), never functions`);
+    return group;
+}
+export function sentencePattern(pattern) {
+    return SentencePattern.parse(pattern).regex;
+}
+export function sentenceParameters(pattern) {
+    return [...SentencePattern.parse(pattern).parameters];
+}
+export const defineSteps = defineIntegration;

package/core/application/src/orchestration/integrations/generic-sentences.d.ts

@@ -0,0 +1 @@
+export { ACTIVE_APPLICATION_SENTENCE, ACTORS_EXIST_SENTENCE, ADVANCE_BLOCKS_SENTENCE, ADVANCE_TIME_SENTENCE, AT_THE_SAME_TIME_SENTENCE, GENERIC_SENTENCES, HOST_BYPASS_SENTENCE, NAVIGATION_OUTCOMES, NAVIGATION_REQUESTED_SENTENCE, NEW_ACTOR_SENTENCE, OPEN_APP_SENTENCE, TOGETHER_SENTENCE, isGenericOwner, } from "@parity/product-lab/domain/sentences";

package/core/application/src/orchestration/integrations/generic-sentences.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { ACTIVE_APPLICATION_SENTENCE, ACTORS_EXIST_SENTENCE, ADVANCE_BLOCKS_SENTENCE, ADVANCE_TIME_SENTENCE, AT_THE_SAME_TIME_SENTENCE, GENERIC_SENTENCES, HOST_BYPASS_SENTENCE, NAVIGATION_OUTCOMES, NAVIGATION_REQUESTED_SENTENCE, NEW_ACTOR_SENTENCE, OPEN_APP_SENTENCE, TOGETHER_SENTENCE, isGenericOwner, } from "@parity/product-lab/domain/sentences";

package/core/application/src/orchestration/integrations/integration-registry.d.ts

@@ -0,0 +1,53 @@
+import { mergeRequirements, type AppRequirements } from "../capabilities.js";
+import { type ServiceDefinition } from "../services/define.js";
+import type { ServiceScope } from "../services/service-container.js";
+import { SentenceBook, ValueTones, type CharacterDeclaration, type SentenceKind } from "@parity/product-lab/domain";
+import type { IntegrationAction, IntegrationAssertion, IntegrationDefinition, IntegrationServices, ResourceDefinition, SentenceMapping } from "./define.js";
+export interface RegisteredSentence {
+    pattern: string;
+    owner: string;
+    kind: SentenceKind;
+    regex: RegExp;
+}
+/**
+ * All integrations of a lab, validated and namespaced. Service ids become
+ * `integration.service`; a dependency name without a dot is local to the
+ * integration, a dotted name must point to the integration itself or one it
+ * lists in `dependsOn`.
+ */
+export declare class IntegrationRegistry {
+    #private;
+    readonly integrations: ReadonlyMap<string, IntegrationDefinition>;
+    readonly services: Readonly<Record<string, ServiceDefinition<unknown, never>>>;
+    readonly actions: ReadonlyMap<string, {
+        integration: string;
+        action: IntegrationAction;
+    }>;
+    readonly assertions: ReadonlyMap<string, {
+        integration: string;
+        assertion: IntegrationAssertion<unknown, unknown>;
+    }>;
+    readonly sentences: readonly RegisteredSentence[];
+    /** The sentence registry (Phase 4): the framework's generic sentences and every integration's. */
+    readonly book: SentenceBook;
+    /** Each action sentence's mapping to its action's inputs, by pattern. */
+    readonly mappings: ReadonlyMap<string, SentenceMapping>;
+    readonly errors: readonly string[];
+    /** Phase 5: published resources by `<integration>.<name>`. */
+    readonly resources: ReadonlyMap<string, {
+        integration: string;
+        resource: ResourceDefinition<unknown>;
+    }>;
+    /** Every integration's declared value tones, merged (the panel colours table cells with them). */
+    readonly valueTones: ValueTones;
+    /** `characters`: the lab's reusable characters (backlog 35), each a step group `{actor} is <name>` of the lab. */
+    constructor(integrations: readonly IntegrationDefinition[], characters?: Readonly<Record<string, CharacterDeclaration>>);
+    /** Map a dependency name declared by service `from` to a qualified service id. */
+    resolveService: (from: string, name: string) => string;
+    /** Requirements of an integration including every integration it depends on (transitively). */
+    requirements(integrationId: string, extra?: AppRequirements): ReturnType<typeof mergeRequirements>;
+    /** Integration ids a set of integrations needs, dependencies first. */
+    closure(ids: readonly string[]): string[];
+    /** Services visible to an integration, by short name or `integration.service`. */
+    view(integrationId: string, scope: ServiceScope): IntegrationServices;
+}