@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/ports/src/driven/chain/receipt.d.ts

@@ -0,0 +1,33 @@
+/** A block by hash and number. */
+export interface BlockRef {
+    readonly hash: string;
+    readonly number: number;
+}
+/** Where an extrinsic landed: its block and its index in that block. */
+export interface InclusionRef extends BlockRef {
+    readonly index: number;
+}
+/** One runtime event emitted by the extrinsic: pallet (`type`) and event (`value.type`). */
+export interface ReceiptEvent {
+    readonly type: string;
+    readonly value: {
+        readonly type: string;
+        readonly value?: unknown;
+    };
+}
+/**
+ * What a chain reports for a submitted extrinsic once it is in a block. `ok`
+ * is the chain's own dispatch result (`System.ExtrinsicSuccess`); whether the
+ * receipt means success for the caller is a {@link ReceiptValidator}'s call.
+ */
+export interface Receipt {
+    readonly txHash: string;
+    readonly ok: boolean;
+    readonly block: InclusionRef;
+    readonly events: readonly ReceiptEvent[];
+    /** The dispatch error when `ok` is false. */
+    readonly dispatchError?: {
+        readonly type: string;
+        readonly value: unknown;
+    };
+}

package/core/ports/src/driven/chain/receipt.js

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

package/core/ports/src/driven/chain/runtime-fingerprint.d.ts

@@ -0,0 +1,12 @@
+/**
+ * What identifies the runtime a chain runs at a block: the blake2-256 hash of
+ * its code (`:code`, the hash runtime upgrades authorize) and its version.
+ * Version sources resolve `deployed` from it (Phase 6).
+ */
+export interface RuntimeFingerprint {
+    /** `0x`-prefixed blake2-256 of the runtime code. */
+    readonly codeHash: string;
+    readonly specName: string;
+    readonly specVersion: number;
+    readonly transactionVersion: number;
+}

package/core/ports/src/driven/chain/runtime-fingerprint.js

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

package/core/ports/src/driven/chain/signer.d.ts

@@ -0,0 +1,16 @@
+export type SignatureScheme = "sr25519" | "ed25519" | "ecdsa";
+/**
+ * A handle to an account that can sign. Core reads only its public key; the
+ * TransactionSubmitter adapter signs with the handles it accepts: a
+ * {@link KeySigner}, or a signer native to its own technology (for example one
+ * a host supplies for a host identity).
+ */
+export interface Signer {
+    readonly publicKey: Uint8Array;
+}
+/** A signer that holds key material and signs raw payloads (what {@link KeyDerivation} returns). */
+export interface KeySigner extends Signer {
+    readonly scheme: SignatureScheme;
+    /** Signature of exactly these bytes, without any wrapping. */
+    sign(payload: Uint8Array): Uint8Array;
+}

package/core/ports/src/driven/chain/signer.js

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

package/core/ports/src/driven/chain/statement-store-reader.d.ts

@@ -0,0 +1,53 @@
+import type { DecodedStatement } from "@parity/product-lab/domain";
+export interface StatementQuery {
+    /** 32-byte topics. */
+    readonly topics: readonly Uint8Array[];
+    /** `all` (default): statements carrying every topic; `any`: carrying at least one. */
+    readonly match?: "all" | "any";
+    /** Stop waiting once this holds for what was read so far (default: after the first answer). */
+    readonly until?: (statements: readonly ReadStatement[]) => boolean;
+    /**
+     * Backlog 99: return once the store has sent every statement it held when asked (its answers count `remaining`
+     * down to 0), none included, instead of after the first answer. A store that does not count is read until `until`
+     * holds, else for the whole timeout.
+     */
+    readonly held?: boolean;
+    /** How long to wait for `until`; what was read by then is returned. */
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal;
+}
+/** One statement as the store returned it. */
+export interface ReadStatement {
+    /** The bytes the node returned. */
+    readonly encoded: Uint8Array;
+    readonly statement: DecodedStatement;
+    /**
+     * Whether the proof's signature is the signer's over the statement's fields: true or false for an Sr25519 proof;
+     * undefined for a statement without a proof, or with a kind this reader does not check (`unchecked` says which).
+     */
+    readonly verified: boolean | undefined;
+    readonly unchecked?: string;
+}
+/** An account's statement allowance as the chain holds it at one block (`:statement_allowance:` ++ account). */
+export interface StatementAllowanceRead {
+    /** The block read: the best head or the finalized head when asked. */
+    readonly block: {
+        readonly number: number;
+        readonly hash: string;
+    };
+    /** Absent: the chain holds no allowance for the account at that block. */
+    readonly allowance?: {
+        readonly maxCount: number;
+        readonly maxSize: number;
+    };
+}
+export interface StatementStoreReader {
+    /** The statements the store holds, or receives while waiting, for `query.topics`. */
+    statements(query: StatementQuery): Promise<readonly ReadStatement[]>;
+    /**
+     * `account`'s statement allowance at the best or the finalized head. A node accepts a statement against the best
+     * block but enforces allowances against the finalized one (polkadot-sdk sc-statement-store), removing the statements
+     * of an account with none there: a write stays only once its allowance is finalized. Absent: this reader cannot tell.
+     */
+    allowanceAt?(account: string, at: "best" | "finalized"): Promise<StatementAllowanceRead>;
+}

