@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/application/src/orchestration/integrations/integration-registry.js

@@ -0,0 +1,261 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { mergeRequirements, requirementErrors } from "../capabilities.js";
+import { serviceGraphErrors } from "../services/define.js";
+import { SentenceBook, SentencePattern, ValueTones, characterOwner, characterSentence, charactersDeclarationProblems } from "@parity/product-lab/domain";
+import { GENERIC_SENTENCES } from "./generic-sentences.js";
+export class IntegrationRegistry {
+    integrations;
+    services;
+    actions;
+    assertions;
+    sentences;
+    book;
+    mappings;
+    errors;
+    resources;
+    valueTones;
+    constructor(integrations, characters) {
+        const errors = [];
+        const byId = new Map();
+        for (const integration of integrations) {
+            const existing = byId.get(integration.id);
+            if (existing && existing !== integration)
+                errors.push(`Two different integrations use the id "${integration.id}"`);
+            byId.set(integration.id, integration);
+        }
+        this.integrations = byId;
+        for (const integration of byId.values()) {
+            if (!/^[a-z][a-z0-9-]*$/.test(integration.id))
+                errors.push(`Integration id "${integration.id}" must be lower-case letters, digits and dashes`);
+            errors.push(...requirementErrors(integration.requires, `Integration ${integration.id}`));
+            for (const dependency of integration.dependsOn ?? [])
+                if (!byId.has(dependency))
+                    errors.push(`Integration ${integration.id} depends on ${dependency}, which is not registered by any app`);
+        }
+        errors.push(...integrationCycles(byId));
+        const services = {};
+        const actions = new Map();
+        const assertions = new Map();
+        for (const integration of byId.values()) {
+            for (const [name, service] of Object.entries(integration.services ?? {}))
+                services[`${integration.id}.${name}`] = service;
+            for (const [name, action] of Object.entries(integration.actions ?? {})) {
+                actions.set(`${integration.id}.${name}`, { integration: integration.id, action });
+                errors.push(...requirementErrors(action.requires, `Action ${integration.id}.${name}`));
+            }
+            for (const [name, assertion] of Object.entries(integration.assertions ?? {}))
+                assertions.set(`${integration.id}.${name}`, { integration: integration.id, assertion });
+        }
+        const scenarioOwners = new Map();
+        for (const integration of byId.values())
+            for (const scenario of integration.scenarios ?? []) {
+                const owner = scenarioOwners.get(scenario.id);
+                if (owner && owner !== integration.id)
+                    errors.push(`Scenario "${scenario.id}" is declared by integrations ${owner} and ${integration.id}`);
+                scenarioOwners.set(scenario.id, integration.id);
+            }
+        this.services = services;
+        this.actions = actions;
+        this.assertions = assertions;
+        const resources = new Map();
+        for (const integration of byId.values()) {
+            for (const [name, resource] of Object.entries(integration.resources ?? {})) {
+                if (!resource || typeof resource.read !== "function")
+                    errors.push(`Resource ${integration.id}.${name} needs read()`);
+                else
+                    resources.set(`${integration.id}.${name}`, { integration: integration.id, resource });
+            }
+            errors.push(...uiErrors(integration));
+            if (integration.scenarioConditions !== undefined && typeof integration.scenarioConditions !== "function")
+                errors.push(`Integration ${integration.id}: scenarioConditions must be a function`);
+        }
+        this.resources = resources;
+        const tones = ValueTones.merge([...byId.values()].map((integration) => ({ owner: `Integration ${integration.id}`, tones: integration.valueTones })));
+        this.valueTones = tones.tones;
+        errors.push(...tones.errors);
+        errors.push(...this.#serviceReferenceErrors());
+        errors.push(...serviceGraphErrors(services, this.resolveService));
+        const declarations = [...GENERIC_SENTENCES];
+        const mappings = new Map();
+        for (const [id, { action }] of actions) {
+            const entries = Array.isArray(action.sentences)
+                ? action.sentences.map((pattern) => [pattern, {}])
+                : Object.entries((action.sentences ?? {}));
+            for (const [pattern, mapping] of entries) {
+                errors.push(...mappingErrors(id, action, pattern, mapping));
+                const table = typeof mapping === "object" && mapping ? mapping.table : undefined;
+                declarations.push({ pattern, owner: id, kind: "action", ...(table ? { table } : {}), ...(action.outputs ? { outputs: action.outputs } : {}) });
+                mappings.set(pattern, mapping);
+            }
+            for (const [plural, singular] of Object.entries(action.repeatable ?? {}))
+                declarations.push({ pattern: plural, owner: id, kind: "repeatable", repeats: singular });
+        }
+        for (const [id, { assertion }] of assertions) {
+            if (assertion.sentence)
+                declarations.push({ pattern: assertion.sentence, owner: id, kind: "assertion", ...(assertion.table ? { table: assertion.table } : {}) });
+        }
+        for (const integration of byId.values()) {
+            for (const [index, group] of (integration.stepGroups ?? []).entries())
+                declarations.push({
+                    pattern: group.sentence,
+                    owner: `${integration.id}.stepGroups[${index}]`,
+                    kind: "step-group",
+                    steps: group.steps,
+                    ...(group.table ? { table: group.table } : {}),
+                    ...(group.eachRow ? { eachRow: group.eachRow } : {}),
+                });
+            for (const [alias, target] of Object.entries(integration.aliases ?? {}))
+                declarations.push({ pattern: alias, owner: `${integration.id}.aliases["${alias}"]`, kind: "step-group", steps: [target] });
+        }
+        for (const [name, character] of Object.entries(characters ?? {}))
+            if (!charactersDeclarationProblems({ [name]: character }).length)
+                declarations.push({ pattern: characterSentence(name), owner: characterOwner(name), kind: "step-group", steps: character.steps });
+        this.book = new SentenceBook(declarations);
+        errors.push(...this.book.errors);
+        for (const entry of this.book.entries) {
+            const definition = entry.kind === "action" ? actions.get(entry.owner)?.action : entry.kind === "assertion" ? assertions.get(entry.owner)?.assertion : undefined;
+            if (definition?.actor === "none" && entry.pattern.parameters.includes("actor"))
+                errors.push(`${entry.kind === "action" ? "Action" : "Assertion"} ${entry.owner} acts as no actor (actor: "none"), but its sentence "${entry.pattern.text}" names an {actor}`);
+        }
+        this.mappings = mappings;
+        this.sentences = this.book.entries.map((entry) => ({ pattern: entry.pattern.text, owner: entry.owner, kind: entry.kind, regex: entry.pattern.regex }));
+        this.errors = errors;
+    }
+    resolveService = (from, name) => {
+        const integration = from.slice(0, from.indexOf("."));
+        return name.includes(".") ? name : `${integration}.${name}`;
+    };
+    #serviceReferenceErrors() {
+        const errors = [];
+        for (const [id, service] of Object.entries(this.services)) {
+            const integration = id.slice(0, id.indexOf("."));
+            const allowed = new Set([integration, ...(this.integrations.get(integration)?.dependsOn ?? [])]);
+            for (const name of service.dependsOn ?? []) {
+                const target = this.resolveService(id, name);
+                const owner = target.slice(0, target.indexOf("."));
+                if (!allowed.has(owner))
+                    errors.push(`Service ${id} uses ${target}, but integration ${integration} does not list ${owner} in dependsOn`);
+            }
+        }
+        return errors;
+    }
+    requirements(integrationId, extra) {
+        const seen = new Set();
+        const collect = (id) => {
+            if (seen.has(id))
+                return [];
+            seen.add(id);
+            const integration = this.integrations.get(id);
+            return [integration?.requires, ...(integration?.dependsOn ?? []).flatMap(collect)];
+        };
+        return mergeRequirements(extra, ...collect(integrationId));
+    }
+    closure(ids) {
+        const result = [];
+        const visit = (id) => {
+            if (result.includes(id) || !this.integrations.has(id))
+                return;
+            for (const dependency of this.integrations.get(id).dependsOn ?? [])
+                visit(dependency);
+            result.push(id);
+        };
+        ids.forEach(visit);
+        return result;
+    }
+    view(integrationId, scope) {
+        const allowed = new Set([integrationId, ...(this.integrations.get(integrationId)?.dependsOn ?? [])]);
+        return {
+            get: (name) => {
+                const id = name.includes(".") ? name : `${integrationId}.${name}`;
+                const owner = id.slice(0, id.indexOf("."));
+                if (!allowed.has(owner))
+                    return Promise.reject(new Error(`Integration ${integrationId} cannot use ${id}: add ${owner} to its dependsOn`));
+                return scope.get(id);
+            },
+        };
+    }
+}
+function integrationCycles(integrations) {
+    const errors = [];
+    const state = new Map();
+    const visit = (id, path) => {
+        if (state.get(id) === "done")
+            return;
+        if (state.get(id) === "visiting") {
+            errors.push(`Integration dependency cycle: ${[...path.slice(path.indexOf(id)), id].join(" -> ")}`);
+            return;
+        }
+        state.set(id, "visiting");
+        for (const dependency of integrations.get(id)?.dependsOn ?? [])
+            if (integrations.has(dependency))
+                visit(dependency, [...path, id]);
+        state.set(id, "done");
+    };
+    for (const id of integrations.keys())
+        visit(id, []);
+    return errors;
+}
+const isModule = (value) => (typeof value === "string" && value.trim() !== "") || value instanceof URL;
+function uiErrors(integration) {
+    const ui = integration.ui;
+    if (!ui)
+        return [];
+    const errors = [];
+    const actions = integration.actions ?? {};
+    for (const [key, module] of Object.entries(ui.inputRenderers ?? {})) {
+        const [action, input, extra] = key.split(".");
+        if (extra !== undefined || !action || !input || !actions[action]?.inputs?.[input])
+            errors.push(`Integration ${integration.id}: input renderer "${key}" names no input (use <action>.<input> of one of its actions)`);
+        if (!isModule(module))
+            errors.push(`Integration ${integration.id}: input renderer "${key}" needs a module (a file: URL or a path)`);
+    }
+    for (const [key, module] of Object.entries(ui.resultRenderers ?? {})) {
+        if (!actions[key])
+            errors.push(`Integration ${integration.id}: result renderer "${key}" names no action`);
+        if (!isModule(module))
+            errors.push(`Integration ${integration.id}: result renderer "${key}" needs a module (a file: URL or a path)`);
+    }
+    const ids = new Set();
+    for (const panel of ui.panels ?? []) {
+        if (!panel || !/^[a-z][a-z0-9-]*$/.test(panel.id ?? ""))
+            errors.push(`Integration ${integration.id}: a panel id must be lower-case letters, digits and dashes`);
+        else if (ids.has(panel.id))
+            errors.push(`Integration ${integration.id}: two panels use the id ${panel.id}`);
+        else
+            ids.add(panel.id);
+        if (!panel?.title)
+            errors.push(`Integration ${integration.id}: panel ${panel?.id ?? "?"} needs a title`);
+        if (!isModule(panel?.module))
+            errors.push(`Integration ${integration.id}: panel ${panel?.id ?? "?"} needs a module (a file: URL or a path)`);
+    }
+    return errors;
+}
+const MAPPING_KEYS = new Set(["table", "map", "inputs"]);
+function mappingErrors(owner, action, pattern, mapping) {
+    if (typeof mapping === "function")
+        return [];
+    if (!mapping || typeof mapping !== "object")
+        return [`Action ${owner}: sentence "${pattern}" maps to ${String(mapping)}; use {}, a function or { table, map, inputs }`];
+    const errors = Object.keys(mapping)
+        .filter((key) => !MAPPING_KEYS.has(key))
+        .map((key) => `Action ${owner}: sentence "${pattern}" has an unknown mapping key ${key} (table, map, inputs)`);
+    if (mapping.map !== undefined && typeof mapping.map !== "function")
+        errors.push(`Action ${owner}: sentence "${pattern}": map must be a function`);
+    let parameters;
+    try {
+        parameters = SentencePattern.parse(pattern).parameters;
+    }
+    catch {
+        return errors;
+    }
+    if (pattern.endsWith(":") && !mapping.map)
+        errors.push(`Action ${owner}: sentence "${pattern}" takes a table, so it needs map(values, rows)`);
+    if (!mapping.map) {
+        const values = parameters.length - (parameters.includes("actor") ? 1 : 0);
+        const inputs = Object.keys(action.inputs ?? {}).filter((name) => !Object.hasOwn(mapping.inputs ?? {}, name));
+        if (values > inputs.length)
+            errors.push(`Action ${owner}: sentence "${pattern}" has ${values} value(s) for ${inputs.length} input(s); declare the inputs or map them`);
+    }
+    return errors;
+}

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

