@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/domain/src/releases/index.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { compareVersions, entriesBetween, headline, isVersion, parseChangelog, releaseChannel, releaseNoticeLines, } from "./release-notes.js";

package/core/domain/src/releases/release-notes.d.ts

@@ -0,0 +1,49 @@
+/** One version's entry in a changesets `CHANGELOG.md`. */
+export interface ReleaseEntry {
+    readonly version: string;
+    /** "Major Changes": what may need a change in the consumer's repository. */
+    readonly breaking: readonly string[];
+    /** "Minor Changes" and "Patch Changes" (and any other section), in the file's order. */
+    readonly changes: readonly string[];
+}
+/** What changed since the version a repository last used, and whether a newer version is published. */
+export interface ReleaseNotice {
+    readonly package: string;
+    /** The installed version. */
+    readonly version: string;
+    /** Present on the first use after an upgrade: the entries after `from` up to the installed version, newest first. */
+    readonly whatsNew?: {
+        readonly from: string;
+        readonly entries: readonly ReleaseEntry[];
+        readonly notes: string;
+    };
+    /** Present when the registry's dist-tag for this version's channel names a newer version. */
+    readonly available?: {
+        readonly version: string;
+        readonly tag: string;
+    };
+    /** The command that upgrades the package and refreshes what depends on it. */
+    readonly fix: string;
+}
+/** True when `version` is a semantic version. */
+export declare function isVersion(version: string): boolean;
+/** Semantic version precedence: negative when `a` comes before `b`, 0 when equal (build metadata ignored). */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * The registry dist-tag a version follows (tools/release/README.md, "Channels"): `latest` for a release, `canary` for
+ * a snapshot of main (`-canary.<date>.<n>`), `dev` for a manual cut (`-dev-<date>…`), `next` for any other prerelease.
+ */
+export declare function releaseChannel(version: string): "latest" | "next" | "canary" | "dev";
+/**
+ * The entries of a changesets `CHANGELOG.md`: every `## <version>` heading, its `### … Changes` sections and their
+ * bullets. A bullet's leading commit (`- abc1234: …`) is dropped and its continuation lines are joined.
+ */
+export declare function parseChangelog(text: string): ReleaseEntry[];
+/** The entries after `from` up to and including `to`, newest first; entries that are not versions are skipped. */
+export declare function entriesBetween(entries: readonly ReleaseEntry[], from: string, to: string): ReleaseEntry[];
+/** A change's first sentence, at most `max` characters: a notice is a summary; the notes file has the rest. */
+export declare function headline(change: string, max?: number): string;
+/** The notice as lines for a terminal: what is new (breaking changes first, at most `maxItems`), then a newer version. */
+export declare function releaseNoticeLines(notice: ReleaseNotice, options?: {
+    maxItems?: number;
+}): string[];

package/core/domain/src/releases/release-notes.js