package/core/ports/src/driven/chain/statement-store-reader.js

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

package/core/ports/src/driven/chain/transaction-submitter.d.ts

@@ -0,0 +1,104 @@
+import type { BlockRef, Receipt } from "./receipt.js";
+import type { Signer } from "./signer.js";
+/**
+ * A call built by the consumer's chain API (`ChainAccess.api`). Opaque to core;
+ * the TransactionSubmitter adapter accepts the calls its own API builds.
+ */
+export type ChainCall = object;
+export interface SubmitRequest {
+    /** Names the transaction in errors. */
+    readonly label: string;
+    readonly call: ChainCall;
+    readonly signer: Signer;
+    /** Aborting fails both promises of the tracked transaction. */
+    readonly signal: AbortSignal;
+    /** Fails both promises when finality has not arrived in time (default 180 s). */
+    readonly timeoutMs?: number;
+    /**
+     * The account nonce to sign with. Absent: the adapter resolves one itself
+     * (from its node's current heads, which do not count transactions still in
+     * the pool). Set by a caller that orders an account's submissions and
+     * allocates its nonces (the application's `SigningQueues`).
+     */
+    readonly nonce?: number;
+    /**
+     * Filled by the adapter as facts become known (signing block, runtime
+     * version, nonce, mortality, genesis, and `inclusionMoves`: each change of
+     * inclusion before finality, `{ from, to, at }` with `from`/`to` a block
+     * `{ hash, number, index }` or `null` when no best block holds it). JSON-safe
+     * values; the caller journals them. Never key material.
+     */
+    readonly diagnostics?: Record<string, unknown>;
+    /** Runs after the adapter's own reads and just before broadcast; throwing cancels the submission. */
+    readonly beforeBroadcast?: () => void;
+    /** Called once when the payload has been signed. */
+    readonly onSigned?: () => void;
+    /**
+     * Called once, before the transaction can reach a block, with what
+     * identifies it on chain. From then on it may land: whoever submitted it
+     * keeps these facts to find out later whether it did (reconciliation).
+     */
+    readonly onSubmitted?: (transaction: SignedTransaction) => void;
+}
+/**
+ * A signed transaction as the chain will see it. Enough to decide later,
+ * from finalized state alone, whether it landed: its hash to find it, the
+ * block it was signed against as the lower bound of where it can be, and its
+ * nonce and mortality to prove that it never can.
+ */
+export interface SignedTransaction {
+    /** blake2-256 of the signed extrinsic (what `Receipt.txHash` carries). */
+    readonly txHash: string;
+    /** The signer's public key, 0x hex. */
+    readonly signer: string;
+    /** The block the transaction was signed against; it cannot be in this block or an earlier one. */
+    readonly signedAt: BlockRef;
+    /** The signer's account nonce the transaction uses, when the adapter knows it. */
+    readonly nonce?: number;
+    /** A mortal transaction can only be in blocks `birth` to `death - 1`; `immortal` has no such bound. Absent when unknown. */
+    readonly mortality?: {
+        readonly birth: number;
+        readonly death: number;
+    } | "immortal";
+}
+/**
+ * The two stages of one submitted transaction. `included` resolves with the
+ * first receipt from a best or finalized block: progress only, never evidence
+ * that it landed (that block may still lose). `finalized` resolves only with
+ * the receipt from the finalized block. An inclusion that moves to another
+ * block or is retracted before finality fails nothing: the adapter keeps
+ * tracking and finality decides. A stream that ends before finality, abort or
+ * timeout rejects both (whatever has not resolved yet): the outcome is then
+ * unknown, for the caller to reconcile from finalized state. Nothing is
+ * retried or resubmitted.
+ */
+export interface TrackedTransaction {
+    readonly included: Promise<Receipt>;
+    readonly finalized: Promise<Receipt>;
+}
+/**
+ * What a caller needs to allocate an account's nonces itself: which chain the
+ * submitter signs for and the account's next nonce there. Both read the
+ * chain, never a local counter.
+ */
+export interface SubmitterNonces {
+    /** The chain the submitter signs for: its genesis hash, 0x hex. */
+    chain(): Promise<string>;
+    /**
+     * The account's next nonce at the node's best block (the runtime's
+     * `AccountNonceApi`): transactions still in the pool are not counted.
+     */
+    next(signer: Signer): Promise<number>;
+}
+/** Signs, submits and tracks transactions to finality on one chain. */
+export interface TransactionSubmitter {
+    /** Resolves once the transaction is broadcast; rejects if it could not be signed or sent. */
+    submit(request: SubmitRequest): Promise<TrackedTransaction>;
+    /**
+     * Present when the submitter signs with `SubmitRequest.nonce` and can read
+     * an account's next nonce: callers may then allocate nonces themselves, so
+     * concurrent submissions from one account never sign the same nonce.
+     * Absent: the submitter resolves every nonce itself.
+     */
+    readonly nonces?: SubmitterNonces;
+}

