@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/ports/src/driving/feature-session.d.ts

@@ -0,0 +1,269 @@
+import type { SideReading } from "@parity/product-lab/domain/checks";
+import type { ActorSession, AgreementSummary, PlanIssue, RecordedOutput, SentenceKind, UnmetCondition } from "@parity/product-lab/domain";
+import type { AppSurface } from "../driven/browser/app-surface.js";
+import type { StepOutputs } from "../driven/lab/lab-sentences.js";
+import type { FixturePolicy, ScenarioFixtureReport, ScenarioIsolationReport } from "./fixtures.js";
+/** A sentence as a step-definition generator sees it. */
+export interface SentenceView {
+    readonly pattern: string;
+    readonly owner: string;
+    readonly kind: SentenceKind;
+    /** The anchored regular expression steps match (source, no flags). */
+    readonly regex: string;
+    /** How many values the expression captures. */
+    readonly parameters: number;
+    /** The pattern ends with ":" and takes a DataTable. */
+    readonly takesTable: boolean;
+    /** The table header a fitting table uses. */
+    readonly table?: string;
+}
+/** A step as the feature file writes it: its text and its DataTable (header first). */
+export interface FeatureStepInput {
+    readonly text: string;
+    readonly table?: readonly (readonly string[])[];
+    /** Backlog 113: the step's doc string (`these steps run together:` takes its parts as one). */
+    readonly docString?: string;
+}
+/**
+ * Race hunting (backlog 32): before each step an identity takes, a wait drawn from a seed, so the actors interleave
+ * differently from seed to seed. One actor's steps keep their order; a seed gives the same waits again.
+ */
+export interface RaceRequest {
+    /** Up to 8 hex digits: the run's seed. Each scenario's own seed is drawn from it and where the scenario was written. */
+    readonly seed: string;
+    /** The longest wait before a step, in milliseconds (default 300, at most 60000). */
+    readonly maxMs?: number;
+    /** `seed` is one scenario's own (reproducing its recording), used as it is. */
+    readonly exact?: boolean;
+}
+export interface FeatureSessionOptions {
+    /**
+     * `fresh` (default, CI): identity sentences create new identities, removed
+     * when the scenario ends. `manual`: scenario actors may be bound to saved
+     * identities first; identities the scenario creates are kept.
+     */
+    readonly binding?: "fresh" | "manual";
+    /** The app surface an actor's calls use (the visible lab window's iframe); none: the integration's own page. */
+    surface?(actorId: string): AppSurface | undefined;
+    /**
+     * What the visible surfaces can condition (backlog 31), by scenario actor, read before the run: `unavailable` names
+     * the kinds a surface cannot apply, with why. Absent, or undefined for an actor, with `surface` given: they cannot.
+     */
+    surfaceConditions?(actor: string): {
+        readonly unavailable?: {
+            readonly network?: string;
+            readonly cpu?: string;
+        };
+    } | undefined;
+    /** What a scenario naming a fixture does when nothing fitting is saved (default `restore`: refuse with the reasons). */
+    readonly fixtures?: FixturePolicy;
+    /** Race hunting: every scenario begun waits before its identities' steps (recorded with it). */
+    readonly race?: RaceRequest;
+    /**
+     * The fixture whose setup this session runs (8 October 2026). A step that would create a person is refused at plan,
+     * before anything runs, when the running session keeps its people in memory only (no fixtureState): a fixture saved
+     * from it could not act as them. A setup that makes no people runs and saves as before.
+     */
+    readonly fixtureSetup?: string;
+}
+export interface BeginScenarioRequest {
+    readonly name: string;
+    readonly steps: readonly FeatureStepInput[];
+    /** True when a custom `step()` definition runs this text (it is then not planned). */
+    readonly custom?: (text: string) => boolean;
+    /** Manual binding: scenario actor name -> saved identity (actor session id). */
+    readonly bindings?: Readonly<Record<string, string>>;
+    /**
+     * The host each new actor is created on, by actor name: one the lab declares. A step that names its actor's host
+     * (`{actor} is a new actor on the {string} host`) sets it; a different one here refuses the scenario.
+     */
+    readonly hosts?: Readonly<Record<string, string>>;
+    /**
+     * The scenario's effective tags (feature, Rule, scenario, Examples block). `@fixture:<name>` (backlog 1b): the
+     * fixture is restored before planning, and the scenario's actors of the fixture's identities are bound to them by
+     * name (in either binding mode; they are never removed when the scenario ends). An undeclared fixture, one saved for
+     * another environment, or a missing or stale one (unless the session rebuilds) refuses the scenario with every reason.
+     */
+    readonly tags?: readonly string[];
+    /**
+     * Where the scenario's `@fixture-shared` tag was written (its feature or Rule; any id unique to that place): the
+     * scenarios of one group naming the same fixture, run one after another, share the restore made before the first.
+     */
+    readonly fixtureGroup?: string;
+    /**
+     * Where the scenario was written (backlog 20, 3 October 2026): its feature file as the runner names it (relative to
+     * the lab) and the line of the scenario, or of its Examples row. Its recording carries it, so it can be bundled.
+     */
+    readonly source?: {
+        readonly uri: string;
+        readonly line?: number;
+    };
+    /**
+     * Outputs recorded before this scenario that belong to its world, oldest first (backlog 21: a "what if" branch starts
+     * with its trunk's, an end check with its branch's): its references and an assertion's `outputs` see them.
+     */
+    readonly outputs?: readonly RecordedOutput[];
+}
+/** One atomic call of a step, as it ran. */
+export interface FeatureCallTrace {
+    readonly owner: string;
+    readonly kind: SentenceKind;
+    readonly text: string;
+    /** The text with output references replaced by their values (only when it has references). */
+    readonly resolved?: string;
+    /** Where it came from, outermost first: `step group "…"`, `repeat 2/5 "…"`. */
+    readonly origin: readonly string[];
+    readonly actor?: string;
+    /** The call acted as the setup principal (a sentence declared to act as no actor): no identity, account or app. */
+    readonly setup?: true;
+    /**
+     * Which block the action or assertion declared its chain reads rest on (backlog 14): `finalized` (chain truth) or
+     * `best` (inclusion). Absent for calls that read no chain of their own (identities, navigation, time).
+     */
+    readonly reads?: "finalized" | "best";
+    /** The chain waits the call made through the lab's connections, each with the head it read (`StepEvidence.chainWaits`). */
+    readonly chainWaits?: readonly {
+        label: string;
+        head: "finalized" | "best";
+        status: "waiting" | "complete" | "failed";
+        ms: number;
+        block?: number;
+    }[];
+    /**
+     * The checks of a screen against the chain the call made (`checkUiAgainstChain`), in short: the mode that applied
+     * (pinned, eventual or optimistic) and how agreement was reached, or why not. The whole record of each is in the
+     * step's evidence (`StepEvidence.attached.uiChainAgreements`).
+     */
+    readonly agreements?: readonly AgreementSummary[];
+    /**
+     * Backlog 186: what the call's checks read on each side (`StepEvidence` readings, backlog 160), so a report outside the
+     * lab window says the same "screen ✓ · chain ✓ People #14" (`stepSidesWords`).
+     */
+    readonly readings?: readonly SideReading[];
+    /** Why no screen can show what the call changed, as its action declares it (`screenCheck.none`). */
+    readonly screenNotShown?: string;
+    /** The call changes nothing (`mutates: false`): it has no chain check to make. */
+    readonly changesNothing?: true;
+    /** Direct app traffic and finalized transaction accounting, including policies and every coverage gap. */
+    readonly hostBypass?: import("@parity/product-lab/domain").HostBypassEvidence;
+    readonly status: "complete" | "failed" | "skipped";
+    /**
+     * Backlog 35c: what a new actor with no funds holds, read right after it was created at each chain's finalized head
+     * (free balance in planck). Every one is 0, or the call failed.
+     */
+    readonly funds?: readonly {
+        readonly chain: string;
+        readonly account: string;
+        readonly block: number;
+        readonly hash: string;
+        readonly free: string;
+    }[];
+    /** Outputs the call published. */
+    readonly outputs?: Readonly<Record<string, string | number>>;
+    /**
+     * Its new actors were created ahead of the step, together with the new actors of the steps around it (one environment
+     * operation, as many at once as the environment allows): the names created together, when that creation started, and
+     * when this call's own actors were ready (wall-clock ms). The step waited only for its own.
+     */
+    readonly provisioned?: {
+        readonly with: readonly string[];
+        readonly startedAt: number;
+        readonly readyAt: number;
+    };
+    /** When the call's run step started and finished (wall-clock ms): calls that ran together overlap here. */
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    /** Why it failed. */
+    readonly error?: string;
+    /** Additional abort diagnostics for display only; not part of failure classification or control matching. */
+    readonly abortDetail?: string;
+    /** In a run-together group: the earlier calls of the group it waited for and the resources they shared (they did not overlap). */
+    readonly waitsFor?: readonly {
+        readonly call: string;
+        readonly resources: readonly string[];
+    }[];
+    /** Backlog 113: `waitsFor` in words, so a call that did not overlap says why ("ran in turn after "…": both hold …"). */
+    readonly ranInTurn?: string;
+}
+export interface FeatureStepTrace {
+    readonly index: number;
+    readonly text: string;
+    /** The runtime runs the step's calls executed as, in order (none for identity-only steps). */
+    readonly runs: readonly string[];
+    readonly calls: readonly FeatureCallTrace[];
+    /** Backlog 40: what the step's visual and accessibility checks found (a new baseline, a pass, a failure), when the scenario runs them. */
+    readonly checks?: readonly string[];
+    /** Backlog 35b: how a `{actor} is <character>` step was met when the scenario's fixture prepares that character. */
+    readonly character?: CharacterStepTrace;
+    /**
+     * How long the step waited, before its calls ran, for new actors still being created ahead of earlier steps (the
+     * environment does one operation at a time): absent when nothing was being created.
+     */
+    readonly waitedForActorsMs?: number;
+}
+/**
+ * Backlog 35b: a character step in a scenario that started from a fixture preparing the character. `prepared`: the
+ * actor was bound to the fixture's identity (its account and data, its username where it has one) and no step ran;
+ * absent: the character's steps ran, and `note` says why no prepared identity was used.
+ */
+export interface CharacterStepTrace {
+    readonly character: string;
+    readonly actor: string;
+    readonly prepared?: {
+        readonly fixture: string;
+        readonly identity: string;
+    };
+    readonly note: string;
+}
+/** A planned scenario whose steps run one at a time, in order. */
+/** How a scenario ended, as its runner saw it. */
+export interface FeatureScenarioOutcome {
+    readonly status: "passed" | "failed" | "skipped";
+    /** Where it failed: the Gherkin step (0-based index, -1 for a hook), its text and the error. */
+    readonly failure?: {
+        readonly step: number;
+        readonly text: string;
+        readonly error: string;
+    };
+}
+export interface FeatureScenarioHandle {
+    readonly name: string;
+    /** Run step `index` once (a custom step is run by its own definition, not here). */
+    run(index: number): Promise<FeatureStepTrace>;
+    /** The identity a scenario actor is bound to. */
+    actor(name: string): ActorSession;
+    /** The scenario's outputs so far. */
+    readonly outputs: StepOutputs;
+    /** Every output recorded so far, oldest first, the ones it began with included (to begin another scenario from). */
+    recorded?(): readonly RecordedOutput[];
+    /** What ran so far. */
+    trace(): readonly FeatureStepTrace[];
+    /**
+     * Release the scenario: its fresh identities and scenario services. The runner may say how the scenario ended
+     * (backlog 20): its recording then holds a failure outside the lab's runs (a custom step, a hook) too.
+     */
+    end(outcome?: FeatureScenarioOutcome): Promise<void>;
+    /** How the scenario started from the fixture its tags name (restore time included); absent when it names none. */
+    readonly fixture?: ScenarioFixtureReport;
+    /**
+     * How an `@isolated` scenario's start state was kept for it, when this session lent it (in-process runs: the lab
+     * window, `fixture run`, MCP); absent when the Cucumber hooks lent it, which say so themselves (lane speed, 7 October 2026).
+     */
+    readonly isolation?: ScenarioIsolationReport;
+}
+/** Thrown by `begin` when the plan has issues; nothing ran. */
+export interface FeaturePlanFailure extends Error {
+    readonly issues: readonly PlanIssue[];
+}
+export interface FeatureSession {
+    /** The loaded lab's sentences: the framework's generic ones and every integration's. */
+    sentences(): SentenceView[];
+    /**
+     * The tags of a scenario that do not fit the running environment (its integrations' scenario conditions, read
+     * once per environment session): a Cucumber run skips such a scenario before planning it. Empty when every tag
+     * fits, when the environment declares no conditions, or when they cannot be read (unknown is never "does not fit").
+     */
+    notFor?(tags: readonly string[]): Promise<readonly UnmetCondition[]>;
+    /** Plan a scenario against the running environment; rejects with a FeaturePlanFailure listing every issue. */
+    begin(request: BeginScenarioRequest): Promise<FeatureScenarioHandle>;
+}