@@ -0,0 +1,17 @@
+import type { ChainReaders } from "@parity/product-lab/ports/chain";
+import type { ServiceScope } from "../services/service-container.js";
+import type { ScenarioContext, ScenarioDefinition } from "../types.js";
+import type { ActionContext, IntegrationChain, IntegrationServices, ResourceAccount } from "./define.js";
+import type { IntegrationRegistry } from "./integration-registry.js";
+export interface ScenarioActionDeps {
+    /** A service scope for one run (`id` names it), released with the run's. */
+    scope(actorId: string, id: string): ServiceScope;
+    chains(): Readonly<Record<string, IntegrationChain>> | undefined;
+    readers(): ChainReaders | undefined;
+    /** The resource accounts the lab derives for a person, by actor id; absent where it derives none. */
+    readonly resourceAccounts?: (actorId: string) => Promise<readonly ResourceAccount[]>;
+}
+/** What a scenario step's action-like work runs with (see above), for the scenario `id`. */
+export declare function scenarioActionContext(step: ScenarioContext, services: IntegrationServices, deps: ScenarioActionDeps, id: string): ActionContext;
+/** Each available integration's own scenarios, as the panel lists them (by their own ids). */
+export declare function integrationScenarios(registry: IntegrationRegistry, available: ReadonlySet<string>, deps: ScenarioActionDeps): ScenarioDefinition[];