@@ -0,0 +1,115 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const SEMVER = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+function parse(version) {
+    const match = SEMVER.exec(version.trim());
+    if (!match)
+        return undefined;
+    return { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] ? match[4].split(".") : [] };
+}
+export function isVersion(version) {
+    return parse(version) !== undefined;
+}
+export function compareVersions(a, b) {
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        throw new Error(`Not a semantic version: ${!left ? a : b}`);
+    for (let i = 0; i < 3; i++)
+        if (left.core[i] !== right.core[i])
+            return left.core[i] - right.core[i];
+    if (!left.pre.length || !right.pre.length)
+        return right.pre.length - left.pre.length;
+    for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i++) {
+        const x = left.pre[i];
+        const y = right.pre[i];
+        if (x === undefined || y === undefined)
+            return x === undefined ? -1 : 1;
+        if (x === y)
+            continue;
+        const numeric = /^\d+$/;
+        if (numeric.test(x) && numeric.test(y))
+            return Number(x) - Number(y);
+        if (numeric.test(x) !== numeric.test(y))
+            return numeric.test(x) ? -1 : 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}
+export function releaseChannel(version) {
+    const pre = parse(version)?.pre;
+    if (!pre?.length)
+        return "latest";
+    if (pre[0] === "canary")
+        return "canary";
+    if (pre[0].startsWith("dev-"))
+        return "dev";
+    return "next";
+}
+export function parseChangelog(text) {
+    const entries = [];
+    let current;
+    let section = "changes";
+    let item;
+    const flush = () => {
+        if (current && item?.length)
+            current[section].push(item.join(" ").replace(/\s+/g, " ").trim());
+        item = undefined;
+    };
+    for (const line of text.split(/\r?\n/)) {
+        const heading = /^##\s+(\S+)\s*$/.exec(line);
+        if (heading && isVersion(heading[1])) {
+            flush();
+            current = { version: heading[1].replace(/^v/, ""), breaking: [], changes: [] };
+            entries.push(current);
+            section = "changes";
+            continue;
+        }
+        if (!current)
+            continue;
+        const subheading = /^###\s+(.*)$/.exec(line);
+        if (subheading) {
+            flush();
+            section = /^major/i.test(subheading[1].trim()) ? "breaking" : "changes";
+            continue;
+        }
+        const bullet = /^[-*]\s+(?:[0-9a-f]{7,40}:\s+)?(.*)$/.exec(line);
+        if (bullet) {
+            flush();
+            item = [bullet[1]];
+        }
+        else if (item && /^\s+\S/.test(line))
+            item.push(line.trim());
+        else if (item && line.trim() === "")
+            flush();
+    }
+    flush();
+    return entries;
+}
+export function entriesBetween(entries, from, to) {
+    return entries
+        .filter((entry) => compareVersions(entry.version, from) > 0 && compareVersions(entry.version, to) <= 0)
+        .sort((a, b) => compareVersions(b.version, a.version));
+}
+export function headline(change, max = 160) {
+    const first = change.split(/(?<=[.!?])\s+(?=[A-Z`])/)[0] ?? change;
+    return first.length > max ? `${first.slice(0, max - 1).trimEnd()}…` : first;
+}
+export function releaseNoticeLines(notice, options = {}) {
+    const max = options.maxItems ?? 8;
+    const lines = [];
+    if (notice.whatsNew) {
+        const { from, entries, notes } = notice.whatsNew;
+        lines.push(`${notice.package} was updated from ${from} to ${notice.version}.`);
+        const breaking = entries.flatMap((entry) => entry.breaking.map((change) => `  Breaking (${entry.version}): ${headline(change)}`));
+        const changes = entries.flatMap((entry) => entry.changes.map((change) => `  ${entry.version}: ${headline(change)}`));
+        const shown = [...breaking, ...changes].slice(0, max);
+        if (shown.length)
+            lines.push("What's new:", ...shown);
+        const more = breaking.length + changes.length - shown.length;
+        lines.push(`${more > 0 ? `${more} more; the` : "The"} full notes: ${notes}`);
+    }
+    if (notice.available)
+        lines.push(`${notice.package} ${notice.available.version} is available (${notice.available.tag}; this repository uses ${notice.version}). Run ${notice.fix}.`);
+    return lines;
+}

package/core/domain/src/resources/generation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An environment generation: 1 when the lab starts, one more after every
+ * reset. Services, scopes and actor sessions belong to the generation they
+ * were created in; anything from an older generation is stale.
+ */
+export declare class Generation {
+    readonly value: number;
+    private constructor();
+    static first(): Generation;
+    static of(value: number): Generation;
+    next(): Generation;
+    /** Whether something from generation `other` belongs to this one (is not stale). */
+    isCurrent(other: Generation | number): boolean;
+    toJSON(): number;
+}

package/core/domain/src/resources/generation.js

@@ -0,0 +1,26 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class Generation {
+    value;
+    constructor(value) {
+        this.value = value;
+        Object.freeze(this);
+    }
+    static first() {
+        return new Generation(1);
+    }
+    static of(value) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new Error(`A generation is a positive integer, not ${String(value)}`);
+        return new Generation(value);
+    }
+    next() {
+        return new Generation(this.value + 1);
+    }
+    isCurrent(other) {
+        return (typeof other === "number" ? other : other.value) === this.value;
+    }
+    toJSON() {
+        return this.value;
+    }
+}

package/core/domain/src/resources/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./resource.js";
+export * from "./resource-functions.js";
+export * from "./generation.js";

package/core/domain/src/resources/index.js

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

package/core/domain/src/resources/resource-functions.d.ts

@@ -0,0 +1,6 @@
+/** One account's nonce sequence, shared by steps signing with that account. */
+export declare function accountResource(address: string): string;
+/** Validate a declared list of resource names. */
+export declare function assertResources(resources: readonly string[], owner: string): void;
+/** Resource names held by both lists, each once. */
+export declare function collisions(a: readonly string[], b: readonly string[]): string[];

package/core/domain/src/resources/resource-functions.js

@@ -0,0 +1,12 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { Resource } from "./resource.js";
+export function accountResource(address) {
+    return Resource.account(address).name;
+}
+export function assertResources(resources, owner) {
+    Resource.assertAll(resources, owner);
+}
+export function collisions(a, b) {
+    return Resource.collisions(a, b);
+}

package/core/domain/src/resources/resource.d.ts

@@ -0,0 +1,17 @@
+export declare class Resource {
+    readonly name: string;
+    private constructor();
+    static isValid(name: unknown): name is string;
+    /** `owner` names who declared it in the error. */
+    static parse(name: unknown, owner?: string): Resource;
+    /** One account's nonce sequence. Every step that signs with an account
+     * declares it, so two submissions from one account never race for a nonce. */
+    static account(address: string): Resource;
+    /** Validate a declared list (an empty list declares none). */
+    static assertAll(names: readonly unknown[], owner: string): void;
+    /** Names both lists hold, each once, in the order of `b`. */
+    static collisions(a: readonly string[], b: readonly string[]): string[];
+    equals(other: Resource): boolean;
+    toString(): string;
+    toJSON(): string;
+}

package/core/domain/src/resources/resource.js

@@ -0,0 +1,42 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,199}$/;
+export class Resource {
+    name;
+    constructor(name) {
+        this.name = name;
+        Object.freeze(this);
+    }
+    static isValid(name) {
+        return typeof name === "string" && NAME.test(name);
+    }
+    static parse(name, owner = "A step") {
+        if (!Resource.isValid(name))
+            throw new Error(`${owner} declares an invalid resource ${JSON.stringify(name)}`);
+        return new Resource(name);
+    }
+    static account(address) {
+        if (!address || /\s/.test(address))
+            throw new Error("An account resource needs an address");
+        return Resource.parse(`account:${address}`, "An account resource");
+    }
+    static assertAll(names, owner) {
+        if (!Array.isArray(names))
+            throw new Error(`${owner} must declare its resources (an empty list for none)`);
+        for (const name of names)
+            Resource.parse(name, owner);
+    }
+    static collisions(a, b) {
+        const set = new Set(a);
+        return [...new Set(b)].filter((name) => set.has(name));
+    }
+    equals(other) {
+        return other.name === this.name;
+    }
+    toString() {
+        return this.name;
+    }
+    toJSON() {
+        return this.name;
+    }
+}

package/core/domain/src/root-calls/index.d.ts

@@ -0,0 +1,2 @@
+export { KNOWN_CHAINS, knownChain, type KnownChain, type KnownNetworkKind } from "./known-networks.js";
+export { CALL_CARRYING_PALLETS, parseRootCallName, rootCallDecision, rootCallPolicyProblems, type RootCallDecision, type RootCallName, type RootCallPolicyData, type RootCallRequest, } from "./root-call-policy.js";

package/core/domain/src/root-calls/index.js

@@ -0,0 +1,4 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { KNOWN_CHAINS, knownChain } from "./known-networks.js";
+export { CALL_CARRYING_PALLETS, parseRootCallName, rootCallDecision, rootCallPolicyProblems, } from "./root-call-policy.js";

package/core/domain/src/root-calls/known-networks.d.ts

@@ -0,0 +1,13 @@
+/** `mainnet`: never a root call. `testnet`: a public test network, allowed only with a policy that names it. */
+export type KnownNetworkKind = "mainnet" | "testnet";
+export interface KnownChain {
+    readonly genesis: string;
+    readonly network: string;
+    readonly chain: string;
+    /** The runtime's spec name when the hash was read. */
+    readonly specName: string;
+    readonly kind: KnownNetworkKind;
+}
+export declare const KNOWN_CHAINS: readonly KnownChain[];
+/** The known chain with this genesis hash (any case), or undefined. */
+export declare function knownChain(genesis: string): KnownChain | undefined;

package/core/domain/src/root-calls/known-networks.js

@@ -0,0 +1,23 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const KNOWN_CHAINS = [
+    { genesis: "0x91b171bb158e2d3848fa23a9f1c25182fb8e20313b2c1eb49219da7a70ce90c3", network: "polkadot", chain: "relay", specName: "polkadot", kind: "mainnet" },
+    { genesis: "0x68d56f15f85d3136970ec16946040bc1752654e906147f7e43e9d539d7c3de2f", network: "polkadot", chain: "asset-hub", specName: "statemint", kind: "mainnet" },
+    { genesis: "0x67fa177a097bfa18f77ea95ab56e9bcdfeb0e5b8a40e46298bb93e16b6fc5008", network: "polkadot", chain: "people", specName: "people-polkadot", kind: "mainnet" },
+    { genesis: "0xdcf691b5a3fbe24adc99ddc959c0561b973e329b1aef4c4b22e7bb2ddecb4464", network: "polkadot", chain: "bridge-hub", specName: "bridge-hub-polkadot", kind: "mainnet" },
+    { genesis: "0x46ee89aa2eedd13e988962630ec9fb7565964cf5023bb351f2b6b25c1b68b0b2", network: "polkadot", chain: "collectives", specName: "collectives", kind: "mainnet" },
+    { genesis: "0xefb56e30d9b4a24099f88820987d0f45fb645992416535d87650d98e00f46fc4", network: "polkadot", chain: "coretime", specName: "coretime-polkadot", kind: "mainnet" },
+    { genesis: "0xb0a8d493285c2df73290dfb7e61f870f17b41801197a149ca93654499ea3dafe", network: "kusama", chain: "relay", specName: "kusama", kind: "mainnet" },
+    { genesis: "0x48239ef607d7928874027a43a67689209727dfb3d3dc5e5b03a39bdc2eda771a", network: "kusama", chain: "asset-hub", specName: "statemine", kind: "mainnet" },
+    { genesis: "0xc1af4cb4eb3918e5db15086c0cc5ec17fb334f728b7c65dd44bfe1e174ff8b3f", network: "kusama", chain: "people", specName: "people-kusama", kind: "mainnet" },
+    { genesis: "0x00dcb981df86429de8bbacf9803401f09485366c44efbf53af9ecfab03adc7e5", network: "kusama", chain: "bridge-hub", specName: "bridge-hub-kusama", kind: "mainnet" },
+    { genesis: "0x638cd2b9af4b3bb54b8c1f0d22711fc89924ca93300f0caf25a580432b29d050", network: "kusama", chain: "coretime", specName: "coretime-kusama", kind: "mainnet" },
+    { genesis: "0x4a2b5b737de1da59e209b0000a876ec2fa20035dc34fd292a848da32d255ad48", network: "paseo-next-v2", chain: "people", specName: "next-people-paseo", kind: "testnet" },
+    { genesis: "0x4349b00e54897e21196fd331015fc5be0f14e118beb0375ed2bb1793737bb57a", network: "paseo-next-v2", chain: "asset-hub", specName: "next-asset-hub-paseo", kind: "testnet" },
+    { genesis: "0x55e3e689ecfa9d2fffcf7d309b8011956671493982230bfd0420c683542249e9", network: "previewnet", chain: "people", specName: "next-people-paseo", kind: "testnet" },
+    { genesis: "0xbac97e23fc8f4bccae72a98f8aeb2bcab20bf755862304e4b46ad6473456e896", network: "previewnet", chain: "asset-hub", specName: "next-asset-hub-paseo", kind: "testnet" },
+];
+export function knownChain(genesis) {
+    const wanted = genesis.toLowerCase();
+    return KNOWN_CHAINS.find((chain) => chain.genesis === wanted);
+}

package/core/domain/src/root-calls/root-call-policy.d.ts

@@ -0,0 +1,44 @@
+/** An environment's root-call policy: plain data in a lab config. */
+export interface RootCallPolicyData {
+    /** The secret holding the sudo key's phrase or seed, by name (never the value). */
+    readonly key: string;
+    /** The calls that may be dispatched with Root, as `Pallet.call` (for example `Balances.force_set_balance`). */
+    readonly allow: readonly string[];
+    /** By chain id, the signed extensions a runtime needs beyond the defaults (as an app's `fundingSigning`). */
+    readonly signing?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}
+/** A call as the policy names it. */
+export interface RootCallName {
+    readonly pallet: string;
+    readonly name: string;
+}
+/** Pallets whose calls carry other calls: never on an allow-list, so nothing reaches Root wrapped inside an allowed call. */
+export declare const CALL_CARRYING_PALLETS: readonly string[];
+/** `Pallet.call` parsed, or undefined. */
+export declare function parseRootCallName(text: string): RootCallName | undefined;
+/** What is wrong with a policy (each named at `at`), or nothing. */
+export declare function rootCallPolicyProblems(value: unknown, at?: string): string[];
+/** One root call to decide. */
+export interface RootCallRequest {
+    readonly policy?: RootCallPolicyData;
+    /** The chain's genesis hash, as its node says. */
+    readonly genesis: string;
+    /** The lab started this chain's nodes itself on this machine (a local network or fork), not a public network. */
+    readonly owned: boolean;
+    /** The environment is a public target that may not be written (`access` read-only, the default). */
+    readonly readOnly?: boolean;
+    readonly call: RootCallName;
+    readonly token: {
+        readonly given?: string;
+        readonly expected: string;
+    };
+}
+export type RootCallDecision = {
+    readonly allowed: true;
+    readonly network: string;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+/** Whether `request` may be dispatched with Root (the key's check aside), and on what network; or why not. */
+export declare function rootCallDecision(request: RootCallRequest): RootCallDecision;

package/core/domain/src/root-calls/root-call-policy.js

@@ -0,0 +1,59 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { knownChain } from "./known-networks.js";
+export const CALL_CARRYING_PALLETS = ["Sudo", "Utility", "Proxy", "Multisig", "Scheduler", "Whitelist", "Democracy", "Referenda", "Council", "TechnicalCommittee", "PolkadotXcm", "XcmPallet", "Recovery"];
+const CALL = /^([A-Z][A-Za-z0-9]*)\.([a-z][a-z0-9_]*)$/;
+const SECRET = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export function parseRootCallName(text) {
+    const match = CALL.exec(text);
+    return match ? { pallet: match[1], name: match[2] } : undefined;
+}
+export function rootCallPolicyProblems(value, at = "rootCalls") {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return [`${at} must be { key, allow }`];
+    const { key, allow, signing, ...rest } = value;
+    const problems = [];
+    for (const extra of Object.keys(rest))
+        problems.push(`${at}.${extra} is not a field of rootCalls (key, allow, signing)`);
+    if (signing !== undefined && (!signing || typeof signing !== "object" || Array.isArray(signing) || Object.values(signing).some((item) => !item || typeof item !== "object" || Array.isArray(item))))
+        problems.push(`${at}.signing must be, by chain id, the signed extensions an object names`);
+    if (typeof key !== "string" || !SECRET.test(key))
+        problems.push(`${at}.key must name a secret (letters, digits, ".", "_" or "-")`);
+    if (!Array.isArray(allow) || allow.length === 0)
+        problems.push(`${at}.allow must list at least one call as "Pallet.call"`);
+    else {
+        const seen = new Set();
+        allow.forEach((item, index) => {
+            const call = typeof item === "string" ? parseRootCallName(item) : undefined;
+            if (!call)
+                problems.push(`${at}.allow[${index}] must be "Pallet.call" (for example "Balances.force_set_balance")`);
+            else if (CALL_CARRYING_PALLETS.includes(call.pallet))
+                problems.push(`${at}.allow[${index}] ${String(item)} carries other calls: it may not be allowed`);
+            else if (seen.has(String(item)))
+                problems.push(`${at}.allow[${index}] ${String(item)} is listed twice`);
+            seen.add(String(item));
+        });
+    }
+    return problems;
+}
+export function rootCallDecision(request) {
+    const refuse = (reason) => ({ allowed: false, reason: `Root call refused: ${reason}` });
+    const named = `${request.call.pallet}.${request.call.name}`;
+    if (!request.policy)
+        return refuse("this environment declares no rootCalls");
+    const known = knownChain(request.genesis);
+    if (known?.kind === "mainnet")
+        return refuse(`the chain is ${known.network}'s ${known.chain} (genesis ${request.genesis}), a mainnet: never`);
+    if (!request.owned && known?.kind !== "testnet")
+        return refuse(`the chain (genesis ${request.genesis}) is neither one the lab started on this machine nor a public testnet the lab knows`);
+    if (request.readOnly)
+        return refuse(`${known ? `${known.network}'s ${known.chain}` : "the chain"} is a read-only public target here (declare the environment's access "read-write" to write)`);
+    if (CALL_CARRYING_PALLETS.includes(request.call.pallet))
+        return refuse(`${named} carries other calls`);
+    if (!request.policy.allow.includes(named))
+        return refuse(`${named} is not on this environment's allow-list (${request.policy.allow.join(", ")})`);
+    if (request.token.given !== request.token.expected)
+        return refuse("the run's root-call confirmation was not given, or is not this run's");
+    const network = request.owned ? `a local chain the lab started${known ? ` (genesis of ${known.network}'s ${known.chain})` : ""}` : `${known.network}'s ${known.chain}`;
+    return { allowed: true, network };
+}

package/core/domain/src/runs/checkpoint.d.ts

@@ -0,0 +1,20 @@
+/** Why a run stopped at a checkpoint: stepping through (checkpoint mode) or a pause the tester asked for. */
+export type CheckpointReason = "checkpoint-mode" | "requested";
+/**
+ * A safe checkpoint a run is paused at: after a step finished, before the
+ * next starts, with submitted work settled. Immutable.
+ */
+export declare class Checkpoint {
+    /** Index of the step that just finished (0-based). */
+    readonly afterStep: number;
+    readonly reason: CheckpointReason;
+    /** When the run reached it, on the run's clock (ms). */
+    readonly at: number;
+    constructor(checkpoint: {
+        afterStep: number;
+        reason: CheckpointReason;
+        at: number;
+    });
+    /** How long the run has been paused here. */
+    pausedFor(now: number): number;
+}

package/core/domain/src/runs/checkpoint.js

@@ -0,0 +1,22 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export class Checkpoint {
+    afterStep;
+    reason;
+    at;
+    constructor(checkpoint) {
+        if (!Number.isSafeInteger(checkpoint.afterStep) || checkpoint.afterStep < 0)
+            throw new Error("A checkpoint follows a step: afterStep is a step index");
+        if (checkpoint.reason !== "checkpoint-mode" && checkpoint.reason !== "requested")
+            throw new Error(`Unknown checkpoint reason ${String(checkpoint.reason)}`);
+        if (!Number.isFinite(checkpoint.at) || checkpoint.at < 0)
+            throw new Error("A checkpoint has a time");
+        this.afterStep = checkpoint.afterStep;
+        this.reason = checkpoint.reason;
+        this.at = checkpoint.at;
+        Object.freeze(this);
+    }
+    pausedFor(now) {
+        return Math.max(0, now - this.at);
+    }
+}

package/core/domain/src/runs/evidence.d.ts

@@ -0,0 +1,66 @@
+import type { NavigationEvidence } from "../navigation/navigation-evidence.js";
+import { type Mortality, type ReceiptPosition } from "./submitted-transaction.js";
+/** An extrinsic the evidence names by block hash and index (`{ blockHash, extrinsicIndex }`). */
+export interface ReceiptEvidence {
+    readonly kind: "receipt";
+    /** JSON path in the step result, `$` for the root. */
+    readonly path: string;
+    readonly blockHash: string;
+    readonly index: number;
+    readonly block?: number;
+}
+/**
+ * A transaction the evidence names by its hash (`{ txHash }`), with what else
+ * it says about it: the signer (`signer` or `account`), the finalized block
+ * known before signing (`after`, or `signedAt.number`), the nonce, the
+ * mortality (its `birthHash` from `signedAt.hash` when that block is the era's
+ * birth) and, for a receipt (`{ txHash, block: { hash, index } }` or
+ * `blockHash` with an index), where it landed. What "did this transaction
+ * land" checks.
+ */
+export interface TransactionEvidence {
+    readonly kind: "transaction";
+    readonly path: string;
+    readonly txHash: string;
+    readonly chain?: string;
+    readonly signer?: string;
+    readonly after?: number;
+    readonly nonce?: number;
+    readonly mortality?: Mortality;
+    readonly receipt?: ReceiptPosition;
+}
+/** A block number the evidence refers to (a key containing `block`). */
+export interface BlockEvidence {
+    readonly kind: "block";
+    readonly path: string;
+    readonly block: number;
+}
+/** A UI observation recorded as a file (screenshot, snapshot, video, trace). */
+export interface ObservationEvidence {
+    readonly kind: "observation";
+    readonly path: string;
+    /** Absolute path of the artifact. */
+    readonly artifact: string;
+}
+export type EvidenceItem = ReceiptEvidence | TransactionEvidence | BlockEvidence | ObservationEvidence | (NavigationEvidence & {
+    readonly path: string;
+});
+export declare class Evidence {
+    readonly value: unknown;
+    private constructor();
+    static of(value: unknown): Evidence;
+    /** Extrinsics named by block hash and index (`extrinsicIndex`, `extrinsic` or `index`), depth-first. */
+    receipts(): ReceiptEvidence[];
+    /** Transactions named by `txHash` (a 32-byte hash), depth-first; see {@link TransactionEvidence}. */
+    transactions(): TransactionEvidence[];
+    /** Block numbers under keys containing `block` (a number, or an object with `number`). */
+    blocks(): BlockEvidence[];
+    /** Absolute artifact paths under keys naming a screenshot, snapshot, video, trace or image. */
+    observations(): ObservationEvidence[];
+    /** Navigation records the bridge produced, wherever the step result carries them. */
+    navigations(): (NavigationEvidence & {
+        readonly path: string;
+    })[];
+    /** Every item, by kind: receipts, transactions, blocks, navigations, observations. */
+    items(): EvidenceItem[];
+}