package/core/ports/src/driving/feature-session.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/core/ports/src/driving/features.d.ts

@@ -0,0 +1,260 @@
+import type { FeatureFile, FeatureScenario, FeatureStep, PlanIssue, ScenarioNeeds, UnmetCondition } from "@parity/product-lab/domain";
+import type { AppSurface } from "../driven/browser/app-surface.js";
+import type { FeatureGateStep, FeatureScenarioResult } from "../driven/features/feature-runner.js";
+import type { RaceRequest } from "./feature-session.js";
+import type { FixturePolicy } from "./fixtures.js";
+import type { JudgedFailure } from "@parity/product-lab/domain";
+import type { ControlVerdict, FailedStepInput } from "./reports.js";
+/** A parsed feature file (the domain's `FeatureFile`). */
+export type FeatureFileView = Omit<FeatureFile, "scenarios"> & {
+    scenarios: FeatureScenarioView[];
+};
+export type FeatureScenarioView = FeatureScenario & {
+    inspection?: FeatureScenarioInspection;
+};
+/** Declared requirements, never a promise that a runtime or custom support code will succeed. */
+export interface FeatureScenarioInspection {
+    environment: string;
+    source: "declared" | "running";
+    coverage: "complete" | "partial" | "unknown";
+    availability: "available" | "unavailable" | "unknown";
+    integrations: string[];
+    requires: {
+        chains: string[];
+        services: string[];
+        capabilities: string[];
+    };
+    reasons: string[];
+    /** Custom/unmatched steps are not imported or executed to inspect their requirements. */
+    unchecked: {
+        text: string;
+        example?: number;
+    }[];
+    issues: (PlanIssue & {
+        example?: number;
+    })[];
+    /**
+     * Tags of the scenario that do not fit the running environment, with the integration's reason ("not for this
+     * chain"): a run refuses it before anything starts. Only with `source: "running"` once the environment's scenario
+     * conditions were read; absent while nothing runs (unknown, never "does not fit") or when every tag fits.
+     */
+    notFor?: UnmetCondition[];
+    /**
+     * An outline's Examples blocks whose own tags do not fit the running environment (29 September 2026): the block
+     * (its index in `examplesBlocks`, name and line) and each of its unfit tags with the integration's reason. A run
+     * leaves those rows out (a row's tags include its block's) and runs the rest; when every block is listed, nothing
+     * of the outline runs here. Only tags the scenario's own `notFor` does not name; absent while the conditions are
+     * unknown or when every block fits.
+     */
+    examplesNotFor?: ExamplesNotFor[];
+    /**
+     * Backlog 163-165: where it runs, when its tags or actions say (`@environment:<id>`, `@live-network`, `@root-calls`,
+     * an action with `rootCalls`): every declared environment it fits, in declaration order (empty: none this lab
+     * declares), whether the inspected environment is one, and why not. Known from the declarations, running or not;
+     * absent when it runs anywhere.
+     */
+    runsOn?: ScenarioRunsOn;
+}
+/** Where a scenario runs (`FeatureScenarioInspection.runsOn`). */
+export interface ScenarioRunsOn {
+    needs: ScenarioNeeds;
+    /** The declared environments it fits. */
+    environments: string[];
+    /** Of those, the live ones (a lab window never switches to one: it runs local environments). */
+    live: string[];
+    /** It fits the inspected environment. */
+    here: boolean;
+    /** Why it does not fit the inspected environment ("Not for fast: live network only: … (@live-network)"). */
+    reason?: string;
+}
+/** One Examples block that does not fit the running environment (`FeatureScenarioInspection.examplesNotFor`). */
+export interface ExamplesNotFor {
+    block: number;
+    name: string;
+    line: number;
+    notFor: UnmetCondition[];
+}
+export interface FeatureListRequest {
+    read?: boolean;
+    configuration?: string;
+    /** Inspect declared sentences for the running environment, else the declared default; no environment starts. */
+    inspect?: boolean;
+}
+export type FeatureStepView = FeatureStep;
+/** The lab's feature files: its declared globs, else every .feature under its directory. */
+export interface FeatureListing {
+    source: "lab.config.ts features" | "discovered (lab.config.ts declares no features)";
+    /** Relative to the lab's directory. */
+    paths: string[];
+    /** Parsed, each step matched against the registered sentences (only with `read`). */
+    features: FeatureFileView[];
+    /** The runner configuration feature runs use (the one asked for when it exists, else the conventional file next to lab.config.ts); null when there is none. */
+    configuration: string | null;
+}
+export interface RunFeaturesRequest {
+    /** Feature files (relative to the lab's directory or absolute inside it); each must be one of the lab's, optionally with `:line[:line]` (Cucumber's selection by scenario or Examples row line). Empty: the configuration's own selection. */
+    paths?: readonly string[];
+    tags?: string;
+    name?: string;
+    /** Exported to the run as PRODUCT_LAB_ENVIRONMENT; must be configured, and local unless the runtime allows public environments. */
+    environment?: string;
+    /** The runner configuration; default: the conventional file next to lab.config.ts. */
+    configuration?: string;
+    /** Where the run keeps its output: exactly here, or under `runsDirectory` in a folder named after the run id. */
+    directory?: string;
+    runsDirectory?: string;
+    /** The machine-readable report (default `<directory>/cucumber.json`). */
+    report?: string;
+    dryRun?: boolean;
+    /** Judge the run as a negative control (JudgeNegativeControl), optionally at an expected step and error marker. */
+    control?: {
+        expected?: {
+            step?: string;
+            marker?: string;
+            atStep?: number;
+            reason?: string;
+        };
+    };
+    /** Backlog 38 (`product-lab test --mutate`): the paths may also be mutant copies of the lab's features under `.product-lab/mutants/`. */
+    mutants?: boolean;
+    /**
+     * A run in which every selected scenario was skipped (not for this chain) fails instead of passing (`product-lab
+     * test`). A run in which no scenario ran at all (its selection matched none) always fails, whatever this says.
+     */
+    requireScenarios?: boolean;
+    /** Extra environment variables for the run. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** A label for the run id (default `feature`). */
+    label?: string;
+    /**
+     * Scenarios naming a fixture (`@fixture:<name>`): `restore` (default) restores a saved one that fits and refuses a
+     * missing or stale one with its reasons; `rebuild` runs its setup and saves it first (backlog 1b).
+     */
+    fixtures?: FixturePolicy;
+    /** Race hunting (backlog 32): the run's scenarios wait before their identities' steps, drawn from this seed. */
+    race?: RaceRequest;
+    /**
+     * Run in this process against the environment that runs (Phase 4, the manual panel), through the same Cucumber and
+     * generated steps: scenario actors bound to saved identities by name (the rest get new identities), a pause gate
+     * after each step, and the visible lab window's surface for the actor it shows.
+     */
+    inProcess?: {
+        bindings?: Readonly<Record<string, string>>;
+        /** The fixture whose setup this run is (`FeatureSessionOptions.fixtureSetup`): `product-lab fixture save`, Build. */
+        fixtureSetup?: string;
+        /** The host each new scenario actor is created on, by actor name: one the lab declares (default: the lab's default host). */
+        hosts?: Readonly<Record<string, string>>;
+        /** Pause after every step (step through); `pause()` pauses after the current one either way. */
+        pauseAfterStep?: boolean;
+        /** Phase 5 (the builder's checkpoints): pause after these 0-based steps of the named scenario. */
+        checkpoints?: Readonly<Record<string, readonly number[]>>;
+        /**
+         * Backlog 17: pause before each step the lab's saved breakpoints name in the selected scenarios (`LabBreakpoints`);
+         * the run's record reports each one (`FeatureRunRecord.breakpoints`), hit or not. Default false (fixture builds and
+         * other unattended runs never stop).
+         */
+        breakpoints?: boolean;
+        surface?(actorId: string): AppSurface | undefined;
+        /** What those surfaces can condition, by scenario actor (`FeatureSessionOptions.surfaceConditions`). */
+        surfaceConditions?(actor: string): {
+            readonly unavailable?: {
+                readonly network?: string;
+                readonly cpu?: string;
+            };
+        } | undefined;
+    };
+}
+/**
+ * Where an in-process run waits, until `continue`: after a finished step, or (a breakpoint, backlog 17) before a step
+ * runs, with `before` set and `status` `pending`.
+ */
+export interface FeatureCheckpoint extends FeatureGateStep {
+    reason: "requested" | "after-each-step" | "checkpoint" | "breakpoint";
+    before?: boolean;
+}
+/** A saved breakpoint as one in-process run applied it, and what became of it (backlog 17). */
+export interface FeatureBreakpointState {
+    path: string;
+    scenario: string;
+    /** 0-based, Background steps first. */
+    index: number;
+    text: string;
+    line?: number;
+    /**
+     * `waiting` (not reached yet), `hit` (the run paused before the step), `missed` (the run ended without reaching it;
+     * `reason` says why), `stale` (the feature file changed since it was set; not applied).
+     */
+    state: "waiting" | "hit" | "missed" | "stale";
+    reason?: string;
+}
+export type FeatureRunStatus = "queued" | "running" | "passed" | "failed" | "error";
+export interface FeatureRunRecord {
+    id: string;
+    selection: {
+        paths: string[];
+        tags?: string;
+        name?: string;
+        environment?: string;
+    };
+    status: FeatureRunStatus;
+    startedAt: number;
+    finishedAt?: number;
+    exitCode?: number;
+    error?: string;
+    /** Why a requested stop failed (the run's process or session may still be running); absent when every stop succeeded. */
+    stopError?: string;
+    /** Scenarios with their steps, as the report records them. */
+    scenarios: FeatureScenarioResult[];
+    /** Every step across the scenarios, numbered, hooks included (what ExplainFailure and JudgeNegativeControl read). */
+    steps: FailedStepInput[];
+    control?: {
+        verdict: ControlVerdict;
+        reason: string;
+        expected?: {
+            step?: string;
+            marker?: string;
+            atStep?: number;
+            reason?: string;
+        };
+        failure?: JudgedFailure;
+    };
+    directory: string;
+    report: string;
+    /** In this process (the manual panel) or in a process the runner owns. */
+    mode: "process" | "in-process";
+    /** In-process runs: the steps finished so far, in order. */
+    progress?: FeatureGateStep[];
+    /** In-process runs: pause after every step. */
+    pauseAfterStep?: boolean;
+    /** In-process runs: the step the run waits after (or, at a breakpoint, before). */
+    checkpoint?: FeatureCheckpoint;
+    /** In-process runs with `breakpoints`: every saved breakpoint of the selected scenarios and what became of it. */
+    breakpoints?: FeatureBreakpointState[];
+}
+/** A started (or queued) feature run. Runs of one runtime are serialized: each owns the ports its hooks use. */
+export interface FeatureRunHandle {
+    readonly id: string;
+    /** The live record, redacted. */
+    record(): FeatureRunRecord;
+    /** Resolves with the final record (redacted); never rejects. */
+    readonly completion: Promise<FeatureRunRecord>;
+    /** The run's output lines, redacted (empty while queued). */
+    tail(lines: number, filter?: string): {
+        lines: string[];
+        total: number;
+        file?: string;
+    };
+    /** Output as it arrives, redacted; returns the unsubscribe function. */
+    onOutput(listener: (chunk: string) => void): () => void;
+    /** Stop the run (a queued run never starts). */
+    stop(options?: {
+        signal?: "SIGINT" | "SIGTERM";
+        graceMs?: number;
+    }): Promise<void>;
+    /** In-process runs: pause after the current step. */
+    pause?(): void;
+    /** In-process runs: go on from the checkpoint; `pauseAfterStep` sets whether to pause after the next step too. */
+    continue?(options?: {
+        pauseAfterStep?: boolean;
+    }): void;
+}