package/core/application/src/orchestration/integrations/integration-scenarios.js

@@ -0,0 +1,48 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readingRecorder, writeRecorder } from "@parity/product-lab/domain/checks";
+function bound(step, role, asking) {
+    const actor = step.actors?.[role];
+    if (!actor)
+        throw new Error(`${asking}: the scenario binds no actor "${role}"${step.actors ? ` (it binds ${Object.keys(step.actors).join(", ")})` : ""}`);
+    return actor;
+}
+export function scenarioActionContext(step, services, deps, id) {
+    const chains = deps.chains();
+    const readers = deps.readers();
+    const derive = deps.resourceAccounts;
+    const scenario = step.actors
+        ? { id, signal: step.signal, actor: (role) => bound(step, role, `"${role}"`), actors: () => step.actors }
+        : undefined;
+    return {
+        actor: step.actor,
+        signal: step.signal,
+        progress: step.progress,
+        report: step.report,
+        services,
+        reading: readingRecorder(step.attach),
+        write: writeRecorder(step.attach),
+        ...(step.ui ? { ui: step.ui } : {}),
+        ...(scenario ? { scenario } : {}),
+        ...(chains ? { chains } : {}),
+        ...(readers ? { readers } : {}),
+        ...(derive ? { resourceAccounts: (actorName) => derive(actorName === undefined ? step.actor.id : bound(step, actorName, `resourceAccounts("${actorName}")`).id) } : {}),
+    };
+}
+export function integrationScenarios(registry, available, deps) {
+    return [...registry.integrations.values()]
+        .filter((integration) => available.has(integration.id))
+        .flatMap((integration) => (integration.scenarios ?? []).map((scenario) => {
+        const id = scenario.id;
+        return {
+            ...scenario,
+            steps: (context) => {
+                const services = registry.view(integration.id, deps.scope(context.actor.id, id));
+                return scenario.steps(context).map((step) => ({
+                    ...step,
+                    run: (stepContext) => step.run({ ...scenarioActionContext(stepContext, services, deps, id), inputs: stepContext.inputs, attach: stepContext.attach }),
+                }));
+            },
+        };
+    }));
+}

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

