@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/domain/src/accounts/expected-account.js

@@ -0,0 +1,35 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { AccountAddress } from "./account-address.js";
+export class ExpectedAccount {
+    account;
+    comparison;
+    constructor(account, comparison = {}) {
+        this.account = typeof account === "string" ? AccountAddress.parse(account) : account;
+        this.comparison = comparison;
+        Object.freeze(this);
+    }
+    matches(value) {
+        const text = addressText(value);
+        const found = text === undefined ? undefined : AccountAddress.tryParse(text);
+        return found ? this.account.same(found, this.comparison) : false;
+    }
+    toString() {
+        return this.account.text;
+    }
+    toJSON() {
+        return this.account.text;
+    }
+}
+function addressText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value instanceof Uint8Array)
+        return `0x${Array.from(value, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+    const withHex = value;
+    if (withHex && typeof withHex === "object" && typeof withHex.asHex === "function") {
+        const hex = withHex.asHex();
+        return typeof hex === "string" ? hex : undefined;
+    }
+    return undefined;
+}

package/core/domain/src/accounts/hashes.d.ts

@@ -0,0 +1,4 @@
+/** Unkeyed BLAKE2b of `data`, `length` bytes out (1 to 64; the SS58 checksum uses 64). */
+export declare function blake2b(data: Uint8Array, length?: number): Uint8Array;
+/** Keccak-256 of `data` (the Ethereum hash, not SHA3-256: padding byte 0x01). */
+export declare function keccak256(data: Uint8Array): Uint8Array;

package/core/domain/src/accounts/hashes.js

@@ -0,0 +1,131 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const MASK = (1n << 64n) - 1n;
+const rotr = (value, bits) => ((value >> bits) | (value << (64n - bits))) & MASK;
+const rotl = (value, bits) => ((value << bits) | (value >> (64n - bits))) & MASK;
+function word(bytes, offset) {
+    let value = 0n;
+    for (let index = 7; index >= 0; index--)
+        value = (value << 8n) | BigInt(bytes[offset + index] ?? 0);
+    return value;
+}
+function writeWord(target, offset, value, length = 8) {
+    for (let index = 0; index < length; index++)
+        target[offset + index] = Number((value >> BigInt(8 * index)) & 0xffn);
+}
+const BLAKE_IV = [
+    0x6a09e667f3bcc908n, 0xbb67ae8584caa73bn, 0x3c6ef372fe94f82bn, 0xa54ff53a5f1d36f1n,
+    0x510e527fade682d1n, 0x9b05688c2b3e6c1fn, 0x1f83d9abfb41bd6bn, 0x5be0cd19137e2179n,
+];
+const BLAKE_SIGMA = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+    [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+    [11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4],
+    [7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8],
+    [9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13],
+    [2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9],
+    [12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11],
+    [13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10],
+    [6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5],
+    [10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0],
+];
+function blakeCompress(state, block, counter, last) {
+    const m = Array.from({ length: 16 }, (_, index) => word(block, index * 8));
+    const v = [...state, ...BLAKE_IV];
+    v[12] = v[12] ^ (counter & MASK);
+    v[13] = v[13] ^ (counter >> 64n);
+    if (last)
+        v[14] = v[14] ^ MASK;
+    const mix = (a, b, c, d, x, y) => {
+        v[a] = (v[a] + v[b] + x) & MASK;
+        v[d] = rotr(v[d] ^ v[a], 32n);
+        v[c] = (v[c] + v[d]) & MASK;
+        v[b] = rotr(v[b] ^ v[c], 24n);
+        v[a] = (v[a] + v[b] + y) & MASK;
+        v[d] = rotr(v[d] ^ v[a], 16n);
+        v[c] = (v[c] + v[d]) & MASK;
+        v[b] = rotr(v[b] ^ v[c], 63n);
+    };
+    for (let round = 0; round < 12; round++) {
+        const s = BLAKE_SIGMA[round % 10];
+        mix(0, 4, 8, 12, m[s[0]], m[s[1]]);
+        mix(1, 5, 9, 13, m[s[2]], m[s[3]]);
+        mix(2, 6, 10, 14, m[s[4]], m[s[5]]);
+        mix(3, 7, 11, 15, m[s[6]], m[s[7]]);
+        mix(0, 5, 10, 15, m[s[8]], m[s[9]]);
+        mix(1, 6, 11, 12, m[s[10]], m[s[11]]);
+        mix(2, 7, 8, 13, m[s[12]], m[s[13]]);
+        mix(3, 4, 9, 14, m[s[14]], m[s[15]]);
+    }
+    for (let index = 0; index < 8; index++)
+        state[index] = state[index] ^ v[index] ^ v[index + 8];
+}
+export function blake2b(data, length = 64) {
+    if (!Number.isInteger(length) || length < 1 || length > 64)
+        throw new Error("BLAKE2b output is 1 to 64 bytes");
+    const state = [...BLAKE_IV];
+    state[0] = state[0] ^ (0x01010000n | BigInt(length));
+    let offset = 0;
+    while (data.length - offset > 128) {
+        blakeCompress(state, data.subarray(offset, offset + 128), BigInt(offset + 128), false);
+        offset += 128;
+    }
+    const tail = new Uint8Array(128);
+    tail.set(data.subarray(offset));
+    blakeCompress(state, tail, BigInt(data.length), true);
+    const out = new Uint8Array(64);
+    for (let index = 0; index < 8; index++)
+        writeWord(out, index * 8, state[index]);
+    return out.slice(0, length);
+}
+const KECCAK_ROUNDS = [
+    0x0000000000000001n, 0x0000000000008082n, 0x800000000000808an, 0x8000000080008000n, 0x000000000000808bn, 0x0000000080000001n,
+    0x8000000080008081n, 0x8000000000008009n, 0x000000000000008an, 0x0000000000000088n, 0x0000000080008009n, 0x000000008000000an,
+    0x000000008000808bn, 0x800000000000008bn, 0x8000000000008089n, 0x8000000000008003n, 0x8000000000008002n, 0x8000000000000080n,
+    0x000000000000800an, 0x800000008000000an, 0x8000000080008081n, 0x8000000000008080n, 0x0000000080000001n, 0x8000000080008008n,
+];
+const KECCAK_ROTATION = [1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 2, 14, 27, 41, 56, 8, 25, 43, 62, 18, 39, 61, 20, 44];
+const KECCAK_LANE = [10, 7, 11, 17, 18, 3, 5, 16, 8, 21, 24, 4, 15, 23, 19, 13, 12, 2, 20, 14, 22, 9, 6, 1];
+function keccakPermute(state) {
+    const column = new Array(5).fill(0n);
+    for (const constant of KECCAK_ROUNDS) {
+        for (let x = 0; x < 5; x++)
+            column[x] = state[x] ^ state[x + 5] ^ state[x + 10] ^ state[x + 15] ^ state[x + 20];
+        for (let x = 0; x < 5; x++) {
+            const mixed = column[(x + 4) % 5] ^ rotl(column[(x + 1) % 5], 1n);
+            for (let y = 0; y < 25; y += 5)
+                state[y + x] = state[y + x] ^ mixed;
+        }
+        let carried = state[1];
+        for (let index = 0; index < 24; index++) {
+            const lane = KECCAK_LANE[index];
+            const next = state[lane];
+            state[lane] = rotl(carried, BigInt(KECCAK_ROTATION[index]));
+            carried = next;
+        }
+        for (let y = 0; y < 25; y += 5) {
+            for (let x = 0; x < 5; x++)
+                column[x] = state[y + x];
+            for (let x = 0; x < 5; x++)
+                state[y + x] = column[x] ^ (~column[(x + 1) % 5] & MASK & column[(x + 2) % 5]);
+        }
+        state[0] = state[0] ^ constant;
+    }
+}
+export function keccak256(data) {
+    const rate = 136;
+    const padded = new Uint8Array(Math.floor(data.length / rate) * rate + rate);
+    padded.set(data);
+    padded[data.length] = padded[data.length] ^ 0x01;
+    padded[padded.length - 1] = padded[padded.length - 1] ^ 0x80;
+    const state = new Array(25).fill(0n);
+    for (let offset = 0; offset < padded.length; offset += rate) {
+        for (let lane = 0; lane < rate / 8; lane++)
+            state[lane] = state[lane] ^ word(padded, offset + lane * 8);
+        keccakPermute(state);
+    }
+    const out = new Uint8Array(32);
+    for (let lane = 0; lane < 4; lane++)
+        writeWord(out, lane * 8, state[lane]);
+    return out;
+}

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

@@ -0,0 +1,5 @@
+export * from "./account-address.js";
+export * from "./account-format-error.js";
+export * from "./ambiguous-account-error.js";
+export * from "./expected-account.js";
+export * from "./account-functions.js";

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

@@ -0,0 +1,7 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export * from "./account-address.js";
+export * from "./account-format-error.js";
+export * from "./ambiguous-account-error.js";
+export * from "./expected-account.js";
+export * from "./account-functions.js";

package/core/domain/src/actors/actor-alias.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The name a scenario gives an actor (`Alice`, `Bob`): a capitalised alias,
+ * bound to an identity when a run starts. Distinct from the `ActorId` of a
+ * running actor session.
+ */
+export declare class ActorAlias {
+    readonly value: string;
+    private constructor();
+    static isValid(value: unknown): value is string;
+    static parse(value: unknown): ActorAlias;
+    toString(): string;
+    toJSON(): string;
+}

package/core/domain/src/actors/actor-alias.js

@@ -0,0 +1,24 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const ALIAS = /^[A-Z][A-Za-z0-9_-]{0,31}$/;
+export class ActorAlias {
+    value;
+    constructor(value) {
+        this.value = value;
+        Object.freeze(this);
+    }
+    static isValid(value) {
+        return typeof value === "string" && ALIAS.test(value);
+    }
+    static parse(value) {
+        if (!ActorAlias.isValid(value))
+            throw new Error(`Actor names are capitalised aliases such as Alice, not ${JSON.stringify(value)}`);
+        return new ActorAlias(value);
+    }
+    toString() {
+        return this.value;
+    }
+    toJSON() {
+        return this.value;
+    }
+}

package/core/domain/src/actors/actor-id.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The id of an actor session (what `LabEnvironment.actors()` reports and
+ * hosts receive as `HostActor.id`). Opaque, non-empty, at most 200
+ * characters, no control characters, so it can key sessions unambiguously.
+ */
+export declare class ActorId {
+    readonly value: string;
+    private constructor();
+    static parse(value: unknown): ActorId;
+    equals(other: ActorId): boolean;
+    toString(): string;
+    toJSON(): string;
+}

package/core/domain/src/actors/actor-id.js

@@ -0,0 +1,24 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const CONTROL = /[\u0000-\u001f\u007f]/;
+export class ActorId {
+    value;
+    constructor(value) {
+        this.value = value;
+        Object.freeze(this);
+    }
+    static parse(value) {
+        if (typeof value !== "string" || value.length === 0 || value.length > 200 || CONTROL.test(value))
+            throw new Error(`Invalid actor id ${JSON.stringify(value)}: a non-empty string of at most 200 characters without control characters`);
+        return new ActorId(value);
+    }
+    equals(other) {
+        return other.value === this.value;
+    }
+    toString() {
+        return this.value;
+    }
+    toJSON() {
+        return this.value;
+    }
+}

package/core/domain/src/actors/actor-roster.d.ts

@@ -0,0 +1,19 @@
+import { Actor, type ActorSession } from "./actor.js";
+/**
+ * The actors of one environment: distinct ids and one isolated app origin
+ * each. The controller checked this in two places (the current environment
+ * and the one it switches to); the panel used the removal rule.
+ */
+export declare class ActorRoster {
+    #private;
+    readonly actors: readonly Actor[];
+    constructor(sessions: readonly ActorSession[]);
+    /** The session with this id; throws for an unknown one. */
+    session(id: string): ActorSession;
+    /**
+     * Why an actor may not be stopped or removed: keep a usable app session.
+     * Undefined when it may (or when the id is unknown).
+     */
+    static removalBlockedReason(sessions: readonly ActorSession[], id: string): string | undefined;
+    removalBlockedReason(id: string): string | undefined;
+}

package/core/domain/src/actors/actor-roster.js

@@ -0,0 +1,36 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { Actor } from "./actor.js";
+export class ActorRoster {
+    actors;
+    #sessions;
+    constructor(sessions) {
+        const actors = sessions.map((session) => Actor.from(session));
+        const ids = new Set(actors.map((actor) => actor.id.value));
+        const origins = new Set(actors.map((actor) => actor.origin));
+        if (ids.size !== actors.length || origins.size !== actors.length)
+            throw new Error("Actors require distinct ids and isolated application origins");
+        this.actors = Object.freeze(actors);
+        this.#sessions = Object.freeze([...sessions]);
+        Object.freeze(this);
+    }
+    session(id) {
+        const session = this.#sessions.find((item) => item.id === id);
+        if (!session)
+            throw new Error("Unknown actor session");
+        return session;
+    }
+    static removalBlockedReason(sessions, id) {
+        const actor = sessions.find((item) => item.id === id);
+        if (!actor)
+            return undefined;
+        if (sessions.length === 1)
+            return "Keep at least one identity. Create another identity first.";
+        if (Actor.isRunning(actor) && !sessions.some((item) => item.id !== id && Actor.isRunning(item)))
+            return "Keep at least one running identity. Start another identity first.";
+        return undefined;
+    }
+    removalBlockedReason(id) {
+        return ActorRoster.removalBlockedReason(this.#sessions, id);
+    }
+}

package/core/domain/src/actors/actor.d.ts

@@ -0,0 +1,122 @@
+import { ActorId } from "./actor-id.js";
+export type ActorStatus = "starting" | "running" | "stopped" | "failed";
+/** How an actor's identity came to be: the lab created it, or it existed before (pre-onboarded, backlog A3). */
+export type ActorKind = "created" | "preOnboarded";
+/**
+ * Where an identity came from, as views say it beside the person (docs/feature-map.md, "Identity"):
+ * - `new`: New identity (the lab window, the MCP server or the terminal asked for one);
+ * - `run`: a scenario run asked for a new person (`source`: the scenario);
+ * - `saved-state`: a saved chain state was loaded and the identity came with it (`source`: the state's name);
+ * - `start`: opened when the environment started (the lab's first identity, or one it keeps between starts);
+ * - `declared`: an existing wallet the lab declares (pre-onboarded, backlog A3).
+ */
+export interface ActorOrigin {
+    readonly kind: "new" | "run" | "saved-state" | "saved" | "start" | "declared";
+    /** When it was made or opened (ISO 8601); for `saved`, when it was opened again. */
+    readonly at: string;
+    /** The scenario (`run`) or the saved state (`saved-state`) it came from. */
+    readonly source?: string;
+    /** `saved` (kept by the lab between starts): when it was first made (ISO 8601), when the lab recorded it. */
+    readonly made?: string;
+    /** `saved`: where the lab keeps it, as a path a person can open. */
+    readonly stored?: string;
+}
+/**
+ * C6, 6 October 2026: what a host cannot do yet, said up front on every person on it (a chip of `label`, its tooltip
+ * `why`). The host adapter's own words, never the lab's; an app's consequence belongs in the lab's host description.
+ */
+export interface HostLimit {
+    /** A few words views show on the person: "can't read Bulletin". */
+    readonly label: string;
+    /** Why, and what a person sees because of it. */
+    readonly why: string;
+}
+/**
+ * C4, 6 October 2026: a session's network as it really is where it opened, when that differs from what its host's
+ * options say (a lock that applies only in part in a lab-window tile). The host adapter's words; views show `label`
+ * in place of the option `replaces` names, on the person's row and on their tile alike, with `why` as the tooltip.
+ */
+export interface HostNetworkNote {
+    /** "network partly locked: sockets open". */
+    readonly label: string;
+    readonly why: string;
+    /** The option's label this note stands for ("network locked"); absent: the note is added after the options. */
+    readonly replaces?: string;
+}
+/** The host an actor's session runs in, as views name it: the host adapter's id and its short label. */
+export interface ActorHost {
+    /** The host adapter's id (`HostProvider.id`). */
+    readonly id: string;
+    /** A short name views show beside the person, for example on their tile. */
+    readonly label: string;
+    /** The hue views mark the host with (`#rrggbb`, `isHostColor`); absent: the neutral `HOST_COLOR_FALLBACK`. */
+    readonly color?: string;
+    /**
+     * The host shows the app inside its own page (the truAPI WASM host): in the lab window that page is the person's tile,
+     * and an app shown there without it has no host to answer it (backlog 153).
+     */
+    readonly embedsApp?: true;
+    /** Backlog 185: the host's options on for this identity, as views read them after its name ("network locked"). */
+    readonly options?: readonly string[];
+    /** C6: what the host cannot do yet (`HostProvider.limits`), shown on the person. */
+    readonly limits?: readonly HostLimit[];
+    /** C6: the lab's one line on the host (`hosts.<id>.description`), with what its limits mean for the lab's app. */
+    readonly description?: string;
+    /** C4: the session's network where it opened, when it differs from what the options say (`withNetworkNote`). */
+    readonly network?: HostNetworkNote;
+}
+/**
+ * C4: the host as views show it with the session's network note: the note's label in place of the option it stands
+ * for, so the person's row (its options) and their tile (its note) can never say two things. `host` is the host as its
+ * options say it (`SessionHosts.shown`), never one with a note already; no note: that host.
+ */
+export declare function withNetworkNote(host: ActorHost | undefined, note: HostNetworkNote | undefined): ActorHost | undefined;
+/** The host to report for a session opened by `provider`: undefined when the provider names no label. */
+export declare function actorHost(provider: {
+    readonly id: string;
+    readonly label?: string;
+    readonly color?: string;
+    readonly capabilities?: {
+        readonly placement?: unknown;
+    };
+    readonly limits?: readonly HostLimit[];
+}): ActorHost | undefined;
+/** An actor session as environments report it and the panel shows it (plain data). */
+export interface ActorSession {
+    id: string;
+    name: string;
+    /** The person's username where the identity has one; empty when it has none (views then show none). */
+    username: string;
+    appUrl: string;
+    account: string;
+    status?: ActorStatus;
+    error?: string;
+    /**
+     * `preOnboarded`: an account that existed before the run (backlog A3); the lab never creates, deletes or funds it,
+     * and views say so. Absent: `created`.
+     */
+    kind?: ActorKind;
+    /** The host the session runs in, when the session knows it (`actorHost`); absent: unknown, and views show none. */
+    host?: ActorHost;
+    /** Where it came from and when (the runtime adds it to the views it reports); absent: unknown. */
+    origin?: ActorOrigin;
+}
+/**
+ * An actor: one identity using one app origin. Built from the session an
+ * environment reports; validates the id and the app URL (HTTP(S), no
+ * credentials) and keeps the app's origin, which isolates it from every other
+ * actor.
+ */
+export declare class Actor {
+    readonly id: ActorId;
+    readonly name: string;
+    readonly origin: string;
+    readonly status: ActorStatus | undefined;
+    private constructor();
+    static from(session: ActorSession): Actor;
+    /** The origin of an application URL; throws unless it is HTTP(S) without credentials. */
+    static origin(appUrl: string): string;
+    /** An actor without a status is running (environments that do not manage identities report none). */
+    static isRunning(session: Pick<ActorSession, "status">): boolean;
+    get running(): boolean;
+}