package/core/ports/src/driving/features.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/core/ports/src/driving/fixture-maintenance.d.ts

@@ -0,0 +1,95 @@
+import type { EnvironmentRuntimeUpgrade } from "../driven/environment/running-environment.js";
+import type { DigestPart } from "@parity/product-lab/domain";
+import type { FixtureReport } from "./fixtures.js";
+/** One declared fixture against this checkout (setup, lab lock, declared inputs); nothing started. */
+export interface FixtureCheck {
+    readonly name: string;
+    readonly environment: string;
+    readonly setup: string;
+    /**
+     * `missing`: nothing saved. `fits-checkout`: its setup, lock and inputs are this checkout's (its runtimes and lineage
+     * are checked when its environment runs). `stale`: one of them changed (`reasons`); it needs `fixture refresh`.
+     */
+    readonly state: "missing" | "fits-checkout" | "stale";
+    readonly reasons: readonly string[];
+    /**
+     * The parts of its key this checkout decides, digested (backlog 1d): a CI cache keys the fixture's bundle by them, so
+     * a change to its setup, the lab lock, its declared inputs (the app's sources) or a fixture it is built on misses.
+     * Absent when its setup does not exist.
+     */
+    readonly checkout?: {
+        readonly setup?: DigestPart;
+        readonly lock: DigestPart;
+        readonly inputs?: DigestPart;
+        readonly base?: DigestPart;
+    };
+    readonly saved?: {
+        readonly createdAt: string;
+        readonly lineage: string;
+        readonly runtimes: Readonly<Record<string, string>>;
+        readonly history: readonly {
+            readonly action: string;
+            readonly at: string;
+        }[];
+    };
+}
+/** What a refresh of a saved fixture would do, with its environment running. */
+export type FixtureRefreshPlan = {
+    readonly kind: "fits";
+} | {
+    readonly kind: "missing";
+}
+/** Only its runtimes differ and the environment upgrades a restored state in place. */
+ | {
+    readonly kind: "upgrade";
+    readonly reasons: readonly string[];
+}
+/** Something an upgrade cannot change differs (`reasons`), or the environment cannot upgrade in place (`why`). */
+ | {
+    readonly kind: "rebuild";
+    readonly reasons: readonly string[];
+    readonly why: readonly string[];
+};
+/** An in-place refresh: the saved state restored, upgraded, checked and saved again under its new key. */
+export interface FixtureUpgradeReport {
+    readonly name: string;
+    readonly upgrade: EnvironmentRuntimeUpgrade;
+    /** The save under the new key. */
+    readonly report: FixtureReport;
+    readonly timings: {
+        readonly restoreMs: number;
+        readonly upgradeMs: number;
+        readonly totalMs: number;
+    };
+}
+/** A rebuild's fresh session: the saved fixture's session directories moved aside until the new fixture is saved. */
+export interface FixtureRebuild {
+    /** The directories moved aside (a fresh one is made by the next start). */
+    readonly directories: readonly string[];
+    /** The rebuilt fixture is saved: delete what was moved aside. */
+    commit(): void;
+    /** The rebuild failed: remove what was made meanwhile and put the originals back. */
+    rollback(): void;
+}
+export interface FixtureMaintenance {
+    /** Every declared fixture against this checkout; starts nothing. */
+    check(): Promise<FixtureCheck[]>;
+    /** What `refresh` would do for `name`: needs its environment running. */
+    plan(name: string): Promise<FixtureRefreshPlan>;
+    /**
+     * In place: restore the saved state, upgrade its runtimes through the environment (each checked on the chain), and
+     * save it again under the new key with an `upgraded` history entry. Refused unless `plan` says `upgrade`. Needs
+     * `snapshot().confirmations.restoreFixture`.
+     */
+    upgrade(request: {
+        name: string;
+        confirmation?: string;
+    }): Promise<FixtureUpgradeReport>;
+    /** Before a rebuild's start: move the saved fixture's session directories aside so the start makes fresh ones. The environment must not run. */
+    prepareRebuild(name: string): Promise<FixtureRebuild>;
+    /** After the setup passed again: save the running state with a `rebuilt` history entry naming why. */
+    saveRebuilt(request: {
+        name: string;
+        reasons: readonly string[];
+    }): Promise<FixtureReport>;
+}

package/core/ports/src/driving/fixture-maintenance.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export {};