@@ -0,0 +1,78 @@
+import type { AtomicCall, ParameterKind, PublicTimeouts } from "@parity/product-lab/domain";
+import type { ActionDefinition } from "./define.js";
+import type { ActorlessCallContext, Inputs, LabSentences, SentenceAction, SentenceArgument, SentenceCallContext, SentenceInvariant, SentenceScenarioContext, SentenceScenarioScope } from "@parity/product-lab/ports/lab";
+import type { ServiceScope, ScenarioServiceScope } from "../services/service-container.js";
+import type { IntegrationChain, ResourceAccount } from "./define.js";
+import type { HostSession } from "@parity/product-lab/ports/host";
+import type { ChainHead } from "../chain/chain-connection.js";
+import type { ChainReaders } from "@parity/product-lab/ports/chain";
+import type { IntegrationRegistry } from "./integration-registry.js";
+import type { ActionRootCall } from "../lab/root-call-access.js";
+export interface IntegrationSentencesOptions {
+    /** The service scope one call uses (scenario services are fresh per call); no actor for a call that acts as none. */
+    scope(actorId: string | undefined, owner: string): ServiceScope;
+    /** Explicit feature scopes stay outside legacy afterRun cleanup. */
+    scenario?(context: SentenceScenarioContext): ScenarioServiceScope;
+    /** Why an integration action or assertion cannot run in this environment. */
+    unavailable(owner: string): string | undefined;
+    /** A live connection per chain the running environment declares, given to every action and assertion (ActionContext.chains/AssertionContext.chains). */
+    chains?: Readonly<Record<string, IntegrationChain>>;
+    /** Backlog 91: the lab's own readers of what apps stored, given to every action and assertion (their `readers`). */
+    readers?: ChainReaders;
+    /** The resource accounts the lab derives for a person (ActionContext and AssertionContext.resourceAccounts), by actor id. */
+    resourceAccounts?(actorId: string): Promise<readonly ResourceAccount[]>;
+    /** On a public network (backlog A6): the finality-sized waits every call's chain views get (read at each call). */
+    publicWaits?(): PublicTimeouts | undefined;
+    /** Root calls, when the lab declares them for this environment: given to actions only (ActionContext.rootCall). */
+    rootCall?: ActionRootCall;
+}
+/** An assertion's values by kind: `actor`, `string`, … then `actor2`, `string2`, … */
+export declare function namedArguments(kinds: readonly ParameterKind[], args: readonly SentenceArgument[]): Record<string, string>;
+export declare class IntegrationSentences implements LabSentences {
+    private readonly registry;
+    private readonly options;
+    private readonly scenario?;
+    constructor(registry: IntegrationRegistry, options: IntegrationSentencesOptions, scenario?: SentenceScenarioContext | undefined);
+    openScenario(context: SentenceScenarioContext): SentenceScenarioScope;
+    get book(): import("@parity/product-lab/domain").SentenceBook;
+    unavailable(owner: string): string | undefined;
+    reads(owner: string): ChainHead;
+    /**
+     * What one call sees of the chains (backlog 14): views of the lab's connections, and `chainView` for a connection the
+     * integration owns, that wait on the call's declared head by default, report their waits (with the head) to the
+     * call's step, and, for a check that needs finality, refuse a wait on the best block.
+     */
+    private chainsFor;
+    actorless(owner: string): boolean;
+    action(owner: string): SentenceAction | undefined;
+    invariants(): readonly SentenceInvariant[];
+    parameterInputs(pattern: string): readonly (string | undefined)[] | undefined;
+    inputs(call: AtomicCall, args: readonly SentenceArgument[]): Record<string, unknown>;
+    /**
+     * Which of an action call's arguments fill a free-text input (backlog A7): only those may carry a run's token on a
+     * public network. Found through the sentence's own mapping, each string argument replaced by a marker: one that
+     * lands unchanged in a `text` input counts; a choice, a number, a boolean or a value the mapping transforms does not.
+     */
+    textArguments(call: AtomicCall, args: readonly SentenceArgument[]): ReadonlySet<number>;
+    act(call: AtomicCall, inputs: Inputs, context: SentenceCallContext | ActorlessCallContext): Promise<unknown>;
+    check(call: AtomicCall, args: readonly SentenceArgument[], context: SentenceCallContext | ActorlessCallContext): Promise<unknown>;
+    /**
+     * A call's `resourceAccounts`: the acting actor's, or a named actor's of the scenario (resolved as its steps resolve
+     * one, so a name the scenario does not bind is refused by name). None where the lab derives none.
+     */
+    private resourceAccounts;
+}
+/**
+ * Backlog 160-161: what an action's step keeps, wherever it runs (a feature step, a panel action scenario): what it read
+ * back of its effect (`reading`), what it wrote besides the lab's transactions (`write`), and, for an action whose
+ * change no screen shows, its declared reason (attached at once).
+ */
+export declare function actionStepTools(action: Pick<ActionDefinition, "screenCheck">, attach: (evidence: Readonly<Record<string, unknown>>) => void): {
+    reading: (reading: import("@parity/product-lab/domain").SideReading) => void;
+    write: (write: import("@parity/product-lab/domain").StepWrite) => void;
+};
+/**
+ * A person's resource accounts (AssertionContext.resourceAccounts, the lab's statementReader): what each of their host
+ * sessions derives from the identity the lab started that host with, one set per app, with the app's product id.
+ */
+export declare function resourceAccountsOf(hostSessions: (() => Promise<readonly HostSession[]>) | undefined, actorId: string): Promise<readonly ResourceAccount[]>;

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

