@parity/product-lab 0.0.1-placeholder → 0.1.1

package/adapters/browser/playwright/src/worker-hold.js

@@ -0,0 +1,115 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const HOLD_LIMIT_MS = 3_000;
+export class WorkerHold {
+    socket;
+    observed;
+    nextId = 0;
+    pending = new Map();
+    sessions = new Map();
+    held = new Map();
+    seen = new Map();
+    waiters = new Map();
+    closed = false;
+    constructor(socket, observed) {
+        this.socket = socket;
+        this.observed = observed;
+        socket.addEventListener("message", (event) => this.onMessage(JSON.parse(String(event.data))));
+        socket.addEventListener("close", () => this.close());
+    }
+    static async open(port, observed) {
+        const version = (await (await fetch(`http://127.0.0.1:${port}/json/version`)).json());
+        if (!version.webSocketDebuggerUrl)
+            throw new Error(`The browser's debugging port ${port} names no browser endpoint`);
+        const socket = new WebSocket(version.webSocketDebuggerUrl);
+        await new Promise((resolve, reject) => {
+            socket.addEventListener("open", () => resolve(), { once: true });
+            socket.addEventListener("error", () => reject(new Error(`Could not connect to the browser's debugging port ${port}`)), { once: true });
+        });
+        const hold = new WorkerHold(socket, observed);
+        await hold.send("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: true, flatten: true, filter: [{ type: "page" }, { type: "iframe" }, { exclude: true }] });
+        return hold;
+    }
+    release(targetId, waitMs = 1_000) {
+        const held = this.held.get(targetId);
+        if (held) {
+            held.release();
+            return Promise.resolve(true);
+        }
+        if (this.seen.has(targetId))
+            return Promise.resolve(this.seen.get(targetId));
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => { this.waiters.delete(targetId); resolve(false); }, waitMs);
+            timer.unref?.();
+            this.waiters.set(targetId, [...(this.waiters.get(targetId) ?? []), (wasHeld) => { clearTimeout(timer); resolve(wasHeld); }]);
+        });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const held of this.held.values())
+            held.release();
+        for (const { reject } of this.pending.values())
+            reject(new Error("The worker hold closed"));
+        this.pending.clear();
+        if (this.socket.readyState === WebSocket.OPEN)
+            this.socket.close();
+    }
+    send(method, params = {}, sessionId) {
+        if (this.closed)
+            return Promise.reject(new Error("The worker hold is closed"));
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+        });
+    }
+    onMessage(message) {
+        if (message.id !== undefined) {
+            const pending = this.pending.get(message.id);
+            this.pending.delete(message.id);
+            if (message.error)
+                pending?.reject(new Error(message.error.message));
+            else
+                pending?.resolve(message.result);
+            return;
+        }
+        if (message.method === "Target.attachedToTarget")
+            void this.attached(message.params, message.sessionId);
+        if (message.method === "Target.detachedFromTarget")
+            this.sessions.delete(String(message.params?.sessionId));
+    }
+    async attached({ sessionId, targetInfo, waitingForDebugger }, parentSession) {
+        this.sessions.set(sessionId, targetInfo.targetId);
+        const resume = () => this.send("Runtime.runIfWaitingForDebugger", {}, sessionId).catch(() => undefined);
+        if (targetInfo.type !== "worker") {
+            await this.send("Target.setAutoAttach", { autoAttach: true, waitForDebuggerOnStart: true, flatten: true, filter: [{ type: "worker" }, { type: "iframe" }, { exclude: true }] }, sessionId).catch(() => undefined);
+            await resume();
+            return;
+        }
+        const parent = parentSession ? this.sessions.get(parentSession) : undefined;
+        const settle = (wasHeld) => {
+            this.seen.set(targetInfo.targetId, wasHeld);
+            for (const waiter of this.waiters.get(targetInfo.targetId) ?? [])
+                waiter(wasHeld);
+            this.waiters.delete(targetInfo.targetId);
+        };
+        if (!waitingForDebugger || (parent !== undefined && !this.observed(parent))) {
+            await resume();
+            settle(false);
+            return;
+        }
+        let release;
+        const released = new Promise((resolve) => { release = resolve; });
+        this.held.set(targetInfo.targetId, { sessionId, ...(parent ? { parent } : {}), release, released });
+        const limit = setTimeout(release, HOLD_LIMIT_MS);
+        limit.unref?.();
+        settle(true);
+        await released;
+        clearTimeout(limit);
+        this.held.delete(targetInfo.targetId);
+        await resume();
+        await this.send("Target.detachFromTarget", { sessionId }).catch(() => undefined);
+    }
+}

package/adapters/chain/papi/README.md