package/core/domain/src/actors/actor.js

@@ -0,0 +1,49 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ActorId } from "./actor-id.js";
+export function withNetworkNote(host, note) {
+    if (!host || !note)
+        return host;
+    const options = host.options ?? [];
+    const shown = note.replaces !== undefined && options.includes(note.replaces) ? options.map((option) => (option === note.replaces ? note.label : option)) : [...options, note.label];
+    return { ...host, options: shown, network: note };
+}
+export function actorHost(provider) {
+    if (!provider.label)
+        return undefined;
+    return {
+        id: provider.id,
+        label: provider.label,
+        ...(provider.color ? { color: provider.color } : {}),
+        ...(provider.capabilities?.placement ? { embedsApp: true } : {}),
+        ...(provider.limits?.length ? { limits: provider.limits } : {}),
+    };
+}
+export class Actor {
+    id;
+    name;
+    origin;
+    status;
+    constructor(session) {
+        this.id = ActorId.parse(session.id);
+        this.name = session.name;
+        this.origin = Actor.origin(session.appUrl);
+        this.status = session.status;
+        Object.freeze(this);
+    }
+    static from(session) {
+        return new Actor(session);
+    }
+    static origin(appUrl) {
+        const url = new URL(appUrl);
+        if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+            throw new Error("Application URL must be HTTP(S) without credentials");
+        return url.origin;
+    }
+    static isRunning(session) {
+        return !session.status || session.status === "running";
+    }
+    get running() {
+        return Actor.isRunning(this);
+    }
+}