@@ -0,0 +1,214 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { readingRecorder, SCREEN_CHECK_KEY, writeRecorder } from "@parity/product-lab/domain/checks";
+export function namedArguments(kinds, args) {
+    const counts = new Map();
+    return Object.fromEntries(kinds.map((kind, index) => {
+        const n = (counts.get(kind) ?? 0) + 1;
+        counts.set(kind, n);
+        return [n === 1 ? kind : `${kind}${n}`, String(args[index])];
+    }));
+}
+export class IntegrationSentences {
+    registry;
+    options;
+    scenario;
+    constructor(registry, options, scenario) {
+        this.registry = registry;
+        this.options = options;
+        this.scenario = scenario;
+    }
+    openScenario(context) {
+        if (!this.options.scenario)
+            throw new Error("This sentence catalogue cannot open a running scenario");
+        const owner = this.options.scenario(context);
+        const calls = new IntegrationSentences(this.registry, {
+            ...this.options,
+            scope: (actor) => (actor === undefined ? owner : owner.forActor(actor)),
+        }, context);
+        return {
+            act: (call, inputs, callContext) => calls.act(call, inputs, callContext),
+            check: (call, args, callContext) => calls.check(call, args, callContext),
+            close: () => owner.dispose(),
+        };
+    }
+    get book() {
+        return this.registry.book;
+    }
+    unavailable(owner) {
+        if (!this.registry.actions.has(owner) && !this.registry.assertions.has(owner))
+            return `${owner} is not an action or assertion of this lab`;
+        return this.options.unavailable(owner);
+    }
+    reads(owner) {
+        const definition = this.registry.actions.get(owner)?.action ?? this.registry.assertions.get(owner)?.assertion;
+        return definition?.reads ?? "finalized";
+    }
+    chainsFor(title, reads, check, report) {
+        const requiresFinality = check && reads === "finalized" ? `"${title}" needs a finalized block (reads: "finalized")` : undefined;
+        const publicWaits = this.options.publicWaits?.();
+        const options = { head: reads, ...(requiresFinality ? { requiresFinality } : {}), activity: report, ...(publicWaits ? { publicWaits } : {}) };
+        const chainView = (connection) => connection.view(options);
+        const chains = this.options.chains;
+        return {
+            reads,
+            chainView,
+            ...(chains ? { chains: Object.fromEntries(Object.entries(chains).map(([id, chain]) => [id, chainView(chain)])) } : {}),
+        };
+    }
+    actorless(owner) {
+        const definition = this.registry.actions.get(owner)?.action ?? this.registry.assertions.get(owner)?.assertion;
+        return definition?.actor === "none";
+    }
+    action(owner) {
+        const found = this.registry.actions.get(owner);
+        if (!found)
+            return undefined;
+        const { action } = found;
+        return {
+            title: action.title,
+            inputs: { ...(action.inputs ?? {}) },
+            mutates: action.mutates !== false,
+            ...(action.reportsSubmission ? { reportsSubmission: true } : {}),
+            resources: [...(action.resources ?? [])],
+            ...(action.explore === false ? { explore: false } : {}),
+        };
+    }
+    invariants() {
+        return [...this.registry.integrations.values()].flatMap((integration) => (integration.invariants ?? []).map((pattern) => {
+            const entry = this.registry.book.entries.find((item) => item.pattern.text === pattern);
+            if (!entry || entry.kind !== "assertion" || !entry.owner.startsWith(`${integration.id}.`))
+                throw new Error(`Integration ${integration.id}'s invariant "${pattern}" is not one of its assertion sentences`);
+            if (entry.pattern.parameters.length !== 1 || entry.pattern.parameters[0] !== "actor")
+                throw new Error(`Integration ${integration.id}'s invariant "${pattern}" must take {actor} and nothing else (it is checked for every actor in scope)`);
+            return { integration: integration.id, pattern };
+        }));
+    }
+    parameterInputs(pattern) {
+        const entry = this.registry.book.entries.find((item) => item.pattern.text === pattern);
+        const found = entry ? this.registry.actions.get(entry.owner) : undefined;
+        if (!entry || !found)
+            return undefined;
+        const mapping = this.registry.mappings.get(pattern) ?? {};
+        if (typeof mapping === "function" || mapping.map)
+            return undefined;
+        const fixed = mapping.inputs ?? {};
+        const names = Object.keys(found.action.inputs ?? {}).filter((name) => !Object.hasOwn(fixed, name));
+        const actor = entry.pattern.parameters.indexOf("actor");
+        let next = 0;
+        return entry.pattern.parameters.map((_, index) => (index === actor ? undefined : names[next++]));
+    }
+    inputs(call, args) {
+        const found = this.registry.actions.get(call.entry.owner);
+        if (!found)
+            throw new Error(`${call.entry.owner} is not an action`);
+        const mapping = this.registry.mappings.get(call.entry.pattern.text) ?? {};
+        if (typeof mapping === "function")
+            return { ...mapping(...args) };
+        const fixed = mapping.inputs ?? {};
+        if (mapping.map)
+            return { ...fixed, ...mapping.map(args, call.rows) };
+        const actor = call.entry.pattern.parameters.indexOf("actor");
+        const names = Object.keys(found.action.inputs ?? {}).filter((name) => !Object.hasOwn(fixed, name));
+        const values = args.filter((_, index) => index !== actor);
+        return { ...fixed, ...Object.fromEntries(values.map((value, index) => [names[index], value])) };
+    }
+    textArguments(call, args) {
+        const found = this.registry.actions.get(call.entry.owner);
+        if (!found)
+            return new Set();
+        const marker = (index) => `\u0000argument ${index}\u0000`;
+        const mapped = this.inputs(call, args.map((arg, index) => (typeof arg === "string" ? marker(index) : arg)));
+        const fields = found.action.inputs ?? {};
+        const text = new Set();
+        args.forEach((arg, index) => {
+            if (typeof arg !== "string")
+                return;
+            const key = Object.keys(mapped).find((name) => mapped[name] === marker(index));
+            if (key !== undefined && fields[key]?.type === "text")
+                text.add(index);
+        });
+        return text;
+    }
+    act(call, inputs, context) {
+        const found = this.registry.actions.get(call.entry.owner);
+        if (!found)
+            throw new Error(`${call.entry.owner} is not an action`);
+        const { action } = found;
+        const chains = this.chainsFor(action.title, action.reads ?? "finalized", false, context.report);
+        const shared = (actorId) => ({
+            ...(this.scenario ? { scenario: this.scenario } : {}),
+            signal: context.signal,
+            progress: context.progress,
+            report: context.report,
+            services: this.registry.view(found.integration, this.options.scope(actorId, call.entry.owner)),
+            outputs: context.outputs,
+            ...(context.attach ? actionStepTools(action, context.attach) : {}),
+            ...chains,
+            ...(this.options.rootCall ? { rootCall: this.options.rootCall } : {}),
+            ...(this.options.readers ? { readers: this.options.readers } : {}),
+        });
+        if (action.actor === "none")
+            return action.run(shared(undefined), inputs);
+        const { actor, ui } = acting(call, context);
+        return action.run({ ...shared(actor.id), actor, ...(ui ? { ui } : {}), ...this.resourceAccounts(actor) }, inputs);
+    }
+    async check(call, args, context) {
+        const found = this.registry.assertions.get(call.entry.owner);
+        if (!found)
+            throw new Error(`${call.entry.owner} is not an assertion`);
+        const { assertion } = found;
+        const named = namedArguments(call.entry.pattern.parameters, args);
+        const chains = this.chainsFor(assertion.title, assertion.reads ?? "finalized", true, context.report);
+        const shared = (actorId) => ({
+            ...(this.scenario ? { scenario: this.scenario } : {}),
+            signal: context.signal,
+            services: this.registry.view(found.integration, this.options.scope(actorId, call.entry.owner)),
+            outputs: context.outputs,
+            ...(call.rows ? { rows: call.rows } : {}),
+            ...(context.attach ? { attach: context.attach, reading: readingRecorder(context.attach) } : {}),
+            ...(this.options.readers ? { readers: this.options.readers } : {}),
+            ...chains,
+        });
+        let observed;
+        if (assertion.actor === "none")
+            observed = await assertion.observe(shared(undefined), named);
+        else {
+            const { actor, ui, unsettled } = acting(call, context);
+            observed = await assertion.observe({ ...shared(actor.id), actor, ...(ui ? { ui } : {}), ...(unsettled ? { unsettled } : {}), ...this.resourceAccounts(actor) }, named);
+        }
+        const table = call.entry.table;
+        const expected = table ? (table.rows === "one" ? call.rows[0] : call.rows) : named;
+        await found.assertion.compare(observed, expected);
+        return observed;
+    }
+    resourceAccounts(actor) {
+        const derive = this.options.resourceAccounts;
+        if (!derive)
+            return {};
+        return {
+            resourceAccounts: async (actorName) => {
+                if (actorName === undefined)
+                    return derive(actor.id);
+                if (!this.scenario)
+                    throw new Error(`resourceAccounts("${actorName}"): this call runs outside a feature scenario, so it has no other actor to name`);
+                return derive(this.scenario.actor(actorName).id);
+            },
+        };
+    }
+}
+function acting(call, context) {
+    if (!("actor" in context))
+        throw new Error(`"${call.text}" (${call.entry.owner}) acts as an actor, and the scenario has none yet`);
+    return context;
+}
+export function actionStepTools(action, attach) {
+    if (action.screenCheck)
+        attach({ [SCREEN_CHECK_KEY]: { ...action.screenCheck } });
+    return { reading: readingRecorder(attach), write: writeRecorder(attach) };
+}
+export async function resourceAccountsOf(hostSessions, actorId) {
+    const sessions = ((await hostSessions?.()) ?? []).filter((session) => session.actor.id === actorId && session.resourceAccounts);
+    const accounts = await Promise.all(sessions.map(async (session) => (await session.resourceAccounts()).map(({ account, resource }) => ({ account, resource, productId: session.app.productId }))));
+    return accounts.flat();
+}