package/core/ports/src/driven/chain/transaction-submitter.js

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

package/core/ports/src/driven/deploy/content-archiver.d.ts

@@ -0,0 +1,21 @@
+/** A CARv1 archive of one content DAG, with what checking its blocks found. */
+export interface ContentArchive {
+    readonly car: Uint8Array;
+    readonly blocks: number;
+    readonly bytes: number;
+    /** Blocks whose digest was checked against their CID. */
+    readonly verified: number;
+    /** Blocks under a hash function the archiver cannot check (counted, never trusted silently). */
+    readonly unverified: number;
+}
+/**
+ * Content-addressed archives for hosts that fetch apps as CAR files (dot.li's
+ * `GET /ipfs/<cid>?format=car`). The archiver walks the DAG under a CID and
+ * checks every block against its CID; a block that does not match fails.
+ */
+export interface ContentArchiver {
+    /** The DAG under `cid`, read from the local content store. */
+    archive(cid: string): Promise<ContentArchive>;
+    /** Re-walk an archive obtained elsewhere (for example a public gateway) from `cid`, checking every block, and repack it. */
+    reverify(cid: string, car: Uint8Array): Promise<ContentArchive>;
+}

package/core/ports/src/driven/deploy/content-archiver.js

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

package/core/ports/src/driven/deploy/deployer.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Deployment of an app's built bytes to a network's own content store and
+ * name service (on a local Paseo fork: Bulletin and DotNS), resolution of the
+ * name, and read-back of the content it points at. Local environments only:
+ * an implementation refuses non-loopback endpoints and signs with development
+ * keys. Refactor step 8 (docs/architecture-refactor.md, "The model").
+ */
+import type { NameResolver } from "./name-resolver.js";
+/** What to deploy. */
+export interface DeployRequest {
+    /** Directory of the built app; it must hold an `index.html`. */
+    readonly buildDir: string;
+    /** Bare name label (`[a-z0-9-]+`); the deployer appends its network's top-level domain. */
+    readonly label: string;
+    /** Where the deployer keeps this deployment's records (logs, archives, the deployment record). */
+    readonly runDir: string;
+    /** Product manifest configuration to publish with the deployment (the name's `manifest` record). */
+    readonly manifestConfig?: string;
+    readonly signal?: AbortSignal;
+}
+/** A name as the name service holds it at one block. */
+export interface NameResolution {
+    /** The full name, for example `example.paseo`. */
+    readonly name: string;
+    /** Block hash the records were read at. */
+    readonly at: string;
+    /** The raw contenthash, `0x`-hex, or null when the name has none. */
+    readonly contenthash: string | null;
+    /** Root CID of the content the contenthash points at, or null. */
+    readonly cid: string | null;
+    /** Text records by key (`manifest`, `executable`); null when absent. */
+    readonly records: Readonly<Record<string, string | null>>;
+}
+/** One file of a deployment: its size and sha256 (hex). */
+export interface DeployedFile {
+    readonly bytes: number;
+    readonly sha256: string;
+}
+/** Content read back from the store, every block checked against its CID. */
+export interface RetrievedContent {
+    /** The CID that was read (the name's, when read by name). */
+    readonly cid: string;
+    /** Files by path relative to the root (`index.html`, `assets/app.js`). */
+    readonly files: ReadonlyMap<string, Uint8Array>;
+    /** Set when the CID holds an archive of the site that was unpacked: its inner root and digest. */
+    readonly container?: {
+        readonly kind: "car";
+        readonly root: string;
+        readonly bytes: number;
+        readonly sha256: string;
+    };
+    /** The resolution the CID came from, when read by name. */
+    readonly resolution?: NameResolution;
+    /**
+     * Which source answered (backlog A5): the Bulletin node, or an IPFS gateway after Bulletin did not (`fallbackReason`
+     * says why). Every block is checked against its CID either way.
+     */
+    readonly source?: {
+        readonly kind: "bulletin" | "ipfs-gateway";
+        readonly endpoint: string;
+        readonly fallbackReason?: string;
+    };
+}
+/** A deployment the deployer resolved and read back after uploading it. */
+export interface Deployment {
+    /** The full name (`<label>.<tld>`). */
+    readonly name: string;
+    readonly label: string;
+    readonly cid: string;
+    readonly contenthash: string;
+    readonly resolution: NameResolution;
+    /** Every file read back, with its digest; each file of the build is among them with identical bytes. */
+    readonly files: Readonly<Record<string, DeployedFile>>;
+    /** Files read back that are not in the build (for example a deploy tool's own manifest). */
+    readonly extraFiles: readonly string[];
+    /** The parsed `manifest` record, when one was published. */
+    readonly manifest?: Readonly<Record<string, unknown>>;
+    readonly timings: {
+        readonly deployMs: number;
+        readonly verifyMs: number;
+    };
+}
+/** Which content to read back: by CID, or by name through the name service. */
+export type RetrieveTarget = {
+    readonly cid: string;
+} | {
+    readonly name: string;
+};
+/**
+ * Deploys built apps to one environment's content store and name service.
+ * `deploy` fails unless the name then resolves to the uploaded content and
+ * every build file reads back byte-equal; `resolve` and `retrieve` let a caller
+ * check a deployment independently.
+ */
+export interface Deployer<D extends Deployment = Deployment> extends NameResolver {
+    deploy(request: DeployRequest): Promise<D>;
+    /** Read content back, verifying every block; a name without content is an error. */
+    retrieve(target: RetrieveTarget, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<RetrievedContent>;
+}

package/core/ports/src/driven/deploy/deployer.js

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

package/core/ports/src/driven/deploy/destination-directory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What a running environment resolves navigation destinations against: its
+ * lab apps (with the content each was deployed as, in `deployed-local`), its
+ * DotNS namespace and, when it has one, its name service. Without a name
+ * service destinations resolve against the app list alone (the static map
+ * `dev` uses).
+ */
+import type { DeployedApp } from "@parity/product-lab/domain";
+import type { NameResolver } from "./name-resolver.js";
+export interface DestinationDirectory {
+    readonly apps: readonly DeployedApp[];
+    /** Network namespace (`paseo`, `testnet`); `.dot` names resolve inside it. */
+    readonly namespace?: string;
+    readonly names?: NameResolver;
+}

package/core/ports/src/driven/deploy/destination-directory.js

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

package/core/ports/src/driven/deploy/destination-server.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Serves content a name resolved to as an app a host can load (the local
+ * gateway: content read back from the environment's content store, every
+ * block checked against its CID). The navigation bridge asks it for a
+ * destination no lab app declares, so the actor's host opens exactly the bytes
+ * the name points at (docs/design.md, section 10, "Opening apps by name").
+ */
+import type { HostApp } from "../host/host-session.js";
+/** A resolved destination to serve. */
+export interface ServedDestination {
+    /** Lab-wide app id the served app gets. */
+    readonly appId: string;
+    /** The full name the host runs it under (`<label>.<namespace>`). */
+    readonly product: string;
+    /** Root CID the name resolved to; the server serves exactly this content. */
+    readonly cid: string;
+}
+export interface DestinationServer {
+    /** Read the content back and serve it; the app's URL carries the host bridge when the host needs one. */
+    app(destination: ServedDestination, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<HostApp>;
+    /** Stop every server this started. */
+    close(): Promise<void>;
+}

package/core/ports/src/driven/deploy/destination-server.js

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

package/core/ports/src/driven/deploy/index.d.ts

@@ -0,0 +1,5 @@
+export type { DeployedFile, Deployer, Deployment, DeployRequest, NameResolution, RetrievedContent, RetrieveTarget, } from "./deployer.js";
+export type { ContentArchive, ContentArchiver } from "./content-archiver.js";
+export type { NameResolver } from "./name-resolver.js";
+export type { DestinationServer, ServedDestination } from "./destination-server.js";
+export type { DestinationDirectory } from "./destination-directory.js";

package/core/ports/src/driven/deploy/index.js

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

package/core/ports/src/driven/deploy/name-resolver.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A network's name service, read-only: what a name points at (on a local
+ * Paseo fork, DotNS on Asset Hub). The navigation bridge resolves
+ * `polkadot://<name>` destinations through it in `deployed-local`
+ * (docs/design.md, sections 10 and 11). Every `Deployer` is one.
+ */
+import type { NameResolution } from "./deployer.js";
+export interface NameResolver {
+    /** The name's records at the finalized head (a name without content resolves with null fields). */
+    resolve(name: string): Promise<NameResolution>;
+}

package/core/ports/src/driven/deploy/name-resolver.js

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

package/core/ports/src/driven/environment/environment-adapter-factory.d.ts

@@ -0,0 +1,21 @@
+import type { AdapterFlag } from "../factory/adapter-flag.js";
+import type { OptionsSchema } from "../factory/options-schema.js";
+import type { SystemPorts } from "../system/system-ports.js";
+/**
+ * Creates environments of one adapter kind from validated options
+ * (docs/architecture-refactor.md, "Composition root"). Each environment adapter
+ * package exports its factory; the lab registers the factories it uses, so the
+ * core never names an adapter. The factory owns its options schema: nothing
+ * validates the options again.
+ */
+export interface EnvironmentAdapterFactory<Options = unknown, Environment = unknown, Deps = Partial<SystemPorts>> {
+    /** The adapter kind, for example `attached`. */
+    readonly kind: string;
+    /** What it runs, in a few words. */
+    readonly label: string;
+    readonly options: OptionsSchema<Options>;
+    /** Command-line flags it adds, if any. */
+    readonly flags?: readonly AdapterFlag[];
+    /** An environment for `options` (already validated by `options`). No I/O until the environment starts. */
+    create(options: Options, deps: Deps): Environment;
+}

package/core/ports/src/driven/environment/environment-adapter-factory.js

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

package/core/ports/src/driven/environment/environment-time.d.ts

@@ -0,0 +1,110 @@
+import type { ChainPace } from "@parity/product-lab/domain/lab";
+/** One chain at one moment: its best and finalized block, and its clock when it keeps one. */
+export interface ChainMoment {
+    /** Best block number. */
+    readonly number: number;
+    /** Best block hash, 0x hex. */
+    readonly hash: string;
+    /** Finalized block number. */
+    readonly finalized: number;
+    /** The chain's own clock at the finalized block (`Timestamp.Now`, epoch milliseconds), when the chain keeps one. */
+    readonly timestamp?: number;
+}
+/** What one advance did on one chain, as the environment reports it (the lab checks it against the chain). */
+export interface ChainAdvance {
+    readonly chain: string;
+    /** How the blocks came: `dev_newBlock` (built on request), `block timer` (waited for the node's own blocks), … */
+    readonly method: string;
+    readonly from: ChainMoment;
+    readonly to: ChainMoment;
+    /** Blocks the chain gained (`to.number - from.number`); not named `blocks`, which run evidence reads as a block number. */
+    readonly added: number;
+    /** Wall-clock milliseconds the advance took. */
+    readonly ms: number;
+    /** One sentence for the evidence: what was done and what it cost. */
+    readonly detail?: string;
+    /**
+     * What the lab read itself, through its own connection to the chain, before and after the advance (its finalized
+     * head and the clock there), and that it satisfied the request; set by the lab, never by the environment. Absent:
+     * the lab had no connection to that chain, and only the environment's report stands (`unchecked` says so).
+     */
+    readonly checked?: {
+        readonly before: ChainMoment;
+        readonly after: ChainMoment;
+    };
+    /** Why the lab could not check the advance itself (no connection to the chain). */
+    readonly unchecked?: string;
+}
+export interface AdvanceBlocksRequest {
+    /** A chain id the control lists (`EnvironmentTime.chains`). */
+    readonly chain: string;
+    /** Blocks to add, at least 1. */
+    readonly count: number;
+    readonly signal: AbortSignal;
+    /** One line per stage, for the run's activity. */
+    readonly progress?: (message: string) => void;
+}
+export interface AdvanceClockRequest {
+    readonly chain: string;
+    /** Move the chain's clock forward by at least this many milliseconds. */
+    readonly ms: number;
+    readonly signal: AbortSignal;
+    readonly progress?: (message: string) => void;
+}
+/**
+ * An environment's control over its chains' progress. Every advance resolves only once the new blocks are finalized
+ * (as the environment finalizes them), and reports where each chain was before and after.
+ */
+export interface EnvironmentTime {
+    /** The chains it can advance, by the ids its endpoints use. */
+    readonly chains: readonly string[];
+    /** How its blocks come, in one sentence (`built on request with dev_newBlock`, …): shown with every advance. */
+    readonly production: string;
+    /** Add `count` blocks to `chain`. */
+    advanceBlocks(request: AdvanceBlocksRequest): Promise<ChainAdvance>;
+    /**
+     * Bring `chain`'s clock forward by at least `ms`, by the chain's own means (for example building the blocks whose
+     * stamps cover it). Absent when the chain's clock cannot be moved: `clockUnsupported` says why.
+     */
+    advanceClock?(request: AdvanceClockRequest): Promise<ChainAdvance>;
+    /** Why the chains' clock cannot be moved, when `advanceClock` is absent; one sentence. */
+    readonly clockUnsupported?: string;
+}
+/**
+ * A chain's day (6 October 2026): a host takes the period of a person's allowances (a UTC day) from the wall clock, so
+ * a chain is usable only while its own clock is on the wall clock's day. A chain whose clock runs faster than the wall
+ * clock (a relay-less dev node stamps each block a fixed slot after its parent) leaves that day before the wall clock
+ * does: its day ends then, and from then on claims and new people fail until a reset gives a new chain.
+ */
+export interface ChainDay {
+    readonly chain: string;
+    /** The node's block time, milliseconds. */
+    readonly blockTimeMs: number;
+    /** The pace that block time gives (`ChainPace`: fast or real time), or `custom`: a block time the config sets itself. */
+    readonly mode: ChainPace | "custom";
+    /** The environment's config chose it (`pace` or `blockTime`); else the adapter's default, fast. */
+    readonly modeSet: boolean;
+    /** The chain's clock at the latest reading (`Timestamp.Now`, epoch ms) and the wall clock then. */
+    readonly clock: number;
+    readonly readAt: number;
+    /** Chain milliseconds per wall millisecond between the first and the latest reading; absent until two readings. */
+    readonly pace?: number;
+    /** When (wall epoch ms) its clock reaches the wall clock's next midnight; absent while it does not run ahead. */
+    readonly endsAt?: number;
+    /** Its clock is on a later day than the wall clock already. */
+    readonly ended: boolean;
+}
+/**
+ * A start refused because a chain's day has ended before it started (its clock is on a later day than the wall
+ * clock's): carried on the thrown error as `chainDayEnded`, so an entry point can offer a new chain. A kept chain
+ * (backlog 183) is replaced by a start that asks `replaceKept`.
+ */
+export interface ChainDayEnded {
+    readonly chain: string;
+    /** Whole hours its clock is ahead of the wall clock. */
+    readonly hoursAhead: number;
+    /** The chain was kept between starts: a start with `replaceKept` discards it for a new one. */
+    readonly kept: boolean;
+    /** Its pace (`ChainDay.mode`): a person told how to keep a chain for days is not told to set what is set. */
+    readonly mode: ChainPace | "custom";
+}

package/core/ports/src/driven/environment/environment-time.js

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