@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/application/src/orchestration/secrets/secret-source.d.ts

@@ -0,0 +1,18 @@
+import type { SecretKind } from "@parity/product-lab/ports/driving";
+/** Node's inspect hook, by its registered symbol (no Node import). */
+declare const INSPECT: unique symbol;
+export declare abstract class SecretSource {
+    abstract readonly kind: SecretKind;
+    /** Development material that must never be used outside local environments. */
+    abstract readonly localOnly: boolean;
+    /** Safe description for orchestration-side error messages (never the value). */
+    abstract describe(): string;
+    /** @internal Read the raw material. Orchestration side only. */
+    abstract read(env: NodeJS.ProcessEnv): string | undefined;
+    toJSON(): {
+        secret: string;
+        kind: SecretKind;
+    };
+    [INSPECT](): string;
+}
+export {};

package/core/application/src/orchestration/secrets/secret-source.js

@@ -0,0 +1,12 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const REDACTED = "[secret]";
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+export class SecretSource {
+    toJSON() {
+        return { secret: REDACTED, kind: this.kind };
+    }
+    [INSPECT]() {
+        return `SecretSource(${this.kind}, ${REDACTED})`;
+    }
+}

package/core/application/src/orchestration/secrets/sources.d.ts

@@ -0,0 +1,27 @@
+export type { SecretKind } from "@parity/product-lab/ports/driving";
+import { SecretSource } from "./secret-source.js";
+export { SecretSource } from "./secret-source.js";
+/**
+ * A well-known development derivation (`//Alice`, `//Bob`, …) of the Substrate
+ * development phrase. Allowed only on local environments; the lab refuses it on
+ * any environment whose offer is not `local`.
+ */
+export declare function devAccount(uri: string): SecretSource;
+/**
+ * Read a secret from an environment variable on the orchestration side when it
+ * is first needed. For signers the value may be a mnemonic, a `0x` mini secret,
+ * or either followed by a derivation path (`<phrase>//admin`).
+ */
+export declare function fromEnv(name: string): SecretSource;
+/**
+ * A secret declared once, or per environment. Keys are environment ids, or
+ * `local` / `remote` (matched by the environment's `local` flag), or `default`.
+ * Precedence: environment id, then `local`/`remote`, then `default`.
+ */
+export type SecretEntry = SecretSource | Readonly<Record<string, SecretSource>>;
+export declare function isSecretSource(value: unknown): value is SecretSource;
+export declare function selectSecretSource(entry: SecretEntry, environment: {
+    id: string;
+    local: boolean;
+}): SecretSource | undefined;
+export declare function secretEntryErrors(name: string, entry: unknown): string[];

package/core/application/src/orchestration/secrets/sources.js

@@ -0,0 +1,42 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { SecretUri } from "@parity/product-lab/domain";
+import { DevAccountSource } from "./dev-account-source.js";
+import { EnvSource } from "./env-source.js";
+import { SecretSource } from "./secret-source.js";
+export { SecretSource } from "./secret-source.js";
+export function devAccount(uri) {
+    if (!uri.startsWith("//") || !developmentAccount(uri))
+        throw new Error('devAccount expects a development derivation such as "//Alice"');
+    return new DevAccountSource(uri);
+}
+function developmentAccount(uri) {
+    try {
+        return SecretUri.parse(uri).developmentAccount;
+    }
+    catch {
+        return false;
+    }
+}
+export function fromEnv(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        throw new Error(`Invalid environment variable name: ${name}`);
+    return new EnvSource(name);
+}
+export function isSecretSource(value) {
+    return value instanceof SecretSource;
+}
+export function selectSecretSource(entry, environment) {
+    if (isSecretSource(entry))
+        return entry;
+    return (entry[environment.id] ?? entry[environment.local ? "local" : "remote"] ?? entry.default);
+}
+export function secretEntryErrors(name, entry) {
+    if (isSecretSource(entry))
+        return [];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return [`Secret "${name}" must be devAccount(…), fromEnv(…) or a record of them`];
+    return Object.entries(entry)
+        .filter(([, source]) => !isSecretSource(source))
+        .map(([key]) => `Secret "${name}" entry "${key}" must be devAccount(…) or fromEnv(…)`);
+}

