@parity/product-lab 0.0.1-placeholder → 0.1.0

package/contracts/chain/src/runner.js

@@ -0,0 +1,156 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import assert from "node:assert/strict";
+import { before, describe, test } from "node:test";
+export class CheckFailed extends Error {
+    evidence;
+    constructor(message, evidence = {}) {
+        super(message);
+        this.evidence = evidence;
+        this.name = "CheckFailed";
+    }
+}
+export function expect(condition, message, evidence = {}) {
+    if (!condition)
+        throw new CheckFailed(message, evidence);
+}
+const message = (error) => (error instanceof Error ? error.message : String(error));
+export function evidenceJson(value) {
+    return JSON.stringify(value, (_key, item) => typeof item === "bigint"
+        ? item.toString()
+        : item instanceof Uint8Array
+            ? `0x${Array.from(item, (byte) => byte.toString(16).padStart(2, "0")).join("")}`
+            : item);
+}
+async function within(work, ms, what) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new CheckFailed(`${what} did not finish within ${ms} ms`)), ms);
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function missingRequirements(declared, testCase) {
+    return testCase.requires.filter((requirement) => !declared.includes(requirement));
+}
+function notRun(options, testCase) {
+    if (options.only && !options.only.includes(testCase.id))
+        return { status: "skipped", reason: "not selected" };
+    const missing = missingRequirements(options.declared, testCase);
+    if (missing.length)
+        return { status: "unsupported", missing };
+    const reason = options.skip?.(testCase);
+    return reason ? { status: "skipped", reason } : undefined;
+}
+export async function runCases(options) {
+    const startedAt = new Date().toISOString();
+    const results = [];
+    const errors = [];
+    const log = options.log ?? (() => { });
+    let context;
+    let ready = false;
+    try {
+        context = await options.setup();
+        ready = true;
+    }
+    catch (error) {
+        errors.push(`setup: ${message(error)}`);
+    }
+    for (const testCase of options.cases) {
+        const base = { id: testCase.id, title: testCase.title, requires: testCase.requires };
+        const reason = notRun(options, testCase);
+        if (reason) {
+            results.push({ ...base, ...reason, ms: 0, evidence: {} });
+            log(`- ${testCase.title}: ${reason.status === "unsupported" ? `unsupported (${reason.missing.join(", ")})` : `skipped (${reason.reason})`}`);
+            continue;
+        }
+        if (!ready) {
+            results.push({ ...base, status: "fail", ms: 0, evidence: {}, error: "setup failed" });
+            continue;
+        }
+        const started = performance.now();
+        try {
+            const evidence = await within(testCase.run(context), options.caseTimeoutMs ?? 60_000, testCase.id);
+            results.push({ ...base, status: "pass", ms: Math.round(performance.now() - started), evidence });
+            log(`✓ ${testCase.title}`);
+        }
+        catch (error) {
+            results.push({
+                ...base,
+                status: "fail",
+                ms: Math.round(performance.now() - started),
+                evidence: error instanceof CheckFailed ? error.evidence : {},
+                error: message(error),
+            });
+            log(`✗ ${testCase.title}: ${message(error)}`);
+        }
+    }
+    if (ready && options.teardown)
+        try {
+            await options.teardown(context);
+        }
+        catch (error) {
+            errors.push(`teardown: ${message(error)}`);
+        }
+    const summary = { pass: 0, fail: 0, unsupported: 0, skipped: 0 };
+    for (const result of results)
+        summary[result.status]++;
+    return {
+        kit: options.kit,
+        subject: options.subject,
+        declared: options.declared,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        results,
+        summary,
+        errors,
+    };
+}
+export function conforms(report) {
+    return report.summary.fail === 0 && report.errors.length === 0 && report.summary.pass > 0;
+}
+export function formatReport(report) {
+    const mark = { pass: "✓", fail: "✗", unsupported: "-", skipped: " " };
+    const lines = [`${report.kit} contract: ${report.subject} (declares ${report.declared.join(", ") || "nothing"})`];
+    for (const result of report.results) {
+        const detail = result.status === "unsupported"
+            ? `unsupported: not declared (${result.missing?.join(", ")})`
+            : result.status === "fail"
+                ? `FAILED: ${result.error}`
+                : result.status === "pass"
+                    ? `${result.ms} ms`
+                    : `skipped: ${result.reason}`;
+        lines.push(`${mark[result.status]} ${result.title.padEnd(72)} ${detail}`);
+    }
+    for (const error of report.errors)
+        lines.push(`✗ ${error}`);
+    const { pass, fail, unsupported, skipped } = report.summary;
+    lines.push(`${pass} passed, ${fail} failed, ${unsupported} unsupported${skipped ? `, ${skipped} skipped` : ""}`);
+    return lines.join("\n");
+}
+export function registerCases(title, options) {
+    void describe(title, () => {
+        let report;
+        before(() => {
+            report = runCases(options);
+        });
+        for (const testCase of options.cases) {
+            const reason = notRun(options, testCase);
+            const skip = reason ? (reason.status === "unsupported" ? `unsupported: not declared (${reason.missing.join(", ")})` : reason.reason) : undefined;
+            void test(testCase.title, skip ? { skip } : {}, async () => {
+                const result = (await report).results.find((item) => item.id === testCase.id);
+                assert.ok(result, `${testCase.id} did not run`);
+                if (result.status === "fail")
+                    assert.fail(`${result.error}\nevidence: ${evidenceJson(result.evidence)}`);
+                assert.equal(result.status, "pass", `${testCase.id} is ${result.status}`);
+            });
+        }
+        void test("nothing fails outside the cases", async () => {
+            assert.deepEqual((await report).errors, []);
+        });
+    });
+}