package/core/domain/src/actors/host-color.d.ts

@@ -0,0 +1,4 @@
+/** The hue of a host that declares none: slate, apart from every adapter's own and from the status colours. */
+export declare const HOST_COLOR_FALLBACK = "#64748b";
+/** A host colour is a `#rrggbb` hex value. */
+export declare function isHostColor(value: unknown): value is string;

package/core/domain/src/actors/host-color.js

@@ -0,0 +1,6 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const HOST_COLOR_FALLBACK = "#64748b";
+export function isHostColor(value) {
+    return typeof value === "string" && /^#[0-9a-f]{6}$/i.test(value);
+}

package/core/domain/src/actors/host-options.d.ts

@@ -0,0 +1,74 @@
+/** A value of a host option: on or off, or one of its choices. */
+export type HostOptionValue = boolean | string;
+export type HostOptionValues = Readonly<Record<string, HostOptionValue>>;
+/** A switch a host adapter offers on its hosts, in plain words. Views and the terminal render what the adapter declares. */
+export interface HostOptionDeclaration {
+    /** Its key in the host's options (`hosts.<id>.options.<name>` in the lab config): a key of the adapter's own options. */
+    readonly name: string;
+    /** Its plain name, lower case, as it reads after the host's ("network locked"). */
+    readonly label: string;
+    /** One line: what it does and why a person turns it on. */
+    readonly why: string;
+    readonly type: "boolean" | "choice";
+    /** A `choice`'s values, each with its plain name. */
+    readonly choices?: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    /** Its value when the lab config sets none. */
+    readonly default: HostOptionValue;
+    /** A person may set it for one identity (New identity's menu, a scenario's `with`); else the lab config sets it for the host. */
+    readonly perIdentity?: boolean;
+}
+/** An option of one declared host: the adapter's declaration and the value the lab sets for the host. */
+export interface HostOptionSetting extends HostOptionDeclaration {
+    readonly value: HostOptionValue;
+}
+/** A declared host as a host reference resolves against it (`EnvironmentHost` carries these fields). */
+export interface HostChoiceEntry {
+    readonly id: string;
+    /** The session's default host: a reference with no name (`?<option>=true`) asks for it. */
+    readonly default?: boolean;
+    readonly label?: string;
+    readonly options?: readonly HostOptionSetting[];
+    /** Other names for this host with some options set (`hosts.<id>.aliases`): names a lab used before its hosts had options. */
+    readonly aliases?: Readonly<Record<string, HostOptionValues>>;
+    /** Names the host went by before ("desktop"), accepted after every other name; never shown. */
+    readonly formerNames?: readonly string[];
+}
+/** A host reference resolved: the declared host, the per-identity values that differ from its own, and its canonical reference. */
+export interface HostChoice {
+    readonly id: string;
+    /** Only the values that differ from the host's own (`HostOptionSetting.value`). */
+    readonly values: HostOptionValues;
+    /** `id`, or `id?name=value&…` with the names sorted: one host per reference. */
+    readonly reference: string;
+}
+/**
+ * The reference of host `id` with `values`: `id` alone without values, else `id?name=value&…`, names sorted. A session
+ * makes one host per reference; a saved identity keeps its reference, and comes back on the same host with the same
+ * options.
+ */
+export declare function hostReference(id: string, values?: HostOptionValues): string;
+/**
+ * What a host reference asks for: the host's name (an id, an alias, or its plain name, "truAPI CLI")
+ * and each option asked, by name or by label, with its value as written (absent: on).
+ */
+export declare function parseHostReference(reference: string): {
+    readonly name: string;
+    readonly asked: readonly (readonly [string, string | undefined])[];
+};
+/** A host reference with options asked by their labels (a scenario's `on the "truAPI CLI" host with "network locked"`). */
+export declare function hostReferenceWith(name: string, labels: readonly string[]): string;
+/** The option labels a scenario's `with "…"` names: "network locked", or "network locked and one wallet for all apps of a person". */
+export declare function withLabels(text: string): string[];
+/**
+ * Resolve a host reference against the declared hosts: the host (by id, alias or plain name) and the options it asks
+ * for (by name or label). Refused by name: a host the lab does not declare, an option its adapter does not declare,
+ * one the lab config sets for the host only, a value the option cannot take.
+ */
+export declare function resolveHostChoice(entries: readonly HostChoiceEntry[], reference: string, extra?: HostOptionValues): HostChoice | {
+    readonly problem: string;
+};
+/** The options on for a host with `values` (its own, overridden), as views read them after the host's name: "network locked". */
+export declare function hostOptionsOn(entry: HostChoiceEntry, values?: HostOptionValues): string[];