package/core/application/src/orchestration/integrations/known-submission-error.d.ts

@@ -0,0 +1,16 @@
+import type { SubmissionOutcome } from "@parity/product-lab/ports/driving";
+/** What a failed action knows of its submission: an outcome the run record already uses, and a sentence for people. */
+export interface DeclaredSubmission {
+    readonly outcome: SubmissionOutcome;
+    readonly detail?: string;
+}
+/** Thrown by an action that failed after submitting and knows what became of the submission. */
+export declare class KnownSubmissionError extends Error {
+    readonly submission: DeclaredSubmission;
+    constructor(message: string, submission: DeclaredSubmission, options?: ErrorOptions);
+}
+/**
+ * The submission a failure declares: its own `submission` field, else its causes' (an error wrapped on the way to the
+ * run keeps it). Any error with a valid `submission` counts, not only a KnownSubmissionError.
+ */
+export declare function declaredSubmission(error: unknown): DeclaredSubmission | undefined;

package/core/application/src/orchestration/integrations/known-submission-error.js

@@ -0,0 +1,22 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const OUTCOMES = ["included", "not-included", "not-submitted", "unknown"];
+export class KnownSubmissionError extends Error {
+    submission;
+    constructor(message, submission, options) {
+        super(message, options);
+        this.submission = submission;
+        this.name = "KnownSubmissionError";
+    }
+}
+export function declaredSubmission(error) {
+    for (let current = error, depth = 0; current && typeof current === "object" && depth < 8; current = current.cause, depth++) {
+        const submission = current.submission;
+        if (!submission || typeof submission !== "object")
+            continue;
+        const { outcome, detail } = submission;
+        if (typeof outcome === "string" && OUTCOMES.includes(outcome))
+            return { outcome: outcome, ...(typeof detail === "string" && detail ? { detail } : {}) };
+    }
+    return undefined;
+}