@@ -0,0 +1,203 @@
+# @product-lab/chain-papi
+
+Chain adapter over [polkadot-api](https://papi.how): implements the chain ports
+of `@product-lab/ports/chain` (refactor step 3).
+It runs on polkadot-api 3.x (3.2.1 since 2 October
+2026), whatever version the apps under test use: see
+[Beside polkadot-api 2.x apps](#beside-polkadot-api-2x-apps).
+
+`PapiChainAccess.historicalStorage(pallet, entry, keys, blockHash)` decodes
+state through the node's `state_getStorage` RPC and block-specific metadata.
+It reads a finalized block after polkadot-api has released its chainHead pin,
+provided the node still retains that block's state. The consumer's typed `api`
+remains available for live reads. `storage(pallet, entry, keys, blockHash)` falls back to
+this read (absent values as the entry's default) when polkadot-api no longer pins the block: it
+unpins every finalized block below the newest one, at once on a chain with short blocks (backlog 33,
+seen at 250 ms blocks). Only the node's own answer that the state is gone stays `BlockUnavailableError`
+(`tests/unpinned-storage.test.ts`). For a block it no longer pins, polkadot-api first tries the node's `archive_v1_storage`
+and `archive_v1_header` and logs their refusal: the "RpcError: Method not found" stacks that every default-session run
+printed (backlog 90). Since 4 October 2026 `storage()` asks the node's `rpc_methods` once, and on a node that lists no
+`archive_v1_storage` it reads a named block from the node's state directly. polkadot-api is still used for named heads
+(`finalized`, `best`), and for every read on a node that offers archive_v1 or does not answer `rpc_methods`.
+
+| Class / function | Port | What it does |
+| --- | --- | --- |
+| `PapiChainAccess<Api>` | `ChainAccess`, `ChainHistory` | One polkadot-api client. The constructor does no I/O and refuses an endpoint that is not loopback (`LoopbackUrl` from `@product-lab/domain`: `localhost`, 127.0.0.0/8, `::1`; ws, wss, http or https) unless `options.publicEndpoint: { reason }` opts in. The opt-in is exposed as `publicEndpoint` (`{ url, reason }`, the URL without credentials, query or fragment) for the caller to record, and it covers the `ChainHistory` reads too, which use the same client; that same sanitized form (never the raw URL) is what every thrown message names, so an opted-in endpoint's credentials or API key never appear in an error (and so never reach a caller's `FetchRecord.detail`, for example `DeployedRuntimeSource`'s); `open()` (or `PapiChainAccess.connect(url, options)`) creates it. `api` is the untyped API, or the consumer's typed API from `options.api` (`(client) => client.getTypedApi(descriptors)`). Reads genesis, storage, constants and metadata, and `runtime(at?)` (Phase 6: code hash over `state_getStorageHash(":code")` and the runtime version, for the `deployed` version source, through the same checked connection). `close()` refuses reuse at once (idempotent) but defers destroying the polkadot-api client by `options.closeGraceMs` (default 2000ms, unref'd): creating a client makes polkadot-api eagerly and permanently chainHead-follow (`observable-client`'s `chainHead.js`, no way to opt out), including a per-block runtime-change "subfollow" that issues one request the moment it connects; destroying the client while that request is still in flight throws `Error: Not connected` from a stray retry timer with no promise chain to catch it, uncaught, ~250ms later, even though this class had already closed cleanly; the grace period lets that request settle first (has the full mechanism and why it cannot be fixed structurally without patching the dependency). Seen on 0.18.8; #1449 (0.19.3) stops that retry. Every socket is closed within a bound ([Closing connections](#closing-connections)). `client` exposes the polkadot-api client to consumers that need more than the port. `finalizedHead()`/`bestHead()` and `ChainHistory` (tx-landed) all read the plain JSON-RPC (`chain_getFinalizedHead`, `chain_getBlockHash`, `chain_getHeader`, `chain_getBlock`, `state_getStorage` at the block hash, decoded with that block's own metadata, cached per spec version) rather than the chainHead-follow-derived `getFinalizedBlock()`/`getBestBlocks()`, narrowing (not eliminating, see `close()` above) exposure to the same defect. `ChainHistory`: blocks by number or hash, the blake2-256 hashes of a block's extrinsics, an extrinsic's dispatch result from the block's `System.Events` and an account's `System.Account` nonce; a block or state the node no longer has reads as `undefined` (and, since 29 September 2026, the account watch's reads below) |
+| `PapiTransactionSubmitter` | `TransactionSubmitter` | Signs through polkadot-api 3.x's `createSubmitAndWatch` against the finalized block (the mortality anchor, `mortality: { mortal: true, period: 64, at }`, a period or `mortal: false` from `options.signing` kept; nothing is pinned, see "Signing block" below), merges `options.signing` (for example a runtime's custom signed extensions) into every submission, records signing facts (signing block, runtime version, nonce, mortality, genesis) in the request's diagnostics, calls `onSubmitted` with the `SignedTransaction` (hash, signer, signing block, decoded nonce and mortality bounds) when polkadot-api reports it created (signed), before it can land, and tracks the transaction to finality, appending each inclusion change before finality to `diagnostics.inclusionMoves`. Signs with `SubmitRequest.nonce` when given (over a `nonce` in `options.signing`); `nonces` reads the genesis hash (once) and an account's next nonce (`AccountNonceApi.account_nonce` at the best block, as polkadot-api itself does), which the application's `SigningQueues` use to allocate nonces in order |
+| `decodeCompact(bytes)`, `eraBounds(bytes, signedAt)` | | The `CheckNonce` compact and the `CheckMortality` era as Substrate reads them (`Era::birth`, `Era::death` for the signing block) |
+| `trackTransaction(events, signal, label, timeoutMs, onSignedHash?, onInclusionMove?)` | | The finality tracker: `included` (the first inclusion, progress only) and `finalized` (only from a `finalized` event, with that block's receipt) promises. An inclusion that moves to another best block, or that a reorg retracts, before finality fails nothing: each change goes to `onInclusionMove` (`InclusionMove`: `{ from, to, at }`, `from`/`to` `{ hash, number, index }` or `null` for no best block) and tracking goes on, so a transaction re-included elsewhere still succeeds from the finalized block. A stream ending before finality, abort, error or timeout rejects both (the error names where it was last seen): the outcome is unknown, for the caller's reconciliation. Nothing is retried or resubmitted. See "Inclusion that moves before finality" below |
+| `toTxCreator(signer)` | `Signer` | The polkadot-api 3.x signer (`AccountTxCreator`, polkadot-api's `CommonSignerTxCreator`) for a port signer: a `KeySigner` (for example from `@product-lab/keys-sr25519`) through `getTxCreator`; a polkadot-api 3.x `TxCreator` as it is; a polkadot-api 2.x signer (`PolkadotSigner2`, `signTx(callData, extensions, metadata, atBlockNumber)`: what a product SDK on 2.x hands out, for example a host identity's signer reached through its app page) through a bridge that fills in the nonce and the common extensions with polkadot-api's own enhancers and hands only pipeline zero to `signTx` in runtime order, as 2.x did (the enhancers add them in their own order; a host may write a V4 extrinsic's extensions in the order it gets them, as truAPI host 0.23, 0.25 and 0.26 does on a chain with no `VerifyMultiSignature`) |
+| `withSignedExtensions(creator, publicKey, seen)` | | The creator with every signed extension filled in before `seen` reads them (`SignedExtensions`: `{ id, extra, additionalSigned }` hex): how the submitter records the nonce, era and genesis it signs, and how a test signs without submitting and reads them. Each enhancer keeps an extension already present, so the creator signs exactly what `seen` read |
+| `src/errors.ts` (internal) | `ChainAccess` | The adapter's edge classifier (listed in `ERROR_CLASSIFIERS`), the one module here that reads error text: `isMissingBlock` (a node's words for a block or state it does not hold; JSON-RPC protocol errors such as -32601 "Method not found" are not, by their code), `isNotPinned` (`instanceof` polkadot-api's `BlockNotPinnedError`), `blockUnavailable` (either, as the domain's `BlockUnavailableError`). `storage()` rejects with `BlockUnavailableError` for such a block, so core skips it by type |
+
+## Closing connections
+
+Since 2 October 2026 the client's sockets are `ws` WebSockets the access records. After `close()` destroys the
+client, a socket still open 1 s later is cut (`terminate()`). Two things used to leave a socket open, and the process
+alive, when an endpoint stopped answering: Node's own `WebSocket.close()` waits for the peer's close frame with no
+bound, and polkadot-api's ws-provider drops a socket whose connection timed out (5 s) without closing it. A Notes
+fork run whose live freshness reads timed out held four public sockets for nine minutes.
+`tests/close-unresponsive.test.ts` drives both cases against a loopback endpoint that never answers, and
+`composition/tests/fork-live.test.ts` the live runtime read; with the cut disabled all three fail.
+
+
+The account watch's reads (`ChainHistory`, since 29 September 2026): `signedExtrinsics(block, accounts)` gives a block's extrinsics one of the accounts signed, with their hashes (the signer is read from each signed version-4 extrinsic's `MultiAddress::Id`, `src/extrinsic-signer.ts`; unsigned and general extrinsics have none), and `pendingExtrinsics(accounts)` the pool's (`author_pendingExtrinsics`; `undefined` when the node does not offer the method, `isMethodUnavailable` in `src/errors.ts`). `poolAwareNonce(account)` (2 October 2026, backlog item 17k) is the node's own next nonce for the account, `system_accountNextIndex` asked by SS58 address: its nonce at the best block plus its transactions in the pool, every sender's and every format the pool holds; `undefined` without the method. Live on the People fast chain (omni-node), three `//Alice` remarks in flight: 6 while the nonce at the best block was 3 and `author_pendingExtrinsics` held 3; a read before the node imported them answers the best block's nonce.
+
+`extrinsics(block)` supplies the complete block ledger without account filtering: every index and blake2-256 hash,
+including unsigned calls, general v5 extrinsics, foreign signers, other address forms and malformed encodings.
+`src/extrinsic-decoder.ts` decodes addresses, actual signature bytes, transaction extensions and call names with
+the parent state's runtime metadata (the runtime that executed the block, including a runtime upgrade block).
+Metadata v14 extrinsic type parameters and v15/v16 address/signature/call types are supported. Standard v4 account
+signatures contain the bare signature bytes, excluding the `MultiSignature` discriminator, for comparison with host
+evidence. Index, Raw, Address32, Address20 and unfamiliar address forms retain a readable address and explicit
+signer lookup gaps. A general v5 extrinsic with one enabled standard authorization (`VerifyMultiSignature` `Signed`)
+names its claimed account and decodes complete, as a signed v4 preamble does (backlog 88, 4 October 2026); one whose
+optional authorizations are all absent, in a runtime with FRAME's `AuthorizeCall`, was authorized by its own call
+(`AUTHORIZED_CALL_ORIGIN_GAP`: no account origin, so the pool and block readers skip it as they skip a bare call; in a
+finalized block's reading, `extrinsics(blockHash)`, it is the chain's origin: complete, with `chainOrigin` saying so,
+since only the runtime's own authorization let it in; `tests/general-extrinsics.test.ts`); a
+filled optional authorization is named in its gap, except People's `AsResources` (a resource claim: an
+anonymous ring-VRF proof, no account by design), which is read and decodes complete with `resourceClaim` (the claim,
+its ring index and revision, and the call's one account argument as `beneficiary`; `tests/as-resources.test.ts`, on
+four claims a truAPI CLI host submitted on the lab's local People chain); anything else keeps `GENERAL_UNREAD_ORIGIN_GAP`. Unknown versions and malformed
+fields remain entries with a decode gap. Missing, unsupported or pruned metadata retains all entries too.
+Bare v5 uses the same preamble-then-call framing as bare v4. Legacy metadata v14/v15 records only the lowest
+supported extrinsic version, so `[4]` also permits decoding a bare v5 call. This exception never authorizes the
+call: it still has an unsigned-origin gap. General/signed unsupported-format checks and v16's full version list
+remain enforced. SDK source: [bare v4/v5 framing](https://github.com/paritytech/polkadot-sdk/blob/eeb597f61b9/substrate/primitives/runtime/src/generic/unchecked_extrinsic.rs#L108),
+[v14's lowest-version conversion](https://github.com/paritytech/polkadot-sdk/blob/eeb597f61b9/substrate/primitives/metadata-ir/src/v14.rs#L138)
+and [v15's lowest-version conversion](https://github.com/paritytech/polkadot-sdk/blob/eeb597f61b9/substrate/primitives/metadata-ir/src/v15.rs#L87).
+Unsigned calls alone never set `chainOrigin`. When the executing parent runtime exposes the checked three-input
+`TaggedTransactionQueue.validate_transaction` API, the adapter validates the exact unsigned extrinsic using
+metadata-encoded `TransactionSource.External` and the parent block hash. Only the decoded, complete
+`Err(Invalid(MandatoryValidation))` result supplies origin evidence and clears the unsigned-origin gap. FRAME
+Executive returns that result for mandatory dispatch, which Substrate permits only for inherent extrinsics;
+`BadMandatory`, `BadProof`, `Unknown`, valid transactions, malformed responses and absent/unsupported APIs never
+count as proof. The evidence string names the decoded call, parent runtime hash and exact extrinsic hash. Signed,
+general and malformed entries are never checked as inherents. This relies on the runtime API's Substrate semantics,
+not a pallet/call name. When the legacy metadata RPC returns v14 without API schemas, the adapter requests
+`Metadata_metadata_at_version(15)` at that same parent hash, accepts a complete canonical optional-bytes response
+containing v15 metadata, and otherwise keeps v14 decoding and its origin gap. The result enum is decoded from
+the runtime's metadata; its byte index is never assumed. Source evidence inspected at SDK commit `eeb597f61b9`:
+[FRAME Executive's mandatory validation refusal](https://github.com/paritytech/polkadot-sdk/blob/eeb597f61b9/substrate/frame/executive/src/lib.rs#L917)
+and [the inherent-only validity contract](https://github.com/paritytech/polkadot-sdk/blob/eeb597f61b9/substrate/primitives/runtime/src/transaction_validity.rs#L78).
+Tests:
+`tests/extrinsic-decoder.test.ts` and `tests/chain-history.test.ts`; they use a small runtime metadata fixture and
+do not start chains. `tests/general-extrinsics.test.ts` decodes five real v5 general extrinsics from a public testnet's
+People chain with that runtime's metadata v16, kept gzipped in `tests/fixtures/` (its README names the blocks and the
+read-only source): the remark complete with its account, the four self-authorized calls skipped, a pool of all five
+complete; controls without `AuthorizeCall` and with a filled optional authorization. Controls include legacy bare-v5 decoding, v16/general/signed/malformed refusal, exact parent
+v15 metadata retrieval, changed result-enum indices and absent/malformed/wrong-version metadata fallback.
+
+Pause inspection (backlog 17, 30 September 2026):
+`accountState(account)` reads `System.Account` at the finalized block (nonce, free, reserved, frozen as decimal
+strings) and `blockEvents(hash, accounts?)` decodes a block's `System.Events` as plain values (`src/plain-value.ts`:
+`plainValue` turns binaries and bigints into strings; `mentionedAccounts` names the given accounts an event mentions).
+Tests: `tests/plain-value.test.ts` and the chain-access tests with a fake client.
+
+```ts
+import { ChainConnection, TransactionExecutor } from "@product-lab/core/chain";
+import { PapiChainAccess, PapiTransactionSubmitter } from "@product-lab/chain-papi";
+
+const people = PapiChainAccess.connect(ws, { api: (client) => client.getTypedApi(descriptors) });
+const chain = new ChainConnection(people, signal, { activity });           // closes `people` when `signal` aborts
+const transactions = new TransactionExecutor(new PapiTransactionSubmitter(people, { signing }), journal, {
+  signal, chain: "people", mode: "finalized", validator,                    // validator: the integration's ReceiptValidator
+});
+```
+
+Tests: `tests/errors.test.ts` runs the classifier on the words nodes and polkadot-api use, with negative controls
+(an unrelated failure, a protocol error that says "not found", an error that only borrows the class's name), throwing
+polkadot-api's own `BlockNotPinnedError`.
+
+Entry points, examples and tools construct it; other adapters take the
+`ChainAccess` port through their options instead (for example
+`preparePeopleGenesis` in `@product-lab/env-relayless`). Unit tests use a fake
+polkadot-api client; no test starts a chain.
+
+| | |
+| --- | --- |
+| Nx project | `chain-papi` |
+| Tags | `scope:provider`, `type:adapter` |
+| Exports | `src/index.ts`: `PapiChainAccess`, `ChainApiFactory`, `PapiChainAccessOptions`, `PublicEndpoint`, `UnsafeChainApi`, `PapiTransactionSubmitter`, `PapiTransaction`, `PapiTransactionSubmitterOptions`, `decodeCompact`, `eraBounds`, `withSignedExtensions`, `SignedExtensions`, `toTxCreator`, `AccountTxCreator`, `PolkadotSigner2`, `trackTransaction`, `TransactionEvents`, `InclusionMove`, `TrackedInclusion` |
+| Depends on | `@product-lab/ports`, `@product-lab/domain` (`LoopbackUrl`), `polkadot-api` 3.2.1, `@polkadot-api/ws-provider` 0.9.1, `@polkadot-api/signers-common` 0.4.0 (the nonce and common-extension enhancers), `ws` 8.21.3 (the sockets `close()` can cut; `@types/ws` in the dev dependencies), `@polkadot-api/metadata-builders` 0.15.2 and `@polkadot-api/substrate-bindings` 0.21.2 (the versions that polkadot-api pins; `ChainHistory`'s decoding and blake2-256, and the metadata the 2.x bridge orders extensions by); `@polkadot-labs/hdkd-helpers` 0.0.34, `rxjs` 7.8.2 and `@product-lab/contract-chain` in its tests (dev dependencies) |
+| Used by | the composition root (`composition/src/chain-connections.ts`), `examples/notes` and another example, `tools/verify` |
+
+`RpcStatementStoreReader(ws)` (backlog 91) implements `StatementStoreReader` over a People node:
+`statements(query)` subscribes to the topics and checks each statement's Sr25519 proof (with `held`, backlog 99, it
+returns once the node's answers count `remaining` down to 0, an empty store included, so a store can be read whole with
+no topics), and `allowanceAt(account,
+"best" | "finalized")` (backlog 116) reads `:statement_allowance:` ++ account at that head, naming the block. A node
+accepts a statement against the best block but removes, at the finalized one, the statements of an account it finds no
+allowance for, so a write stays only once its allowance is finalized (`tests/statement-store-reader.test.ts`).
+
+## Signing block
+
+polkadot-api 3.x builds a transaction from the best block's runtime and hands the signer (`TxCreator`) a payload with
+no extensions; the signer computes the nonce (at the best heads) and the mortality. The submitter reads the finalized
+block and passes it as the mortality anchor (`mortality.at`); polkadot-api reads nothing at the anchor, so nothing is
+pinned (no `hodlBlock`). Until 2 October 2026 the submitter ran on polkadot-api 2.2.2, whose `signSubmitAndWatch({ at })`
+read the runtime of `at` after its own hold had ended, and so held the block it read until the signer was called.
+The live check
+`tools/verify/live/chain/papi-pinning.ts` drives the same fresh-client race on a relay-less chain.
+
+`tests/fakes.ts` models polkadot-api 3.x's `createSubmitAndWatch` (`fakeTransaction`, and `chainTransaction` over a
+`FakeChain` with reorgs): each transaction calls the submitter's creator with the payload and bindings 3.x builds,
+over a small runtime metadata with `CheckMortality`, `CheckNonce` and `CheckGenesis`
+(`fixtureSigningMetadataHex`). So the tests sign for real: `tests/transaction-submitter.test.ts` checks the
+extrinsic's signature over exactly the extensions the diagnostics record, a 2.x signer handed those extensions
+(through the submitter and on its own), a 3.x creator used as it is, and a client without `hodlBlock` signing once at
+the block it read while the chain finalizes another.
+
+Contract kit: `tests/contract.test.ts` runs the [chain contract kit](../../../contracts/chain/README.md) over an in-process fake client, declaring `access`, `submit` and `scriptedOutcomes` (not `history`: the fake has no runtime metadata to decode events and accounts with), plus five negative controls (a submitter that returns an unfinalized receipt, one that hides a dispatch error, one that never reports its signed transaction, one that fails when the inclusion moves or is retracted, as this tracker did before 25 September 2026, failing `submit-inclusion-moves` and `submit-retracted`, and one returning the first inclusion's receipt, failing `submit-inclusion-moves`); against a live chain, declaring `access`, `submit` and `history`, only with `PRODUCT_LAB_KIT_LIVE=1` and `PRODUCT_LAB_KIT_CHAIN_WS` (not run by the gates). The 2.x control "a client whose holds hold nothing fails `submit-finality-advances`" went with the pinning; the case itself still runs and passes. `tests/chain-history.test.ts` covers the history reads over plain JSON-RPC, the unknown-block handling and the nonce and era decoding.
+
+## Beside polkadot-api 2.x apps
+
+The apps under test and the product SDK (`@parity/product-sdk-host` 0.24.0: `polkadot-api` ^2.1.6) stay on
+polkadot-api 2.x; Bun installs both. Nothing of polkadot-api crosses between an app and the lab: apps reach the chain
+through their host. What crosses inside a lab:
+
+- **Signers.** Give the submitter a `KeySigner`; a 2.x signer (`PolkadotSigner2`) works through `toTxCreator`'s
+  bridge. It forwards only the extensions declared for runtime pipeline zero, in runtime order; enhancers
+  can fill extensions belonging to other pipelines, and serializing their bytes corrupts a legacy transaction's
+  call. A nonzero pipeline or an undeclared pipeline zero fails before the signer runs. Declared extensions with no
+  supplied value stay absent: a host can fill its own authorization (such as `VerifyMultiSignature`) to sign V5.
+  The 2.x interface cannot convey a pipeline version. `tests/signer-pipelines.test.ts` independently decodes the
+  resulting legacy transactions, preserves authorization when pipeline zero declares it, checks the nonzero refusal, and preserves
+  omitted authorization. A 2.x `getPolkadotSigner(...)` result is such a signer,
+  but derive keys as `KeySigner`s instead.
+- **Typed APIs.** `PapiChainAccess`'s client is 3.x. Descriptors generated by a 2.x `papi` CLI have the same values
+  but 2.x types (no `requiredExtensions`): generate the lab's own with the 3.x CLI from the same metadata, into a
+  path of the lab's own (`papi generate` with `options.noDescriptorsPackage` and a config of its own).
+- **Plain values** (`Enum(...)`, `Binary` helpers, `customSignedExtensions`) are the same in both.
+
+An example whose app and lab share one `package.json` keeps polkadot-api 2.2.2 for the app and reaches 3.x only
+through this package's exports.
+
+## Inclusion that moves before finality
+
+Until 25 September 2026 the tracker failed a transaction with "inclusion moved to another block" when a best-block or finalized event named a block other than its first inclusion, and with "inclusion retracted by a reorg" when a best-block event no longer found it. This failed a lifecycle run on an Engine fork whose transaction was included in one best block and then reported in a sibling (a verification record of 24 September 2026). Now finality decides (the user's option B):
+
+- a move among best blocks updates the tracked inclusion and is recorded (`diagnostics.inclusionMoves`, `{ from, to, at }`);
+- a retraction is recorded as a move to `null`; the transaction may be included again, so tracking goes on;
+- `finalized` resolves only on polkadot-api's `finalized` event, with that block's receipt;
+- no finality within the timeout, or a stream that ends first, rejects both promises: the outcome is unknown, and the caller reconciles it from finalized state (`CheckTransactionLanded` through the Scheduler), which never retries a possibly included mutation;
+- nothing is signed or sent again.
+
+`tests/track-transaction.test.ts` covers the event sequences; `tests/transaction-submitter.test.ts` runs A → B → finalized B, A → retracted → C → finalized C and A → retracted → timeout through `PapiTransactionSubmitter` and asserts one `createSubmitAndWatch`, one signature, one broadcast and one `onSubmitted` in each.
+
+Tests: `bunx nx run chain-papi:test`.
+
+Private, workspace-only package. Consumers will install the single umbrella package `@parity/product-lab` once it is published.
+
+## Pending and account observations (1 October 2026)
+
+`pendingExtrinsicsEvidence(accounts)` and `signedExtrinsicsEvidence(block, accounts)` return recognized account transactions, total inspected entries and exact-hash decoding gaps. Version4 signed preambles and version5 general `VerifyMultiSignature` authorizations use the executing runtime's declared metadata types, not fixed offsets. General account evidence describes metadata-defined bytes; the lab verifies neither a v4 nor a v5 signature (the chain included it). A general extrinsic its own call authorized (`AuthorizeCall`) is no account's transaction, so it leaves a reading complete; any other unread general authorization stays a gap. Unsupported custom authorization, lookup-dependent addresses and malformed fields cannot become a complete empty result. Legacy array readers now refuse partial coverage rather than omit undecodable accounts. A pool reading whose head changed while it was read (a block authored in between, every few seconds on a local chain) is read again, up to three times, before it is reported incomplete. A People resource claim (`AsResources`, no signer by design) counts for the account it names (`resourceClaim.beneficiary`): that account's transaction when it is asked about, nobody's otherwise, never a gap; a claim that names no readable account is a gap that says so (backlog 176). The legacy readers' refusal says in words how many transactions were read and why the others could not be (6 October 2026, backlog 155: on Notes' fast the lab's check after a failed Publish answered "cannot tell" from that race alone).
+
+The adapter requests canonical metadata16 for its full version list and extension pipelines, falling back to15/14 only with their existing version limitations. Codec caching separates runtime code hashes even when specVersion is unchanged; nodes lacking that RPC use a per-state cache. Pool reads are bracketed by best heads: a changed context clears account attribution and is reported as partial. Block reads use the parent runtime. Unit controls never start chains.
+
+`extrinsics(blockHash, { includeCallArguments: true })` returns `callArguments` as plain JSON when the runtime call decodes completely, including
+its arguments and absence of trailing bytes. It uses the executing parent runtime, as the call names do. Missing
+metadata or an unreadable call leaves the arguments absent; authorization gaps remain independently visible.
+Ordinary block/account watches do not copy arguments. No arguments becomes `null`; nesting beyond 12 levels is
+`"…"`, independently of SCALE decoding completeness.

package/adapters/chain/papi/src/chain-access.d.ts

@@ -0,0 +1,178 @@
+import { type PolkadotClient } from "polkadot-api";
+import type { AccountExtrinsicEvidence, AccountState, BlockEvent, BlockRef, ChainAccess, ChainHistory, DispatchOutcome, FinalizedExtrinsic, PendingExtrinsic, RuntimeFingerprint, SignedExtrinsic } from "@parity/product-lab/ports/chain";
+/** The untyped API every chain supports. */
+export type UnsafeChainApi = ReturnType<PolkadotClient["getUnsafeApi"]>;
+/** Builds the consumer's API from the client, e.g. `(client) => client.getTypedApi(descriptors)`. */
+export type ChainApiFactory<Api> = (client: PolkadotClient) => Api;
+export interface PapiChainAccessOptions<Api> {
+    /** The API `api` exposes; default the untyped API. */
+    readonly api?: ChainApiFactory<Api>;
+    /** Client factory; default a polkadot-api client over a WebSocket provider. Tests inject a fake. */
+    readonly createClient?: (url: string) => PolkadotClient;
+    /**
+     * Opt in to an endpoint that is not on this machine. Loopback is the
+     * default (adapters/AGENTS.md); without this a public URL is refused. The
+     * reason is kept as `publicEndpoint` for the caller to record.
+     */
+    readonly publicEndpoint?: {
+        readonly reason: string;
+    };
+    /**
+     * How long `close()` waits before destroying the polkadot-api client;
+     * default `CLOSE_GRACE_MS`. See `close()`'s doc for why. Tests set this to
+     * `0` to assert on the client's `destroy()` synchronously.
+     */
+    readonly closeGraceMs?: number;
+}
+/** A public endpoint a caller opted in to: the URL without credentials, query or fragment, and why. */
+export interface PublicEndpoint {
+    readonly url: string;
+    readonly reason: string;
+}
+/**
+ * ChainAccess over one polkadot-api client. The constructor does no I/O and
+ * refuses an endpoint that is not loopback unless the caller opted in
+ * (`publicEndpoint`); `open()` creates the client (which connects in the background). Storage and
+ * constant reads use the untyped API, whatever `api` the consumer injected.
+ *
+ * ChainHistory reads use the plain JSON-RPC methods (`chain_getBlockHash`,
+ * `chain_getHeader`, `chain_getBlock`, `state_getStorage` at a block hash)
+ * decoded with the block's own runtime metadata, so they reach any block the
+ * node keeps, not only the ones the client follows. `finalizedHead()` and
+ * `bestHead()` read the same way (`chain_getFinalizedHead` /
+ * `chain_getBlockHash` with no block number, then `chain_getHeader`) rather
+ * than through the client's chainHead-follow subscription, whose per-block
+ * runtime-change tracking is not safely torn down by `close()` in
+ * observable-client 0.18.8 (docs/verification/2026-09-24-versions.md).
+ */
+export declare class PapiChainAccess<Api = UnsafeChainApi> implements ChainAccess<Api>, ChainHistory {
+    #private;
+    readonly url: string;
+    private readonly options;
+    /** Set when the caller opted in to a public endpoint; undefined on loopback. */
+    readonly publicEndpoint: PublicEndpoint | undefined;
+    /** Refuses a URL that is not loopback unless `options.publicEndpoint` gives a reason. */
+    constructor(url: string, options?: PapiChainAccessOptions<Api>);
+    /** Construct and open in one step. */
+    static connect<Api = UnsafeChainApi>(url: string, options?: PapiChainAccessOptions<Api>): PapiChainAccess<Api>;
+    open(): this;
+    /** The polkadot-api client, for consumers that need more than the port. */
+    get client(): PolkadotClient;
+    get api(): Api;
+    genesisHash(): Promise<string>;
+    /**
+     * The plain `chain_getFinalizedHead` RPC, not `client.getFinalizedBlock()`:
+     * that reads through polkadot-api's chainHead *follow* subscription, whose
+     * per-block runtime-change "subfollow" (observable-client 0.18.8,
+     * `chainHead/streams/follow.js`) is not safely torn down by `close()` —
+     * closing the connection while it is mid-flight can leave a retry timer
+     * that fires after the provider is gone and throws `Error: Not connected`,
+     * uncaught (docs/verification/2026-09-24-versions.md, "Live run"). Reading
+     * the head as a point-in-time RPC, the same way ChainHistory does below,
+     * never opens that subscription at all.
+     */
+    finalizedHead(): Promise<BlockRef>;
+    /** As `finalizedHead()`: `chain_getBlockHash` with no block number returns the current best hash. */
+    bestHead(): Promise<BlockRef>;
+    storage(pallet: string, entry: string, keys?: readonly unknown[], at?: string): Promise<unknown>;
+    /**
+     * Read decoded storage at an explicit block through the node's historical
+     * RPC, independently of the client's short-lived chainHead pin set. This
+     * is useful when a long UI journey finishes after its earlier finalized
+     * blocks have been unpinned by polkadot-api. The node must still retain
+     * that block's state. An absent value is `undefined`; with `orDefault` it is the entry's default, as
+     * `storage()` returns it (`storage()` falls back to this read for a block polkadot-api no longer pins).
+     */
+    historicalStorage(pallet: string, entry: string, keys: readonly unknown[], at: string, options?: {
+        orDefault?: boolean;
+    }): Promise<unknown>;
+    constant(pallet: string, name: string): Promise<unknown>;
+    metadata(at: string): Promise<Uint8Array>;
+    /**
+     * The runtime at a block (default the finalized head) over the legacy
+     * `state_getStorageHash(":code")` and `state_getRuntimeVersion` RPCs: the
+     * node hashes the code (blake2-256, the hash runtime upgrades authorize),
+     * so the code itself is never downloaded. Rejects when the node has no
+     * state for the block (pruned) or no code.
+     */
+    runtime(at?: string): Promise<RuntimeFingerprint>;
+    private request;
+    /** Whether the node lists `archive_v1_storage` in `rpc_methods`. A node that does not answer is taken to offer it: polkadot-api's own path, as before. */
+    private offersArchive;
+    /** undefined when the node answers that it does not have the block (or its state); other errors propagate. */
+    private unlessMissing;
+    private numberOf;
+    /** hash plus its number via `chain_getHeader`; used for a head the node just reported, so a missing header is an error, not `undefined` (contrast `block()`). */
+    private headerOf;
+    blockAt(number: number): Promise<BlockRef | undefined>;
+    block(hash: string): Promise<BlockRef | undefined>;
+    extrinsicHashes(blockHash: string): Promise<readonly string[] | undefined>;
+    /** Every block entry, decoded with the parent state's runtime: the runtime that executed the block, even at upgrades. */
+    extrinsics(blockHash: string, options?: {
+        includeCallArguments?: boolean;
+    }): Promise<readonly FinalizedExtrinsic[] | undefined>;
+    private bareExtrinsic;
+    /** The runtime's exact MandatoryValidation result proves mandatory/inherent dispatch, never a call-name guess. */
+    private inherentOrigin;
+    /** Metadata-driven account observations from the runtime that executed this block. */
+    signedExtrinsicsEvidence(blockHash: string, accounts: readonly string[]): Promise<AccountExtrinsicEvidence<SignedExtrinsic> | undefined>;
+    /** Legacy array result refuses incomplete coverage instead of silently calling unknown accounts absent. */
+    signedExtrinsics(blockHash: string, accounts: readonly string[]): Promise<readonly SignedExtrinsic[] | undefined>;
+    /**
+     * Pool observations use metadata at a head sampled before the pool, with a second head read afterwards. A block
+     * authored in between (every few seconds on a local chain) changes that context: the pool is read again, up to
+     * POOL_READS times, before the observation is reported incomplete.
+     */
+    pendingExtrinsicsEvidence(accounts: readonly string[]): Promise<AccountExtrinsicEvidence | undefined>;
+    /** One reading of the pool; `contextChanged`: a block was authored while it was read; `otherGaps`: it has gaps besides. */
+    private poolEvidence;
+    /** Legacy array result refuses incomplete coverage; undefined still means the author namespace is unavailable. */
+    pendingExtrinsics(accounts: readonly string[]): Promise<readonly PendingExtrinsic[] | undefined>;
+    private completeAccounts;
+    private accountExtrinsics;
+    dispatchOutcome(blockHash: string, index: number): Promise<DispatchOutcome | undefined>;
+    poolAwareNonce(account: string): Promise<number | undefined>;
+    accountNonce(account: string, at?: string): Promise<number>;
+    accountState(account: string, at?: string): Promise<AccountState>;
+    blockEvents(blockHash: string, accounts?: readonly string[]): Promise<readonly BlockEvent[] | undefined>;
+    /** The storage codecs of the runtime at a block (cached per spec version). */
+    /**
+     * The runtime metadata's decoder at `blockHash`, read a second time when the first read fails (backlog 217: an Asset
+     * Hub read during a busy step lost both its transactions to one failed read), else why it could not be read.
+     */
+    private builderOrWhy;
+    private builder;
+    /**
+     * Idempotent, and immediate from the caller's side: the access refuses
+     * reuse at once (`client`/`open()` throw "is closed" straight away). The
+     * underlying polkadot-api client's `destroy()` is deferred by
+     * `options.closeGraceMs` (default `CLOSE_GRACE_MS`, unref'd: never blocks
+     * the process from exiting) rather than called synchronously here.
+     *
+     * Why: reading any chainHead-derived state (`storage()`, `constant()`,
+     * `.api`, and `finalizedHead()`/`bestHead()` before this bug's fix) makes
+     * polkadot-api's `createClient()` eagerly and permanently subscribe to
+     * chainHead-follow the moment the client is created
+     * (`@polkadot-api/observable-client` 0.18.8, `chainHead/chainHead.js`:
+     * `merge(runtime$, bestBlocks$).subscribe(...)`, with no way to opt out
+     * through the public API) — including a per-block runtime-change
+     * "subfollow" that issues one `chainHead_storage` request for the current
+     * block's code hash as soon as it connects (`chainHead/streams/follow.js`,
+     * `withEnhancedFollow`'s "initialized" handling), and again, rarely, on an
+     * actual runtime upgrade. Destroying the client while that request is
+     * still in flight errors it synchronously (`@polkadot-api/raw-client`
+     * 0.3.0, `disconnect()`: `responses.forEach(r => r.onError(new
+     * DestroyedError()))`), and the subfollow's retry handler has no `isDone`
+     * guard (unlike its sibling for the main follow), so it unconditionally
+     * schedules a retry 250ms out that reissues `chainHead_follow` against the
+     * now fully torn down connection and throws `Error: Not connected`,
+     * uncaught, from a bare timer with no promise chain to catch it — even
+     * though this class had already closed cleanly (verified against the
+     * actual dependency source and a live run;
+     * docs/verification/2026-09-24-versions.md, "Live run"). There is no
+     * supported way to ask the client whether that request has settled, so
+     * this grace period gives it time to, before the connection this class
+     * owns is actually severed.
+     */
+    close(): void;
+}