package/contracts/chain/src/subject.d.ts

@@ -0,0 +1,75 @@
+import type { ChainAccess, ChainCall, ChainHistory, KeyDerivation, Receipt, ReceiptValidator, Signer, TransactionSubmitter } from "@parity/product-lab/ports/chain";
+/** What a chain subject can declare to the kit. */
+export declare const CHAIN_KIT_CAPABILITIES: readonly ["access", "submit", "history", "scriptedOutcomes", "validator", "keys", "sr25519", "signatureCheck"];
+export type ChainKitCapability = (typeof CHAIN_KIT_CAPABILITIES)[number];
+/**
+ * What the fixture's chain does with a transaction (`scriptedOutcomes`):
+ * `finalized` includes it and finalizes that block; `dispatch-error` does the
+ * same with a failed dispatch; `best-only` includes it and never finalizes;
+ * `retracted` includes it, then drops that block and never includes it again;
+ * `moved` includes it in a best block, then a reorg replaces that block with
+ * another that holds it, and that block is finalized; `stream-ends` ends the
+ * stream before any inclusion; `pending` never includes it;
+ * `finality-advances` finalizes another block after the submitter has read the
+ * chain and before the transaction is signed (as a chain that finalizes every
+ * block does), then includes and finalizes it.
+ */
+export type ScriptedOutcome = "finalized" | "dispatch-error" | "best-only" | "retracted" | "moved" | "stream-ends" | "pending" | "finality-advances";
+export interface ChainKitSubject {
+    /** Names the subject in reports. */
+    readonly name: string;
+    readonly declares: readonly ChainKitCapability[];
+    /** `access`: an open ChainAccess (a fresh one per call; the kit closes each). */
+    access?(): ChainAccess | Promise<ChainAccess>;
+    /** `history`: the ChainHistory to check. Default: an access object, which then implements it too. */
+    history?(): ChainHistory | Promise<ChainHistory>;
+    /** `submit`: the submitter, and one transaction per call. */
+    readonly submitter?: {
+        create(): TransactionSubmitter | Promise<TransactionSubmitter>;
+        /** A call and a signer for one transaction; with `scriptedOutcomes` the chain plays `outcome`. Live fixtures always get `finalized`. */
+        transaction(outcome: ScriptedOutcome): {
+            call: ChainCall;
+            signer: Signer;
+        } | Promise<{
+            call: ChainCall;
+            signer: Signer;
+        }>;
+        /** How many transactions reached the chain so far. */
+        broadcasts?(): number;
+    };
+    /** `validator`: receipts it must accept and receipts it must reject. */
+    readonly validator?: {
+        readonly validator: ReceiptValidator;
+        readonly accepts: readonly Receipt[];
+        readonly rejects: readonly Receipt[];
+    };
+    /** `keys`. */
+    readonly keys?: KeyDerivation;
+    /** `signatureCheck`: verifies a raw signature, independently of the subject. */
+    verify?(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
+    /** `access` and `submit` talk to a real chain: their cases run only in live mode. */
+    readonly live?: boolean;
+    /** How long to wait for finality (default 60 s). */
+    readonly finalityTimeoutMs?: number;
+}
+export interface ChainKitOptions {
+    /** Run cases that talk to a real chain. Default false. */
+    readonly live?: boolean;
+    readonly only?: readonly string[];
+    readonly caseTimeoutMs?: number;
+    readonly log?: (line: string) => void;
+}
+/** Well-known development accounts (the Substrate development phrase), independent of any adapter. */
+export declare const DEV_VECTORS: {
+    readonly alice: {
+        readonly uri: "//Alice";
+        readonly address: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
+        readonly polkadot: "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5";
+        readonly publicKey: "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d";
+    };
+    readonly bob: {
+        readonly uri: "//Bob";
+        readonly address: "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty";
+        readonly publicKey: "0x8eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a48";
+    };
+};

package/contracts/chain/src/subject.js

@@ -0,0 +1,25 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const CHAIN_KIT_CAPABILITIES = [
+    "access",
+    "submit",
+    "history",
+    "scriptedOutcomes",
+    "validator",
+    "keys",
+    "sr25519",
+    "signatureCheck",
+];
+export const DEV_VECTORS = {
+    alice: {
+        uri: "//Alice",
+        address: "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
+        polkadot: "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5",
+        publicKey: "0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d",
+    },
+    bob: {
+        uri: "//Bob",
+        address: "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
+        publicKey: "0x8eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a48",
+    },
+};

package/contracts/environment/README.md

@@ -0,0 +1,90 @@
+# @product-lab/contract-environment
+
+The environment contract kit (refactor step 10, part a). An environment adapter runs it against
+itself from its own tests; a case for a capability it does not declare is reported as
+`unsupported`, never as a pass, and a capability it declares but does not honour fails.
+
+```ts
+// adapters/environment/<adapter>/tests/contract.test.ts
+import { environmentContractTests } from "@product-lab/contract-environment";
+
+environmentContractTests(
+  {
+    name: "env-relayless",
+    declares: ["topology", "profiles", "workspaces", "lifecycle", "reset"],
+    factory: new RelaylessEnvironmentFactory(),
+    deps: {},
+    options: { valid: { relay: false, chains: ["people"], runtimes: { people: { wasm: "…" } } }, workspace: { … } },
+    lifecycle: { live: true, environment: () => …, alive: async (running) => … },
+  },
+  { live: process.env.PRODUCT_LAB_KIT_LIVE === "1" },
+);
+```
+
+`environmentContractTests` registers one `node:test` test per case (undeclared cases appear as
+skipped tests marked `unsupported: not declared (…)`); `runEnvironmentContract` returns the report
+instead (`conforms`, `formatReport`).
+
+## Capabilities and cases
+
+| Capability | Cases |
+| --- | --- |
+| `topology` (a `TopologyAdapterFactory`) | `options-valid`: startable options resolve into a schema-version-1 topology of this adapter with no error issues, the options recorded as given, the label following the customizations, retention `persistent` for a workspace and `disposable` otherwise; `options-strict`: unknown keys at the top level, in `services` and in the adapter's own section, and a `provider` naming another adapter, are rejected by the schema and by `resolve`; `malformed-throws`: an unknown network or chain, chains that are not a list, an out-of-range port, a workspace name that is not a name, runtime or binary releases that are not `owner/repo@tag`, a block time below 100 ms, a non-hex genesis storage key, an empty node argument and a non-boolean `statementStore` throw (never issues); each topology adapter owns its options schema, so these probes keep the shared vocabulary the same across adapters; `resolve-pure`; `selection`: startable options select this adapter and naming it explicitly changes nothing; `endpoints-loopback`: every chain and service endpoint is loopback on the topology's ports, also with a custom port, and the offer is local; `offer-consistent`: the domain's `Offer` validation, offer chains and capabilities equal the topology's, services agree, each capability has its chain or service, the domain's `EnvironmentEndpoints` serves every claimed capability, and every absent capability has a reason; `create-inert`; `start-aborted`: a start with an aborted signal rejects with that reason (before any work) |
+| `profiles` | `profiles`: each profile resolves to a topology of that profile; an unknown one throws |
+| `flags` | `flags`: well-formed names, no values change nothing, the fixture's values customize the run |
+| `workspaces` | `workspaces`: `state: { workspace }` is startable and persistent |
+| `endpointOptions` | `public-endpoint-refused`: options naming a non-loopback endpoint throw or carry an error issue |
+| `sensitiveOptions` | `sensitive-redacted`: customizations carrying the secret are marked `sensitive`, `describe` and the presentation never show it, the run manifest (the injected `runManifest`) never carries it; with `lifecycle`, `lifecycle-secrets`: nothing a running environment reports, nor its manifest file, carries it |
+| `probe` | `probe-local`, `probe-public` (never local, never development authority), `probe-read-only` (only read RPC methods) |
+| `lifecycle` | `lifecycle-start` (loopback endpoints, no more than declared, answering; every process `processes()` reports is running), `lifecycle-stop` (close stops what it started, leaves what it did not, `processes()` reports none running, and a second close resolves) |
+| `lifecycle` + `reset` | `lifecycle-reset` |
+| `lifecycle` + `routes` | `lifecycle-routes` (refactor step 7 part b): the running environment's `routes` rebuild as a valid `HostNetworkRoutes`, carry no `publicRoutes` opt-in, are loopback, route every chain and service to the environment's own endpoint of that id, and name the topology's network |
+
+Lifecycle cases whose fixture starts real processes (`lifecycle.live: true`) run only with
+`{ live: true }`. The kit depends only on `@product-lab/domain` and `@product-lab/ports`; the run
+manifest writer is injected (`manifest`). Since step 7 part b `KitRunningEnvironment` and `KitStartContext`
+are the `RunningEnvironment` and `EnvironmentStartContext` ports, and `KitEnvironment` is an `EnvironmentProvider`
+with an optional topology (before, structural copies of core's types).
+
+## Who runs it
+
+| Adapter | Declares | Test file |
+| --- | --- | --- |
+| `env-engine` | `topology`, `profiles`, `flags`, `workspaces`, `sensitiveOptions` | `adapters/environment/engine/tests/contract.test.ts` |
+| `env-relayless` | `topology`, `profiles`, `workspaces` | `adapters/environment/relayless/tests/contract.test.ts` |
+| `env-chopsticks` | `topology`, `profiles`, `flags`, `endpointOptions` | `adapters/environment/chopsticks/tests/contract.test.ts` |
+| `env-engine`, `env-relayless` | `lifecycle` (live), `reset`, `routes` | `tools/verify/tests/environment-contract-live.test.ts` (it needs the Node system adapters, which an adapter's own tests may not import) |
+| `env-chopsticks` | `lifecycle` (live), `reset` | the same file |
+| `env-attached` | `probe` (over a fake JSON-RPC) | `adapters/environment/attached/tests/contract.test.ts` |
+
+The live lifecycle cases are written but not run by the gates (they need a prepared Engine checkout,
+relay-less binaries or a Chopsticks upstream; see that test file's header).
+
+## Package
+
+| | |
+| --- | --- |
+| Nx project | `contract-environment` |
+| Tags | `scope:core`, `layer:core`, `type:contract` |
+| Exports | `.` (`src/index.ts`): `environmentContractTests`, `runEnvironmentContract`, `environmentCases`, `ENVIRONMENT_KIT_CAPABILITIES`, `EnvironmentKitContext`, `conforms`, `formatReport`, and the types `EnvironmentKitSubject`, `EnvironmentKitCapability`, `EnvironmentKitOptions`, `KitEnvironment`, `KitRunningEnvironment`, `KitStartContext`, `ProbedEnvironment`, `ContractReport`, `CaseResult`, `CaseStatus`, `ContractCase` |
+| Tests the ports | `TopologyAdapterFactory`, `EnvironmentProvider` and `RunningEnvironment` (`@product-lab/ports/environment`), `OptionsSchema` and `AdapterFlag` (`@product-lab/ports/factory`); the domain's `HostNetworkRoutes` a running environment exposes |
+| Depends on | `@product-lab/domain`, `@product-lab/ports`, `node:test`, `node:assert` |
+| Used by | the four environment adapters' tests (dev dependency), `tools/verify` (the live lifecycle cases, `tests/environment-contract-live.test.ts`) |
+
+`src/runner.ts` (case gating, reports, `node:test` registration) is copied verbatim into each kit:
+a `type:contract` project may depend only on `type:domain` and `type:port`, so the kits cannot share
+it.
+
+| Source | What it holds |
+| --- | --- |
+| `src/kit.ts` | `environmentCases` (the families below, in run order), `runEnvironmentContract`, `environmentContractTests` |
+| `src/subject.ts` | What a subject declares and gives the kit: capabilities, `EnvironmentKitSubject`, `EnvironmentKitOptions`, `KitEnvironment`, `KitRunningEnvironment`, `KitStartContext`, `ProbedEnvironment` |
+| `src/context.ts` | `EnvironmentKitContext` (the one running environment the lifecycle cases share) |
+| `src/checks.ts` | The pure checks the cases share (resolved options, capability facts, offers, endpoint URLs) |
+| `src/cases/options.ts`, `topology.ts`, `declared-options.ts`, `probe.ts`, `lifecycle.ts` | One file per case family (5, 4, 5, 3 and 5 cases) |
+
+## Tests
+
+```sh
+bunx nx run contract-environment:test   # the kit against an in-memory adapter, with 18 negative controls
+```

package/contracts/environment/src/cases/declared-options.d.ts

@@ -0,0 +1,3 @@
+import { type EnvironmentCase } from "../context.js";
+/** The declared-option cases, in run order. */
+export declare const declaredOptionCases: readonly EnvironmentCase[];

package/contracts/environment/src/cases/declared-options.js

@@ -0,0 +1,103 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { expect } from "../runner.js";
+import { define } from "../context.js";
+import { same, errors, text, nonEmpty, throws, checkResolved } from "../checks.js";
+export const declaredOptionCases = [
+    define({
+        id: "profiles",
+        title: "each profile resolves to a topology of that profile; an unknown one throws",
+        requires: ["topology", "profiles"],
+        async run(kit) {
+            const factory = kit.factory();
+            const base = kit.subject.options?.profileBase ?? {};
+            expect(factory.profiles.length > 0, "declares profiles but offers none");
+            const names = factory.profiles.map((profile) => profile.name);
+            expect(new Set(names).size === names.length, "two profiles share a name", { names });
+            const evidence = {};
+            for (const profile of factory.profiles) {
+                expect(nonEmpty(profile.description), `profile ${profile.name} has no description`);
+                const t = factory.resolve(factory.profile(profile.name, base));
+                evidence[profile.name] = { profile: t.profile, provider: t.provider, errors: errors(t).map((issue) => issue.code) };
+                expect(t.profile === profile.name && t.provider === factory.kind, `profile ${profile.name} resolves to ${t.provider} ${t.profile}`, evidence);
+            }
+            expect(throws(() => factory.profile("contract-kit-no-such-profile", base)).threw, "an unknown profile name is accepted", evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "flags",
+        title: "flags are well formed, change nothing when absent, and customize the run when given",
+        requires: ["topology", "flags"],
+        async run(kit) {
+            const factory = kit.factory();
+            const { valid, flags } = kit.options();
+            expect(factory.flags.length > 0, "declares flags but adds none");
+            const names = factory.flags.map((flag) => flag.name);
+            expect(new Set(names).size === names.length, "two flags share a name", { names });
+            for (const flag of factory.flags) {
+                expect(/^[a-z][a-z0-9-]*$/.test(flag.name), `flag --${flag.name} is not a lower-case name without dashes in front`);
+                expect(flag.type === "string" || flag.type === "boolean", `flag --${flag.name} has type ${String(flag.type)}`);
+                expect(nonEmpty(flag.description), `flag --${flag.name} has no description`);
+            }
+            expect(same(factory.withFlags({}, valid), valid), "no flag values changed the options");
+            expect(flags, "declares flags but the fixture gives no flag values");
+            const layered = factory.withFlags(flags, valid);
+            expect(!same(layered, valid), "the fixture's flag values changed nothing", { flags });
+            const t = factory.resolve(layered);
+            expect(t.label === "custom" && t.customizations.length > 0, "a run customized by flags is not labelled custom", { customizations: t.customizations });
+            return { flags: names, customizations: t.customizations.map((item) => item.option) };
+        },
+    }),
+    define({
+        id: "workspaces",
+        title: "a workspace state resolves into a startable, persistent topology",
+        requires: ["topology", "workspaces"],
+        async run(kit) {
+            const factory = kit.factory();
+            const options = kit.options().workspace;
+            expect(options && "state" in options && typeof options.state === "object" && "workspace" in options.state, "declares workspaces but the fixture gives no workspace options");
+            const t = checkResolved(factory, options);
+            expect(t.retention.retention === "persistent", `a workspace is ${t.retention.retention}, not persistent`, { retention: t.retention });
+            return { retention: t.retention };
+        },
+    }),
+    define({
+        id: "public-endpoint-refused",
+        title: "options naming a non-loopback endpoint are refused",
+        requires: ["topology", "endpointOptions"],
+        async run(kit) {
+            const factory = kit.factory();
+            const options = kit.options().publicEndpoint;
+            expect(options, "declares endpointOptions but the fixture gives no public-endpoint options");
+            const result = throws(() => factory.resolve(options));
+            if (result.threw)
+                return { refused: "threw", message: result.message.slice(0, 200) };
+            const t = result.value;
+            expect(errors(t).length > 0, "a non-loopback endpoint resolves into a startable topology", { issues: t.issues });
+            return { refused: "error issue", codes: errors(t).map((issue) => issue.code) };
+        },
+    }),
+    define({
+        id: "sensitive-redacted",
+        title: "secret option values are marked sensitive and never reach a run manifest",
+        requires: ["topology", "sensitiveOptions"],
+        async run(kit) {
+            const factory = kit.factory();
+            const secret = kit.options().secret;
+            expect(secret, "declares sensitiveOptions but the fixture gives no secret options");
+            expect(kit.subject.manifest, "declares sensitiveOptions but gives no manifest writer to check");
+            const t = factory.resolve(secret.options);
+            const carrying = t.customizations.filter((item) => text(item.value).includes(secret.value));
+            expect(carrying.length > 0, "no customization records the secret option (a customized run would pass as standard)", { customizations: t.customizations.map((item) => item.option) });
+            const unmarked = carrying.filter((item) => item.sensitive !== true);
+            expect(unmarked.length === 0, `customizations ${unmarked.map((item) => item.option).join(", ")} carry the secret without sensitive: true`);
+            const shown = { describe: factory.describe(t), presentation: t.presentation };
+            expect(!text(shown).includes(secret.value), "describe or the presentation shows the secret");
+            const manifest = text(kit.subject.manifest(t));
+            expect(!manifest.includes(secret.value), "the run manifest carries the secret");
+            expect(text(t).includes(secret.value), "the resolved topology lost the value the adapter needs to start");
+            return { sensitive: carrying.map((item) => item.option), manifestBytes: manifest.length };
+        },
+    }),
+];

package/contracts/environment/src/cases/lifecycle.d.ts

@@ -0,0 +1,3 @@
+import { type EnvironmentCase } from "../context.js";
+/** The lifecycle cases, in run order. */
+export declare const lifecycleCases: readonly EnvironmentCase[];

package/contracts/environment/src/cases/lifecycle.js

@@ -0,0 +1,130 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { LoopbackUrl, Offer, HostNetworkRoutes } from "@parity/product-lab/domain";
+import { CheckFailed, expect } from "../runner.js";
+import { define } from "../context.js";
+import { text } from "../checks.js";
+export const lifecycleCases = [
+    define({
+        id: "lifecycle-start",
+        title: "a started environment reports loopback endpoints and no more than it declared",
+        requires: ["lifecycle"],
+        async run(kit) {
+            const environment = await kit.lifecycle().environment();
+            const running = await kit.running();
+            const endpoints = Object.values(running.endpoints ?? {});
+            const external = endpoints.filter((url) => !LoopbackUrl.test(url));
+            const evidence = { endpoints: running.endpoints, offer: running.offer };
+            expect(external.length === 0, `non-loopback endpoints ${external.join(", ")}`, evidence);
+            if (running.offer) {
+                const extraChains = running.offer.chains.filter((chain) => !environment.offer.chains.includes(chain));
+                const extraCapabilities = (running.offer.capabilities ?? []).filter((capability) => !(environment.offer.capabilities ?? []).includes(capability));
+                expect(extraChains.length === 0 && extraCapabilities.length === 0, `the running offer claims more than declared (${[...extraChains, ...extraCapabilities].join(", ")})`, evidence);
+                expect(Offer.errors(running.offer, "running environment").length === 0, Offer.errors(running.offer, "running environment").join("; "), evidence);
+            }
+            expect(await kit.lifecycle().alive(running), "what the environment started does not answer", evidence);
+            if (running.processes) {
+                const processes = running.processes();
+                evidence.processes = processes;
+                const down = processes.filter((entry) => entry.status !== "running");
+                expect(down.length === 0, `owned processes not running after start: ${down.map((entry) => `${entry.id} ${entry.status}`).join(", ")}`, evidence);
+            }
+            return evidence;
+        },
+    }),
+    define({
+        id: "lifecycle-routes",
+        title: "a started environment routes hosts to its own loopback chains and services, with no public opt-in",
+        requires: ["lifecycle", "routes"],
+        async run(kit) {
+            const environment = await kit.lifecycle().environment();
+            const running = await kit.running();
+            const routes = running.routes;
+            expect(routes, "declares routes but the running environment has none");
+            const data = routes.toJSON();
+            const evidence = { routes: data, endpoints: running.endpoints };
+            let rebuilt;
+            try {
+                rebuilt = HostNetworkRoutes.from(data);
+            }
+            catch (error) {
+                throw new CheckFailed(`the routing is not valid: ${error instanceof Error ? error.message : String(error)}`, evidence);
+            }
+            expect(!rebuilt.publicRoutes, `an owned environment opted into public routes (${rebuilt.publicRoutes?.reason})`, evidence);
+            const all = [...Object.values(rebuilt.chains).map((route) => route.ws), ...Object.values(rebuilt.services)];
+            const external = all.filter((url) => !LoopbackUrl.test(url));
+            expect(external.length === 0, `non-loopback routes ${external.join(", ")}`, evidence);
+            const endpoints = running.endpoints ?? {};
+            const elsewhere = [...Object.entries(rebuilt.chains).map(([id, route]) => [id, route.ws]), ...Object.entries(rebuilt.services)].filter(([id, url]) => endpoints[id] !== url);
+            expect(elsewhere.length === 0, `routes that are not the environment's own endpoints: ${elsewhere.map(([id, url]) => `${id} ${url}`).join(", ")}`, evidence);
+            if (environment.topology)
+                expect(rebuilt.network === environment.topology.network, `routes name ${rebuilt.network}, the topology runs ${environment.topology.network}`, evidence);
+            return evidence;
+        },
+    }),
+    define({
+        id: "lifecycle-secrets",
+        title: "nothing a running environment reports carries a secret it was given",
+        requires: ["lifecycle", "sensitiveOptions"],
+        async run(kit) {
+            const lifecycle = kit.lifecycle();
+            expect(lifecycle.secret, "declares sensitiveOptions but the lifecycle fixture gives no secret");
+            const running = await kit.running();
+            const reported = text({ endpoints: running.endpoints, provenance: running.provenance, notices: running.notices, offer: running.offer, retention: running.retention });
+            expect(!reported.includes(lifecycle.secret), "the running environment reports the secret");
+            const evidence = { reportedBytes: reported.length };
+            if (running.manifestFile) {
+                expect(lifecycle.readManifest, "the environment wrote a run manifest the fixture cannot read");
+                const manifest = await lifecycle.readManifest(running.manifestFile);
+                expect(!manifest.includes(lifecycle.secret), "the run manifest carries the secret", { manifestFile: running.manifestFile });
+                evidence.manifestBytes = manifest.length;
+            }
+            return evidence;
+        },
+    }),
+    define({
+        id: "lifecycle-reset",
+        title: "reset starts a new generation that answers on loopback",
+        requires: ["lifecycle", "reset"],
+        async run(kit) {
+            const running = await kit.running();
+            expect(typeof running.reset === "function", "declares reset but the running environment has none");
+            await running.reset(kit.controller.signal);
+            const external = Object.values(running.endpoints ?? {}).filter((url) => !LoopbackUrl.test(url));
+            expect(external.length === 0, `non-loopback endpoints after reset: ${external.join(", ")}`);
+            expect(await kit.lifecycle().alive(running), "the reset environment does not answer");
+            return { endpoints: running.endpoints };
+        },
+    }),
+    define({
+        id: "lifecycle-stop",
+        title: "close stops what the environment started, leaves the rest, and is idempotent",
+        requires: ["lifecycle"],
+        async run(kit) {
+            const lifecycle = kit.lifecycle();
+            const running = await kit.running();
+            kit.markClosed();
+            await running.close();
+            const evidence = {};
+            evidence.aliveAfterClose = await lifecycle.alive(running);
+            expect(evidence.aliveAfterClose === false, "what the environment started still answers after close", evidence);
+            if (running.processes) {
+                const left = running.processes().filter((entry) => entry.status === "running");
+                evidence.processesAfterClose = left;
+                expect(left.length === 0, `owned processes still running after close: ${left.map((entry) => entry.id).join(", ")}`, evidence);
+            }
+            if (lifecycle.foreignAlive) {
+                evidence.foreignAliveAfterClose = await lifecycle.foreignAlive();
+                expect(evidence.foreignAliveAfterClose === true, "close stopped something the environment did not start", evidence);
+            }
+            try {
+                await running.close();
+                evidence.secondClose = "resolved";
+            }
+            catch (error) {
+                throw new CheckFailed(`a second close failed: ${error instanceof Error ? error.message : String(error)}`, evidence);
+            }
+            return evidence;
+        },
+    }),
+];

package/contracts/environment/src/cases/options.d.ts

@@ -0,0 +1,3 @@
+import { type EnvironmentCase } from "../context.js";
+/** The options cases, in run order. */
+export declare const optionsCases: readonly EnvironmentCase[];