package/core/application/src/orchestration/services/authority-error.d.ts

@@ -0,0 +1,7 @@
+import { ServiceError } from "./service-error.js";
+/** The service was verified and rejected (for example its signer is not `Sudo.Key`). */
+export declare class AuthorityError extends ServiceError {
+    constructor(service: string, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/core/application/src/orchestration/services/authority-error.js

@@ -0,0 +1,9 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { ServiceError } from "./service-error.js";
+export class AuthorityError extends ServiceError {
+    constructor(service, message, options) {
+        super(service, message, options);
+        this.name = "AuthorityError";
+    }
+}

package/core/application/src/orchestration/services/authorized-service.d.ts

@@ -0,0 +1,54 @@
+import type { SecretSigner } from "../secrets/secret-resolver.js";
+import { type ServiceContext, type ServiceDefinition, type ServiceLifetime } from "./define.js";
+export type AuthorizedServiceContext<Environment> = ServiceContext<Environment> & {
+    /** The signer resolved from the declared secret, on the orchestration side. */
+    readonly signer: SecretSigner;
+};
+/** `true`/nothing accepts; `false` or a reason string rejects. Throwing also rejects. */
+export type AuthorityVerdict = void | boolean | string;
+export interface AuthorizedServiceDefinition<T, Environment = unknown> {
+    /** Name of the lab secret holding this service's key (`secrets: { [name]: … }` in lab.config). */
+    readonly secret: string;
+    /** Default `environment`: one instance per environment generation. */
+    readonly lifetime?: ServiceLifetime;
+    readonly dependsOn?: readonly string[];
+    /** SS58 prefix for the signer's address (default 42). */
+    readonly ss58Prefix?: number;
+    /** What errors call this service, before its id (default `Service`), e.g. `Funder` or `Operator`. */
+    readonly label?: string;
+    /** Build the privileged service around the signer. Do not submit anything here. */
+    create(context: AuthorizedServiceContext<Environment>): T | Promise<T>;
+    /**
+     * Prove the signer actually holds the authority this service needs, for
+     * example that it equals the chain's `Sudo.Key`. Mandatory: funding or
+     * naming a signer never grants authority. Runs before `prepare` and before
+     * any consumer receives the service.
+     */
+    verifyAuthority(value: T, context: AuthorizedServiceContext<Environment>): AuthorityVerdict | Promise<AuthorityVerdict>;
+    /** One-time privileged preparation, only after authority is verified (for example configuring on-chain parameters). */
+    prepare?(value: T, context: AuthorizedServiceContext<Environment>): void | Promise<void>;
+    dispose?(value: T, context: ServiceContext<Environment>): void | Promise<void>;
+}
+/**
+ * The authorized-service pattern: an integration-owned privileged service that
+ * receives its signer from a lab secret and must pass `verifyAuthority` before
+ * use. The framework itself holds no privileged role; an integration that needs
+ * one declares it, and an integration that does not simply omits it.
+ *
+ * Failure modes, each a clear error naming the service and secret:
+ * - the secret is undeclared, unset, or a `devAccount` on a non-local environment (`SecretError`, wrapped);
+ * - `verifyAuthority` rejects (`AuthorityError`); the value is disposed and `prepare` never runs.
+ */
+export declare function defineAuthorizedService<T, Environment = unknown>(definition: AuthorizedServiceDefinition<T, Environment>): ServiceDefinition<T, Environment>;
+/**
+ * Compare an expected authority account with the one a chain reports.
+ * `normalise` maps an address to a comparable form (for example its public key
+ * bytes as hex, so different SS58 prefixes compare equal).
+ */
+export declare function expectAuthority(options: {
+    /** What was read, for the message, e.g. "People Sudo.Key". */
+    label: string;
+    expected: string;
+    actual: string | undefined | null;
+    normalise?: (address: string) => string;
+}): true | string;

package/core/application/src/orchestration/services/authorized-service.js

@@ -0,0 +1,59 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { AuthorityError, ServiceError, defineService, } from "./define.js";
+export function defineAuthorizedService(definition) {
+    if (!definition.secret)
+        throw new Error("defineAuthorizedService requires the name of a secret");
+    if (typeof definition.verifyAuthority !== "function")
+        throw new Error("defineAuthorizedService requires verifyAuthority(): privileged services must prove their authority");
+    const label = definition.label ?? "Service";
+    return defineService({
+        lifetime: definition.lifetime ?? "environment",
+        dependsOn: definition.dependsOn,
+        privileged: { secret: definition.secret },
+        async init(context) {
+            let signer;
+            try {
+                signer = await context.secrets.signer(definition.secret, { ss58Prefix: definition.ss58Prefix });
+            }
+            catch (error) {
+                throw new ServiceError(context.id, `${label} ${context.id} cannot obtain its signer: ${error.message}`, { cause: error });
+            }
+            const privileged = { ...context, signer };
+            const value = await definition.create(privileged);
+            let verdict;
+            try {
+                verdict = await definition.verifyAuthority(value, privileged);
+            }
+            catch (error) {
+                verdict = error instanceof Error ? error.message : String(error);
+            }
+            if (verdict === false || typeof verdict === "string") {
+                await definition.dispose?.(value, context);
+                throw new AuthorityError(context.id, `${label} ${context.id} is not authorised: signer ${signer.address} from secret "${definition.secret}" failed verification: ${typeof verdict === "string" ? verdict : "verifyAuthority returned false"}`);
+            }
+            try {
+                await definition.prepare?.(value, privileged);
+            }
+            catch (error) {
+                await definition.dispose?.(value, context);
+                throw error;
+            }
+            return value;
+        },
+        dispose: definition.dispose,
+    });
+}
+export function expectAuthority(options) {
+    const normalise = options.normalise ?? ((address) => address);
+    if (!options.actual)
+        return `${options.label} is not set; expected ${options.expected}`;
+    try {
+        if (normalise(options.actual) === normalise(options.expected))
+            return true;
+    }
+    catch (error) {
+        return `${options.label} could not be compared: ${error.message}`;
+    }
+    return `${options.label} is ${options.actual}, not ${options.expected}`;
+}

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

@@ -0,0 +1,61 @@
+import type { SentenceScenarioContext } from "@parity/product-lab/ports/lab";
+import type { SecretResolver } from "../secrets/secret-resolver.js";
+export { AuthorityError } from "./authority-error.js";
+export { ServiceError } from "./service-error.js";
+export { StaleGenerationError } from "./stale-generation-error.js";
+/**
+ * How long one service instance lives.
+ * - `environment`: once per environment generation; disposed on reset and close.
+ * - `actor`: once per actor per generation; disposed when the actor stops or is deleted.
+ * - `scenario`: once per scenario run (per scope); disposed after the run.
+ */
+export type ServiceLifetime = "environment" | "actor" | "scenario";
+export declare const LIFETIME_RANK: Record<ServiceLifetime, number>;
+export interface ServiceLookup {
+    /** An initialised dependency, by the name used in `dependsOn`. */
+    get<T = unknown>(name: string): T;
+}
+export interface ServiceContext<Environment = unknown> {
+    /** Fully qualified service id, for example `ledger.operator`. */
+    readonly id: string;
+    readonly lifetime: ServiceLifetime;
+    /** Environment generation; a reset starts a new one. */
+    readonly generation: number;
+    /** The running environment handed to services (endpoints, offer, provider handle). */
+    readonly environment: Environment;
+    /** Orchestration-side secrets for the current environment. */
+    readonly secrets: SecretResolver;
+    /** Declared dependencies only. */
+    readonly services: ServiceLookup;
+    readonly actor?: {
+        readonly id: string;
+    };
+    readonly scenario?: {
+        readonly id: string;
+    } & Partial<Omit<SentenceScenarioContext, "id">>;
+    readonly signal: AbortSignal;
+}
+export interface ServiceDefinition<T = unknown, Environment = unknown> {
+    readonly lifetime: ServiceLifetime;
+    /** Services this one needs, initialised first. Names are local to the integration or `integration.service`. */
+    readonly dependsOn?: readonly string[];
+    init(context: ServiceContext<Environment>): T | Promise<T>;
+    /**
+     * Checked after `init` and before any consumer receives the value. Return
+     * nothing (or `true`) to accept; return `false` or a reason string, or throw,
+     * to reject. A rejected value is disposed and initialisation fails.
+     */
+    verify?(value: T, context: ServiceContext<Environment>): void | boolean | string | Promise<void | boolean | string>;
+    dispose?(value: T, context: ServiceContext<Environment>): void | Promise<void>;
+    /** Set by `defineAuthorizedService`: the service holds privileged authority from this secret. */
+    readonly privileged?: {
+        readonly secret: string;
+    };
+}
+export declare function defineService<T, Environment = unknown>(definition: ServiceDefinition<T, Environment>): ServiceDefinition<T, Environment>;
+/**
+ * Static graph validation: unknown dependencies, lifetime violations (a
+ * longer-lived service may not depend on a shorter-lived one) and cycles.
+ * `resolve` maps a declared dependency name to a qualified id.
+ */
+export declare function serviceGraphErrors(services: Readonly<Record<string, ServiceDefinition<unknown, never>>>, resolve?: (from: string, name: string) => string): string[];

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

@@ -0,0 +1,49 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { AuthorityError } from "./authority-error.js";
+export { ServiceError } from "./service-error.js";
+export { StaleGenerationError } from "./stale-generation-error.js";
+export const LIFETIME_RANK = { environment: 0, actor: 1, scenario: 2 };
+export function defineService(definition) {
+    if (!["environment", "actor", "scenario"].includes(definition.lifetime))
+        throw new Error(`Unknown service lifetime: ${String(definition.lifetime)}`);
+    if (typeof definition.init !== "function")
+        throw new Error("defineService requires init()");
+    return definition;
+}
+export function serviceGraphErrors(services, resolve = (_from, name) => name) {
+    const errors = [];
+    for (const [id, service] of Object.entries(services)) {
+        if (!["environment", "actor", "scenario"].includes(service.lifetime))
+            errors.push(`Service ${id} has unknown lifetime ${String(service.lifetime)}`);
+        for (const name of service.dependsOn ?? []) {
+            const target = resolve(id, name);
+            const dependency = services[target];
+            if (!dependency) {
+                errors.push(`Service ${id} depends on unknown service ${name}`);
+                continue;
+            }
+            if (LIFETIME_RANK[dependency.lifetime] > LIFETIME_RANK[service.lifetime])
+                errors.push(`Service ${id} (${service.lifetime}) cannot depend on ${target} (${dependency.lifetime}): a longer-lived service cannot hold a shorter-lived one`);
+        }
+    }
+    const state = new Map();
+    const visit = (id, path) => {
+        if (state.get(id) === "done")
+            return;
+        if (state.get(id) === "visiting") {
+            errors.push(`Service dependency cycle: ${[...path.slice(path.indexOf(id)), id].join(" -> ")}`);
+            return;
+        }
+        state.set(id, "visiting");
+        for (const name of services[id]?.dependsOn ?? []) {
+            const target = resolve(id, name);
+            if (services[target])
+                visit(target, [...path, id]);
+        }
+        state.set(id, "done");
+    };
+    for (const id of Object.keys(services))
+        visit(id, []);
+    return errors;
+}

package/core/application/src/orchestration/services/service-container.d.ts

@@ -0,0 +1,85 @@
+import type { SentenceScenarioContext } from "@parity/product-lab/ports/lab";
+import type { SecretResolver } from "../secrets/secret-resolver.js";
+import { type ServiceDefinition, type ServiceLifetime } from "./define.js";
+export interface ServiceContainerOptions<Environment> {
+    /** Qualified id → definition. */
+    services: Readonly<Record<string, ServiceDefinition<unknown, Environment>>>;
+    /** Map a declared dependency name to a qualified id (default: identity). */
+    resolve?: (from: string, name: string) => string;
+    environment: Environment;
+    secrets: SecretResolver;
+}
+/** A view onto services for one lifetime scope. */
+export interface ServiceScope {
+    readonly generation: number;
+    readonly lifetime: ServiceLifetime;
+    /** Initialise (once per lifetime) and return a service by qualified id. */
+    get<T = unknown>(id: string): Promise<T>;
+    /** Release the scope's own instances. Longer-lived instances stay. */
+    dispose(): Promise<void>;
+}
+/** One scenario owner with actor-specific views sharing its scenario instances. */
+export interface ScenarioServiceScope extends ServiceScope {
+    /** Select the calling actor without binding shared service initialization to it. */
+    forActor(actorId: string): ServiceScope;
+}
+/**
+ * Dependency injection with lifetimes and generations. Instances initialise
+ * lazily and at most once per lifetime scope (concurrent requests share one
+ * initialisation); `start()` eagerly initialises every environment-lifetime
+ * service so authority checks fail at startup, not mid-scenario. `reset()`
+ * disposes everything in reverse initialisation order (scenario, then actor,
+ * then environment instances) and starts a new generation; scopes from the old
+ * generation then refuse to resolve.
+ */
+export declare class ServiceContainer<Environment = unknown> {
+    #private;
+    constructor(options: ServiceContainerOptions<Environment>);
+    get generation(): number;
+    get environment(): Environment;
+    /** Ids in dependency order (dependencies first). */
+    order(lifetime?: ServiceLifetime): string[];
+    /** Eagerly initialise environment-lifetime services (all, or the listed ids and their dependencies). */
+    start(ids?: readonly string[]): Promise<void>;
+    /** The environment-lifetime scope of the current generation. */
+    environmentScope(): ServiceScope;
+    /** The scope for one actor in the current generation (created on first use). */
+    actor(actorId: string): ServiceScope;
+    /** A new scenario scope. Each call is one scenario run; dispose it (or call `endScenarios`) afterwards. */
+    scenario(options?: {
+        actor?: string;
+        id?: string;
+        context?: SentenceScenarioContext;
+    }): ScenarioServiceScope;
+    /** Ids and lifetimes of live instances (for evidence and tests). */
+    live(): {
+        id: string;
+        lifetime: ServiceLifetime;
+        generation: number;
+        actor?: string;
+        scenario?: string;
+    }[];
+    /** Dispose every open scenario scope. */
+    endScenarios(): Promise<void>;
+    /** Dispose one actor's instances (actor stopped or deleted). Open scenario scopes for that actor end too. */
+    releaseActor(actorId: string): Promise<void>;
+    /**
+     * Dispose every instance and begin a new generation. Pass the new
+     * environment handle / secrets when the environment was rebuilt.
+     */
+    reset(next?: {
+        environment?: Environment;
+        secrets?: SecretResolver;
+    }): Promise<number>;
+    /**
+     * Replace the environment handle and secrets for the current generation.
+     * Only allowed while no instance is live (right after `reset()`), so no
+     * service ever sees two environments.
+     */
+    rebind(next: {
+        environment?: Environment;
+        secrets?: SecretResolver;
+    }): void;
+    /** Dispose everything; the container cannot be used afterwards. */
+    dispose(): Promise<void>;
+}