@parity/product-lab 0.0.1-placeholder → 0.1.0

package/adapters/deploy/bulletin/README.md

@@ -0,0 +1,148 @@
+# @product-lab/deploy-bulletin
+
+The `Deployer` port (`@product-lab/ports/deploy`) over a local Bulletin and DotNS, plus what
+deploying and serving there needs: content addressing, the local gateway, `deployed-local`, manifest
+freshness, and the opt-in platform integration (DotNS, Bulletin, statement store, contracts).
+Refactor step 8 part a split it out of the temporary `@product-lab/platform`;
+the behaviour is the one
+verified live on 24 September 2026.
+Nothing here knows any product.
+
+`bulletin-deploy` is an **optional peer dependency** (since 2 October 2026): it is GPL-3.0-or-later while
+product-lab is Apache-2.0, and only those who deploy to Bulletin run it, so installing `@parity/product-lab` does not
+install it. A consumer that deploys adds `npm install --save-dev bulletin-deploy@0.21.0`; without it `BulletinDeployer`
+and `DotnsRegistrar` fail with `BulletinDeployMissingError`, which names the package, the pinned version and that
+command. Everything else here (content addressing, the gateway, DotNS reads, the platform actions) works without it.
+This repository installs it as this package's development dependency, so every in-repo flow is unchanged.
+
+## Classes and modules
+
+| Class / module | Port | What it does |
+| --- | --- | --- |
+| `BulletinDeployer` | `Deployer<BulletinDeployment>` | Constructed per environment with its loopback `PlatformEndpoints` (refused otherwise) and the ports `processes`, `files`, `clock`, `environment`, `rpc` (DotNS reads), optional `contentRpc` (bitswap), `connections`. With no manifest config, `deploy()` first resolves the requested name and reads its CAR from local Bulletin; it skips the tool only when the retrieved file set is exactly the build with equal bytes. The receipt says `status: "already-deployed"`, `deployMs: 0`, and records no upload process or process log (`log` is absent). Otherwise it runs the pinned `bulletin-deploy` 0.21.0 through `ProcessRunner` with the local-only environment file (written through `FileSystem`, 0600), the development phrase only in the child's environment and redacted from the log, inherited `BULLETIN_*`, `DOTNS_*`, `DEPLOY_*`, `SENTRY_*` and `MNEMONIC` removed, its tree watched by `ConnectionMonitor` and bounded by `timeoutMs` (default 15 minutes: a deploy still running is stopped and fails as timed out, and a stop that fails rejects with its reason instead of waiting for an exit); then `DeploymentCheck` resolves and reads back through `resolve`/`retrieve`, the CAR read back is compared with the uploaded one, and `deployed-app.json` is recorded with `status: "uploaded"` |
+| `DeploymentCheck`, `readBuild` | uses `Deployer` | The independent check through the port only: the name has content, the content read back is the resolved CID, every build file is there byte-equal. Any `Deployer` can be checked with it |
+| `DotnsResolver` | uses `JsonRpcClient` | Contenthash and `manifest` / `executable` records straight from the content resolver's storage (independent of `bulletin-deploy`) |
+| `DotnsRegistrar` | uses `Clock` | Commit and register a name with `bulletin-deploy`'s DotNS client, resolved exactly like its CLI with the local environment file. Loads the library with `loadBulletinDeploy` (option `loadLibrary` replaces it in tests) |
+| `BULLETIN_DEPLOY_VERSION`, `resolveBulletinDeploy`, `BulletinDeployMissingError`, `ModuleResolver` | | The pinned version (the optional peer in `package.json`, `tests/bulletin-deploy-tool.test.ts` holds them equal) and the resolution `bulletinDeployTool` and `loadBulletinDeploy` share: Node's `ERR_MODULE_NOT_FOUND` for the bare name becomes `BulletinDeployMissingError`, any other failure passes as it is |
+| `loadBulletinDeploy`, `BulletinDeployLibrary` | | `BulletinDeployLibrary` declares the part of bulletin-deploy the adapter uses (the DotNS client, the environment resolution), not the module's own type, so the package's declarations type-check where the optional peer is not installed (release rehearsal, 22 October 2026); `loadBulletinDeploy` returns the real module as it, so the compiler checks they agree. Loads `bulletin-deploy` in process with `BULLETIN_DEPLOY_TELEMETRY=off` and `BULLETIN_DEPLOY_UPDATE_CHECK=0` set only for the load and only where unset (the library decides telemetry once, when its module loads, and has no option for it); `process.env` is restored afterwards, also when the load fails |
+| `checkManifestFreshness`, `productConfigFor`, `FreshnessPlanner` | uses `FileSystem` | An app's declared `trustedProducts` against the manifest on the environment's DotNS; an absent record is missing, while a present malformed record fails with its product name. The planner refuses by default, or writes the host's `--product-config` |
+| `BulletinContentReader` | `ContentArchiver`; uses `JsonRpcClient` | Blocks over `bitswap_v1_get`, each checked against its CID; `retrieve(cid)` unpacks the CAR `bulletin-deploy` stores; `archive`/`reverify` answer dot.li |
+| `retrieveContent`, `ipfsGatewaySource`, `FetchBytes` (backlog A5) | | Every file under a CID from any block source, each block checked (`BulletinContentReader.retrieve` uses it); and blocks from an IPFS gateway's trustless raw requests (`/ipfs/<cid>?format=raw`, `application/vnd.ipld.raw`), trusted for nothing |
+| `content/` (`cid.ts`, `dag.ts`, `car.ts`) | | CIDv0/v1, sha2-256 and blake2b-256 verification, dag-pb and UnixFS trees, CARv1 build and read (moved from host-dotli through platform) |
+| `buildSiteCar` (`content/site.ts`) | | Packs a built site as one CAR of a UnixFS directory DAG (sha2-256 CIDv1, raw leaves up to 1 MiB, deterministic): the layout `bulletin-deploy` stores. Where no name service exists (relay-less chains) a caller stores it with `BulletinStore` and reads it back exactly like a deployment |
+| `DeployedContentGateway`, `gatewayReport`, `injectScriptTag` (re-exported from `@product-lab/domain` since backlog item 64: the lab's proxy in front of a dev server uses the same injector) | | Serves `RetrievedContent` on 127.0.0.1: deployed bytes unchanged except one host bridge tag in HTML when asked (a fixed `injectScript`, or `bridgeParam`: the loopback bridge a page names in its query, for a host with one bridge per session; a non-loopback value is refused with 400); `/.product-lab/gateway.json` reports digests; `/ipfs/<cid>?format=car` with a `ContentArchiver` |
+| `GatewayDestinations` | `DestinationServer`; uses `PortAllocator` | Phase2-nav: serves the content a name resolved to as a `HostApp` (one gateway per destination on a port from its range, the content read back by CID with every block verified, refused unless it is the requested CID and has an `index.html`); the app's URL carries the session's host bridge. The navigation bridge serves destinations no lab app declares through it (`LabNavigation`'s `nameService.server`) |
+| `runGateway`, `gatewayCommand`, `GatewayUsageError` | uses `JsonRpcClient`, `Clock` | The gateway program's logic (parse, resolve, require the expected CID, read back, serve; `--inject-script` or `--bridge-param`) with its ports injected, and the host app command for a given executable (the port may be the `{port}` placeholder). Backlog A5: `--ipfs-gateway <https origin>` reads content Bulletin does not give from that gateway (with `fetchBytes`, the HTTP transport the caller supplies), and the report's `source` says which answered and why (`kind`, `endpoint`, `fallbackReason`); content neither gives is refused naming both. The executable that wires the Node JSON-RPC clients is composition: `composition/src/gateway-program.ts` (`GATEWAY_PROGRAM`, refactor step 8). `--name` resolves as hosts do (dot.li: `app.<label>` first): `app.<name>`'s contenthash, else the name's own when `app.<name>` has none (no record, an empty contenthash, or no DotNS content resolver); a contenthash that is not an IPFS CID is refused without falling back, neither name having one is refused naming both, and both are read at one block. `--cid` is accepted when it is either name's CID, and that name is served; a pin that is neither is refused naming both. The report's `name` and the summary say which name was served and which the pin matched (26-27 October 2026). `--resolve-asset-hub <url>` resolves `--name` on that Asset Hub instead of `--asset-hub`, same rules, through a connection internal to this package (`src/dotns/read-only-rpc.ts`, not exported) that sends only `chain_getFinalizedHead`, `chain_getHeader`, `state_getStorage` and `childstate_getStorage` to that one endpoint and refuses any other method or endpoint before sending; one off this machine also needs `--allow-public-resolve` (`--allow-public` does not grant it), and the report's `publicRead` records the endpoint, the names read, the winner, the block (hash and number), the pin and every method sent; a pin it does not match is refused naming the endpoint (27 October 2026) |
+| `DeployedLocalLauncher`, `verifyServedApp`, `deployedLocalRequirements`, `parseLaunchMode`, `throwawayLabel` | uses `Deployer`, `Clock`, `IdGenerator` | `deployed-local`: build for a fresh throwaway product id, deploy through any `Deployer`, and give a host the gateway command (`hostApp({ hostBridgeUrl | bridgeParam })`); check what a host serves against the deployment (`verifyServedApp`, with `bridgeParam` requesting HTML as a session's page does; each request bounded by `timeoutMs`, default 30 000 ms, and an optional `signal`; an error status rejects) |
+| `PLATFORM_REQUIREMENTS` | data | What each platform block needs from an environment (chains and capabilities). The integration built from this adapter's parts, `platformIntegration`, moved to `@product-lab/composition/platform` in L1 (an adapter does not author lab integrations); its description follows |
+| `platformIntegration({ chains, rpc?, contentRpc?, clock?, ids?, contracts?, signer?, fundedSigner? })` (`@product-lab/composition/platform` since L1) | uses `ChainAccess`, `TransactionSubmitter`, `JsonRpcClient` | Actions `registerName`, `uploadToBulletin`, `submitStatement`, `deployContract`, `callContract` and assertions `nameResolves`, `contentRetrievable`, `statementAccepted`, `contractReturns`, `contractReturnsNumber`, each with `requires`. `chains` is a `ChainConnector` the caller supplies (for example `PapiChainAccess` plus `PapiTransactionSubmitter`, with `PEOPLE_SIGNING` on People; since backlog A7 it takes an optional `{ publicReason }`, the public network's opt-in, which `withChain` passes on); `rpc`, `clock` and `ids` are needed only by the DotNS, Bulletin-read and statement blocks (a block run without one names it). `contracts` names artifacts (absolute paths): `a {word} contract is deployed` deploys one, and `deployContract` publishes the outputs `address` and `block` (`$address` in a later step). `contractReturnsNumber` (`the contract {string} returns {int} from {string}`) calls a function without arguments (`get()`, `selectorOf`) at the finalized head and compares one decoded uint256. Every action with a sentence declares its text inputs, so its sentences load into a lab's registry, and the assertions read a feature step's values by kind (`string`, `string2`, `int`) as well as the named keys a direct caller passes (both fixed on 25 September 2026). `callContract` is the exception, see below. `fundedSigner: true` (backlog A7): the signer is an existing account the user funded, so `deployContract` needs `contracts` only, and on a writable public target (`offer.public.access: "read-write"`) it deploys over the network's public Asset Hub under its reason; every other mutating action still refuses a non-loopback endpoint, and reads use the public target's reason |
+| `BulletinStore`, `StatementStore`, `ReviveContracts` | chain ports | `TransactionStorage.store` with the reported CID checked; statement encode/sign, `statement_submit`, topic watch and the sudo allowance; pallet-revive deploy and read-only call (at a given block hash; default the finalized head); `selectorOf(signature)`, `decodeUint256(data)` |
+| `submitFinalized`, `DispatchFailedError`, `moduleError` | chain ports | Submit and wait for finality; a failed dispatch throws `DispatchFailedError` (`label`, `block`, the decoded `dispatchError`), and `moduleError` reads its `Pallet.Error` (`ReviveContracts.ensureMapped` accepts `Revive.AccountAlreadyMapped` from it, never from a message) |
+| `src/errors.ts` (internal) | | The adapter's edge classifier (listed in `ERROR_CLASSIFIERS`): `isContentMissing` (the node's `bitswap_v1_get` "Transaction not found", as a `JsonRpcError` from that method only: the deployer then redeploys a name whose Bulletin data is gone) and `isBlockUnavailable` (polkadot-api refusing a runtime call at an unpinned or unknown block: `callFinalized` reads again at a new head). Tests: `tests/errors.test.ts`, with negative controls |
+
+### `callContract`: no sentence and no declared inputs
+
+`platform.callContract` (title "Call a contract (read-only)", `mutates: false`, requires Asset Hub with
+`contracts`) makes a read-only pallet-revive call: `ReviveContracts.call(caller, address, input)`, with
+`inputs.address` as the contract and `inputs.input` as the call data (hex, default `0x`); the caller is the
+platform signer's address, or the development account when no signer is declared. It returns the call
+result. Unlike the other four actions it declares no `sentences` and no `inputs` (and no `description`),
+so:
+
+- no Gherkin step reaches it (the assertions `contractReturns` and `contractReturnsNumber` read contracts
+  from a feature instead);
+- `run_action` and the panel list it and can start it, but only without inputs: the run's inputs are
+  validated against the declared ones, so `address` is refused as an unknown input, and a run without
+  it has no contract address to call;
+- only code that runs the action's scenario step with `address` itself can use it, as
+  `tools/verify/live/deploy/platform-actions.ts` does.
+
+The source says so (`src/platform/platform-integration.ts`: "`artifact`, `address` and `input` still
+come from a direct caller"). This is a gap: declaring `address` and `input` as text inputs, and a
+sentence, would make it usable from `run_action`, the panel and features. `deployContract`'s
+`artifact` input (a path instead of a named contract) is in the same state.
+
+```ts
+// composition (an example or a tool): the Node system adapters in, the Deployer port out
+const deployer = new BulletinDeployer(platformEndpoints(environment.endpoints), {
+  processes, files, clock, environment: variables, rpc: new HttpJsonRpcClient(),
+  contentRpc: new WebSocketJsonRpcClient(), connections: new LsofConnectionMonitor(),
+});
+const launch = await new DeployedLocalLauncher(deployer, endpoints, { clock, ids }, { gatewayScript }).prepare({ build, runDir });
+host.launch({ app: launch.hostApp({ hostBridgeUrl }) });
+```
+
+## Package
+
+| | |
+| --- | --- |
+| Nx project | `deploy-bulletin` |
+| Tags | `scope:provider`, `type:adapter` |
+| Exports | `.` (`src/index.ts`: everything in the table above) |
+| Implements | `Deployer` (so `NameResolver`), `ContentArchiver`, `DestinationServer` (`@product-lab/ports/deploy`) |
+| Uses | `ProcessRunner`, `FileSystem`, `Clock`, `IdGenerator`, `EnvironmentVariables`, `JsonRpcClient`, `ConnectionMonitor` (`@product-lab/ports/system`); `ChainAccess`, `TransactionSubmitter`, `KeySigner` (`@product-lab/ports/chain`) |
+| Depends on | `@product-lab/ports`, `@product-lab/domain` (`LoopbackUrl`, `RequirementCheck`), `AppRequirements`, `ForkSnapshot`, `appUrl` in tests), `bulletin-deploy` 0.21.0 (optional peer; a development dependency here), `@noble/hashes` 1.8.0, `@polkadot-labs/hdkd-helpers` 0.0.34 (the development phrase). No other adapter, no polkadot-api |
+| Used by | the composition root (`composition/src/chain-connections.ts`: the `ChainConnector` type; `composition/src/gateway-program.ts`: `runGateway`; `composition/src/deployed-local-app.ts`: the default session's `deployed-local` launch through `DeployedLocalLauncher`, backlog 200), `examples/notes` (`deployed-local`; `deployed`, through the composition root), `examples/counter-contract` (`platformIntegration`, `PEOPLE_SIGNING`, `selectorOf`), `tools/verify` (`live/deploy/`), `tools/spikes/browser` (dot.li's content) |
+| May be used by | examples, tools, spikes and `composition/`; never `scope:core`; another adapter takes its ports instead (dot.li takes a `ContentArchiver`) |
+
+Left as they were (recorded in the step 8 record): the statement topic watch is its own WebSocket
+subscription (subscriptions have no port yet); `loadBulletinDeploy` sets `BULLETIN_DEPLOY_TELEMETRY` and
+`BULLETIN_DEPLOY_UPDATE_CHECK` in `process.env` for the duration of the load only, because
+`bulletin-deploy` reads telemetry when its module loads; `verifyServedApp` fetches over HTTP directly; the build directory, the dumped CAR and the log
+are read with `node:fs`.
+
+The pin moved from 0.19.3 to 0.21.0 on 1 October 2026. The adapter's code did not change: the CLI flags, environment
+variables, telemetry and update-check switches, environment-file merge, default environment (`paseo-next-v2`, TLD
+`paseo`), mnemonic precedence and the library calls `DotnsRegistrar` makes are the same. Upstream changes that only a
+live deploy can confirm: a lower DotNS register storage-deposit floor (5 PAS instead of 200 PAS), the product config
+refusing unknown top-level fields and a `domain` that differs from the deploy target, duplicate files packed once in
+the CAR, Bulletin re-authorizing when an unexpired allowance is used up, and DotNS commitments saved under the user's
+state directory so a later run can resume them.
+
+## Installing bulletin-deploy in a product
+
+`bulletin-deploy` 0.21.0 is an optional peer: a product that deploys to Bulletin installs it
+(`npm install --save-dev bulletin-deploy@0.21.0`). It does not load next to this package as npm installs it. Its
+`@parity/product-sdk-terminal` 0.10.1 pins `@novasamatech/host-papp` 0.10.0, which declares polkadot-api `>=2` but
+imports `polkadot-api/signer`, a path that only polkadot-api 2 exports. npm dedupes host-papp onto the product's
+polkadot-api 3.2.1 (this package's), so both the library and the CLI fail with `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+The lab's own workspace pins the two packages to 2.2.2 in its root `overrides`, which npm never applies for a
+dependency's consumers. A product adds the same overrides to its own `package.json` and installs again:
+
+```json
+"overrides": {
+  "@novasamatech/host-papp": { "polkadot-api": "2.2.2" },
+  "@novasamatech/statement-store": { "polkadot-api": "2.2.2" }
+}
+```
+
+Without them `bulletinDeployTool` (the deployer) and `loadBulletinDeploy` refuse before anything runs and name these
+overrides. They refuse only for a host-papp below 0.10.1: later ones need polkadot-api 3 and import no `./signer`, so a
+product-sdk-terminal that reaches one loads without the overrides. Tests: `tests/bulletin-deploy-tool.test.ts` (npm's layout refused; with the overrides' nested polkadot-api
+2.2.2 found; host-papp 0.10.1 and 0.12.0 on polkadot-api 3 found). With the overrides, npm resolves `@parity/product-sdk-keys` 0.4.3 for bulletin-deploy (the lab pins
+0.4.1), and the library and the CLI load. Tested versions, 27 October 2026, in a clean npm consumer of the release
+pack: bulletin-deploy 0.21.0, product-sdk-keys 0.4.3, product-sdk-terminal 0.10.1, host-papp 0.10.0 and
+statement-store 0.10.0 on polkadot-api 2.2.2. No deploy ran on that graph.
+bulletin-deploy 0.22.0 and 0.23.0 have the
+same dependencies.
+
+## Tests
+
+`bunx nx run deploy-bulletin:test` (no chain): content addressing and the reader, DotNS
+resolution against a fake resolver storage, the environment file, freshness, loading `bulletin-deploy`
+with `process.env` restored (also when the load or the registration fails), the optional peer at its pinned version
+and, from a directory where it is genuinely not installed, `BulletinDeployMissingError` from both entry points, the gateway and its
+program, launch modes, the platform actions on fake chain ports (the integration loads into an `IntegrationRegistry` without errors; contract sentences with a feature step's values; a wrong expected number fails naming the observed one), and `BulletinDeployer` end to end
+with a stand-in `bulletin-deploy` behind the `ProcessRunner` port. Negative controls: a name that
+resolves to other bytes, other content or none; one changed build byte, a divergent name, an extra stored file, missing Bulletin data, an altered stored block, and a manifest config that must upload; a failing tool; a public connection; a public
+endpoint; altered blocks; a runtime reporting another CID; a destination source answering for
+another CID or without a page; a public bridge script. `tests/destinations.test.ts` packs a site,
+reads it back through the reader and serves it as a destination.
+
+The workspace constrains legacy host-papp and statement-store to PAPI 2.2.2, whose signer APIs they import.
+Bulletin 0.21.0's direct SDK keys dependency is pinned to its declared compatible 0.4.1 release;
+newer 0.4.x keys would retain SDK host 0.24.0. These are workspace compatibility constraints,
+not upstream code patches. Real module loading and indirect API controls (forcing a PAPI 3 resolver for the legacy imports) were run for the SDK restart.
+
+The constraints are not qualified by a live deployment. The old host-api-wrapper is absent from the new lock;
+its former import failure is removed with the SDK 0.28 upgrade. No dead wrapper override is retained.

package/adapters/deploy/bulletin/src/bulletin-deployer.d.ts

@@ -0,0 +1,82 @@
+import type { Deployer, Deployment, DeployRequest, RetrievedContent, RetrieveTarget } from "@parity/product-lab/ports/deploy";
+import type { Clock, ConnectionMonitor, ConnectionReport, EnvironmentVariables, FileSystem, JsonRpcClient, ProcessRunner } from "@parity/product-lab/ports/system";
+import { BulletinContentReader } from "./content/bulletin-content-reader.js";
+import { type DotnsResolution } from "./dotns/dotns-resolver.js";
+import { type PlatformEndpoints } from "./endpoints.js";
+import { type BulletinDeployTool } from "./tool/bulletin-deploy-tool.js";
+import { type EnvironmentFileOptions } from "./tool/environment-file.js";
+/** A development signer: the well-known development phrase with a derivation path. Local environments only. */
+export interface DevelopmentSigner {
+    /** For example `//Alice`. */
+    derivationPath: string;
+}
+export interface BulletinDeployerDependencies {
+    processes: ProcessRunner;
+    files: FileSystem;
+    clock: Clock;
+    /** The deploy process inherits these, minus bulletin-deploy's own endpoint, signer and telemetry variables. */
+    environment: EnvironmentVariables;
+    /** DotNS storage reads on the Asset Hub. */
+    rpc: JsonRpcClient;
+    /** `bitswap_v1_get` on the Bulletin node (default `rpc`). */
+    contentRpc?: JsonRpcClient;
+    connections: ConnectionMonitor;
+}
+export interface BulletinDeployerOptions {
+    /** TLD of the environment (paseo-next-v2: `paseo`). */
+    tld?: string;
+    signer?: DevelopmentSigner;
+    environmentFile?: EnvironmentFileOptions;
+    /** Extra environment for bulletin-deploy (never a signer). */
+    env?: Record<string, string>;
+    /** Fail when the deploy process contacts a non-loopback address (default true). */
+    requireNoPublicConnections?: boolean;
+    /** Default 15 minutes. A deploy still running then is stopped and fails as timed out; a stop that fails rejects with its reason. */
+    timeoutMs?: number;
+    /** The deploy tool; default the pinned package. */
+    tool?: BulletinDeployTool;
+}
+/** A deployment by bulletin-deploy, as recorded in `<runDir>/deployed-app.json`. */
+export interface BulletinDeployment extends Deployment {
+    kind: "product-lab-deployed-app";
+    /** `already-deployed` means no tool process or transaction was started for this request. */
+    status: "uploaded" | "already-deployed";
+    resolution: DotnsResolution;
+    /** The CAR archive the contenthash points at (bulletin-deploy's layout), with its inner root and digest. */
+    container?: {
+        kind: "car";
+        root: string;
+        bytes: number;
+        sha256: string;
+        matchesUpload: boolean;
+    };
+    tool: {
+        name: "bulletin-deploy";
+        version: string;
+        bin: string;
+    };
+    signer: {
+        derivationPath: string;
+    };
+    environmentFile: string;
+    /** Process log, present only when the deployment tool ran. */
+    log?: string;
+    connections: ConnectionReport;
+    endpoints: PlatformEndpoints;
+}
+export declare class BulletinDeployer implements Deployer<BulletinDeployment> {
+    readonly endpoints: PlatformEndpoints;
+    private readonly deps;
+    private readonly options;
+    private readonly resolver;
+    private readonly reader;
+    private readonly tld;
+    constructor(endpoints: PlatformEndpoints, deps: BulletinDeployerDependencies, options?: BulletinDeployerOptions);
+    /** The content reader over this environment's Bulletin (also a ContentArchiver for dot.li). */
+    get content(): BulletinContentReader;
+    resolve(name: string): Promise<DotnsResolution>;
+    retrieve(target: RetrieveTarget): Promise<RetrievedContent>;
+    deploy(request: DeployRequest): Promise<BulletinDeployment>;
+    /** Return a verified existing deployment only for an exact file set at the resolved name. */
+    private existingDeployment;
+}

package/adapters/deploy/bulletin/src/bulletin-deployer.js

@@ -0,0 +1,234 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEV_PHRASE } from "@polkadot-labs/hdkd-helpers";
+import { sha256Hex } from "./bytes.js";
+import { isContentMissing } from "./errors.js";
+import { BulletinContentReader } from "./content/bulletin-content-reader.js";
+import { DeploymentCheck, readBuild } from "./deployment-check.js";
+import { DotnsResolver } from "./dotns/dotns-resolver.js";
+import { need, requireLoopback } from "./endpoints.js";
+import { bulletinDeployTool } from "./tool/bulletin-deploy-tool.js";
+import { assertLoopbackOnly, bulletinDeployEnvironmentFile } from "./tool/environment-file.js";
+const WITHHELD = /^(BULLETIN_|DOTNS_|MNEMONIC$|DEPLOY_|SENTRY_)/;
+const PROCESS_ID = "bulletin-deploy";
+export class BulletinDeployer {
+    endpoints;
+    deps;
+    options;
+    resolver;
+    reader;
+    tld;
+    constructor(endpoints, deps, options = {}) {
+        this.endpoints = endpoints;
+        this.deps = deps;
+        this.options = options;
+        requireLoopback(endpoints, ["people", "assetHub", "bulletin", "relay", "identityBackend"]);
+        this.tld = options.tld ?? "paseo";
+        this.resolver = new DotnsResolver(need(endpoints, "assetHub"), deps.rpc);
+        this.reader = new BulletinContentReader(need(endpoints, "bulletin"), deps.contentRpc ?? deps.rpc);
+    }
+    get content() {
+        return this.reader;
+    }
+    resolve(name) {
+        return this.resolver.resolve(name);
+    }
+    async retrieve(target) {
+        if ("cid" in target)
+            return this.reader.retrieve(target.cid);
+        const resolution = await this.resolve(target.name);
+        if (!resolution.cid)
+            throw new Error(`${target.name} has no IPFS contenthash on ${this.resolver.assetHub}`);
+        return { ...(await this.reader.retrieve(resolution.cid)), resolution };
+    }
+    async deploy(request) {
+        const { files, clock } = this.deps;
+        if (!/^[a-z0-9-]+$/.test(request.label))
+            throw new Error(`"${request.label}" is not a bare DotNS label`);
+        if (!files.exists(join(request.buildDir, "index.html")))
+            throw new Error(`${request.buildDir} has no index.html; build the app first`);
+        const signer = this.options.signer ?? { derivationPath: "//Alice" };
+        if (!/^(\/\/?[A-Za-z0-9_-]+)+$/.test(signer.derivationPath))
+            throw new Error(`Invalid derivation path ${signer.derivationPath}`);
+        files.makeDirectory(request.runDir);
+        const environmentFile = join(request.runDir, "bulletin-deploy-environment.json");
+        files.writePrivateJson(environmentFile, bulletinDeployEnvironmentFile(this.endpoints, this.options.environmentFile));
+        assertLoopbackOnly(files.readJson(environmentFile));
+        const tool = this.options.tool ?? bulletinDeployTool(files);
+        const name = `${request.label}.${this.tld}`;
+        if (!request.manifestConfig) {
+            const verifyStarted = clock.now();
+            const existing = await this.existingDeployment(name, readBuild(request.buildDir), request.signal);
+            if (existing) {
+                files.remove(join(request.runDir, "bulletin-deploy.command.json"));
+                files.remove(join(request.runDir, "deploy.car"));
+                files.remove(join(request.runDir, `${PROCESS_ID}.log`));
+                const at = clock.date().toISOString();
+                const connections = { samples: 0, processes: {}, remotes: [], nonLoopback: [], startedAt: at, stoppedAt: at };
+                files.writePrivateJson(join(request.runDir, "bulletin-deploy.connections.json"), connections);
+                const record = {
+                    kind: "product-lab-deployed-app",
+                    status: "already-deployed",
+                    name,
+                    label: request.label,
+                    cid: existing.resolution.cid,
+                    contenthash: existing.resolution.contenthash,
+                    resolution: existing.resolution,
+                    files: existing.files,
+                    extraFiles: [],
+                    tool: { name: "bulletin-deploy", version: tool.version, bin: tool.bin },
+                    signer: { derivationPath: signer.derivationPath },
+                    environmentFile,
+                    connections,
+                    endpoints: this.endpoints,
+                    timings: { deployMs: 0, verifyMs: Math.round(clock.now() - verifyStarted) },
+                };
+                files.writePrivateJson(join(request.runDir, "deployed-app.json"), record);
+                return record;
+            }
+        }
+        const dumped = join(request.runDir, "deploy.car");
+        const args = [
+            request.buildDir,
+            request.manifestConfig ? name : request.label,
+            "--js-merkle",
+            "--derivation-path",
+            signer.derivationPath,
+            `--dump-car=${dumped}`,
+            ...(request.manifestConfig ? ["--config", request.manifestConfig] : ["--no-manifest"]),
+        ];
+        const withheld = Object.fromEntries(Object.keys(this.deps.environment.all()).filter((key) => WITHHELD.test(key)).map((key) => [key, undefined]));
+        const recorded = {
+            BULLETIN_DEPLOY_ENV_FILE: environmentFile,
+            BULLETIN_DEPLOY_TELEMETRY: "off",
+            BULLETIN_DEPLOY_UPDATE_CHECK: "0",
+            DEPLOY_DOMAIN: name,
+            PRODUCT_LAB_BUILD_DIR: request.buildDir,
+        };
+        files.writePrivateJson(join(request.runDir, "bulletin-deploy.command.json"), {
+            bin: tool.bin,
+            version: tool.version,
+            args,
+            env: { ...recorded, MNEMONIC: "<development phrase>" },
+        });
+        const started = clock.now();
+        const owned = this.deps.processes.open(request.runDir);
+        const log = owned.logFile(PROCESS_ID);
+        let code;
+        let connections;
+        try {
+            const child = await owned.start(PROCESS_ID, {
+                command: tool.bin,
+                args,
+                env: { ...withheld, ...this.options.env, ...recorded, MNEMONIC: DEV_PHRASE },
+            });
+            const watch = this.deps.connections.watch(() => [child.pid]);
+            const timeoutMs = this.options.timeoutMs ?? 15 * 60_000;
+            let timedOut = false;
+            let stopFailed = () => undefined;
+            const unstoppable = new Promise((_resolve, reject) => (stopFailed = reject));
+            const stop = () => void child.stop().catch((error) => stopFailed(new Error(`bulletin-deploy could not be stopped: ${error instanceof Error ? error.message : String(error)}; see ${log}`, { cause: error })));
+            request.signal?.addEventListener("abort", stop, { once: true });
+            const deadline = new AbortController();
+            void clock.sleep(timeoutMs, deadline.signal).then(() => {
+                timedOut = true;
+                stop();
+            }, 
+            () => undefined);
+            const ended = await Promise.race([child.exited, unstoppable]).then((exitCode) => ({ exitCode }), (error) => ({ error }));
+            deadline.abort();
+            request.signal?.removeEventListener("abort", stop);
+            connections = await watch.stop();
+            if ("error" in ended)
+                throw ended.error;
+            if (timedOut)
+                throw new Error(`bulletin-deploy did not finish within ${timeoutMs} ms and was stopped; see ${log}`);
+            code = ended.exitCode;
+        }
+        finally {
+            owned.close();
+            redactLog(log);
+        }
+        const deployMs = Math.round(clock.now() - started);
+        files.writePrivateJson(join(request.runDir, "bulletin-deploy.connections.json"), connections);
+        request.signal?.throwIfAborted();
+        if (code !== 0)
+            throw new Error(`bulletin-deploy exited with ${code}; see ${log}`);
+        if ((this.options.requireNoPublicConnections ?? true) && connections.nonLoopback.length)
+            throw new Error(`bulletin-deploy contacted non-loopback addresses: ${connections.nonLoopback.map((item) => `${item.command} ${item.remote}`).join(", ")}`);
+        const verifyStarted = clock.now();
+        const checked = await new DeploymentCheck(this).check(name, readBuild(request.buildDir), request.signal ? { signal: request.signal } : {});
+        const { content } = checked;
+        const resolution = checked.resolution;
+        const uploaded = existsSync(dumped) ? sha256Hex(readFileSync(dumped)) : undefined;
+        if (content.container && uploaded && content.container.sha256 !== uploaded)
+            throw new Error(`The CAR retrieved for ${name} (${content.container.sha256}) is not the one bulletin-deploy uploaded (${uploaded})`);
+        let manifest;
+        if (resolution.records.manifest) {
+            try {
+                manifest = JSON.parse(resolution.records.manifest);
+            }
+            catch (error) {
+                throw new Error(`${name} has a manifest record that is not JSON`, { cause: error });
+            }
+        }
+        const record = {
+            kind: "product-lab-deployed-app",
+            status: "uploaded",
+            name,
+            label: request.label,
+            cid: resolution.cid,
+            contenthash: resolution.contenthash,
+            resolution,
+            ...(manifest ? { manifest } : {}),
+            ...(content.container ? { container: { ...content.container, matchesUpload: content.container.sha256 === uploaded } } : {}),
+            files: checked.files,
+            extraFiles: checked.extraFiles,
+            tool: { name: "bulletin-deploy", version: tool.version, bin: tool.bin },
+            signer: { derivationPath: signer.derivationPath },
+            environmentFile,
+            log,
+            connections,
+            timings: { deployMs, verifyMs: Math.round(clock.now() - verifyStarted) },
+            endpoints: this.endpoints,
+        };
+        files.writePrivateJson(join(request.runDir, "deployed-app.json"), record);
+        return record;
+    }
+    async existingDeployment(name, build, signal) {
+        signal?.throwIfAborted();
+        const resolution = await this.resolve(name);
+        if (!resolution.cid || !resolution.contenthash || resolution.records.manifest)
+            return null;
+        let content;
+        try {
+            content = await this.retrieve({ cid: resolution.cid });
+        }
+        catch (error) {
+            if (isContentMissing(error))
+                return null;
+            throw error;
+        }
+        signal?.throwIfAborted();
+        if (content.cid !== resolution.cid || !content.container || content.files.size !== build.size)
+            return null;
+        for (const [path, bytes] of build) {
+            const stored = content.files.get(path);
+            if (!stored || Buffer.compare(stored, bytes) !== 0)
+                return null;
+        }
+        return {
+            resolution: resolution,
+            files: Object.fromEntries([...content.files].map(([path, bytes]) => [path, { bytes: bytes.length, sha256: sha256Hex(bytes) }])),
+        };
+    }
+}
+function redactLog(file) {
+    if (!existsSync(file))
+        return;
+    const text = readFileSync(file, "utf8");
+    if (text.includes(DEV_PHRASE))
+        writeFileSync(file, text.split(DEV_PHRASE).join("<development phrase>"), { mode: 0o600 });
+}

package/adapters/deploy/bulletin/src/bytes.d.ts

@@ -0,0 +1,6 @@
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function concatBytes(...parts: readonly Uint8Array[]): Uint8Array;
+export declare function equalBytes(a: Uint8Array, b: Uint8Array): boolean;
+/** sha256 of `bytes`, lowercase hex without a prefix (the digests deployment records carry). */
+export declare const sha256Hex: (bytes: Uint8Array) => string;

package/adapters/deploy/bulletin/src/bytes.js

@@ -0,0 +1,25 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from "node:crypto";
+export function hexToBytes(hex) {
+    const clean = hex.replace(/^0x/, "");
+    if (clean.length % 2)
+        throw new Error("Odd hexadecimal length");
+    return Uint8Array.from(Buffer.from(clean, "hex"));
+}
+export function bytesToHex(bytes) {
+    return `0x${Buffer.from(bytes).toString("hex")}`;
+}
+export function concatBytes(...parts) {
+    const out = new Uint8Array(parts.reduce((sum, part) => sum + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+export function equalBytes(a, b) {
+    return a.length === b.length && a.every((byte, index) => byte === b[index]);
+}
+export const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");

package/adapters/deploy/bulletin/src/content/bulletin-content-reader.d.ts

@@ -0,0 +1,35 @@
+import type { BulletinReader } from "@parity/product-lab/ports/chain";
+import type { ContentArchive, ContentArchiver, RetrievedContent } from "@parity/product-lab/ports/deploy";
+import type { JsonRpcClient } from "@parity/product-lab/ports/system";
+import { type BlockSource } from "./cid.js";
+export interface BulletinContentReaderOptions {
+    /** Per block request. Default 60 s. */
+    readonly timeoutMs?: number;
+}
+export declare class BulletinContentReader implements ContentArchiver, BulletinReader {
+    /** The Bulletin node's RPC endpoint (`ws://…`). */
+    readonly bulletin: string;
+    private readonly rpc;
+    private readonly options;
+    constructor(
+    /** The Bulletin node's RPC endpoint (`ws://…`). */
+    bulletin: string, rpc: JsonRpcClient, options?: BulletinContentReaderOptions);
+    /** Blocks as the node returns them, unverified (wrap in `verifiedSource`). */
+    readonly source: BlockSource;
+    /** One stored blob by CID, verified (what `TransactionStorage.store` stored). */
+    blob(cidText: string): Promise<Uint8Array>;
+    /**
+     * Backlog 91: the bytes stored under `cid`, verified: a raw block as `TransactionStorage.store` addresses it, else a
+     * UnixFS file. A directory is refused (it holds several files).
+     */
+    bytes(cid: string): Promise<Uint8Array>;
+    /** Backlog 160: the node's finalized head (`chain_getFinalizedHead`, then its header's number). */
+    finalizedHead(): Promise<{
+        number: number;
+        hash: string;
+    }>;
+    /** Every file under `cid`, verified; a CAR stored as one file (bulletin-deploy's layout) is unpacked and its inner DAG verified too. */
+    retrieve(cid: string): Promise<RetrievedContent>;
+    archive(cid: string): Promise<ContentArchive>;
+    reverify(cid: string, car: Uint8Array): Promise<ContentArchive>;
+}

package/adapters/deploy/bulletin/src/content/bulletin-content-reader.js

@@ -0,0 +1,58 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { hexToBytes } from "../bytes.js";
+import { buildCar, carBlockSource } from "./car.js";
+import { parseCid, RAW, verifyBlock } from "./cid.js";
+import { retrieveContent } from "./retrieve-content.js";
+export class BulletinContentReader {
+    bulletin;
+    rpc;
+    options;
+    constructor(
+    bulletin, rpc, options = {}) {
+        this.bulletin = bulletin;
+        this.rpc = rpc;
+        this.options = options;
+    }
+    source = async (cid) => {
+        const result = await this.rpc.request(this.bulletin, "bitswap_v1_get", [cid.text], { timeoutMs: this.options.timeoutMs ?? 60_000 });
+        if (typeof result !== "string")
+            throw new Error(`bitswap_v1_get ${cid.text} returned no data`);
+        return hexToBytes(result);
+    };
+    async blob(cidText) {
+        const cid = parseCid(cidText);
+        const block = await this.source(cid);
+        if (!verifyBlock(cid, block))
+            throw new Error(`${cidText} uses a hash function this reader cannot verify`);
+        return block;
+    }
+    async bytes(cid) {
+        if (parseCid(cid).codec === RAW)
+            return this.blob(cid);
+        const { files } = await this.retrieve(cid);
+        const single = files.size === 1 ? files.get("") : undefined;
+        if (!single)
+            throw new Error(`${cid} holds ${files.size} files (${[...files.keys()].slice(0, 3).join(", ")}…), not one`);
+        return single;
+    }
+    async finalizedHead() {
+        const timeoutMs = this.options.timeoutMs ?? 60_000;
+        const hash = await this.rpc.request(this.bulletin, "chain_getFinalizedHead", [], { timeoutMs });
+        if (typeof hash !== "string")
+            throw new Error("chain_getFinalizedHead returned no hash");
+        const header = await this.rpc.request(this.bulletin, "chain_getHeader", [hash], { timeoutMs });
+        if (typeof header?.number !== "string")
+            throw new Error(`chain_getHeader ${hash} returned no number`);
+        return { number: Number.parseInt(header.number, 16), hash };
+    }
+    retrieve(cid) {
+        return retrieveContent(cid, this.source);
+    }
+    archive(cid) {
+        return buildCar(parseCid(cid), this.source);
+    }
+    reverify(cid, car) {
+        return buildCar(parseCid(cid), carBlockSource(car).source);
+    }
+}

package/adapters/deploy/bulletin/src/content/car.d.ts

@@ -0,0 +1,27 @@
+/** CARv1 archives: header, packing a DAG, reading roots and blocks back. */
+import type { ContentArchive } from "@parity/product-lab/ports/deploy";
+import { type BlockSource, type Cid } from "./cid.js";
+/** CARv1 header: dag-cbor {roots: [CID], version: 1}. */
+export declare function carHeader(root: Cid): Uint8Array;
+/** Walk the DAG from `root` and pack every block into a CARv1 archive, checking each against its CID. */
+export declare function buildCar(root: Cid, source: BlockSource, limits?: {
+    maxBlocks: number;
+    maxBytes: number;
+}): Promise<ContentArchive>;
+/**
+ * Root CIDs from a CARv1 header (dag-cbor `{ roots: [CID...], version: 1 }`,
+ * CIDs as tag 42 byte strings with a leading 0x00). Minimal: definite-length
+ * items only, which is what CAR writers emit.
+ */
+export declare function carRoots(car: Uint8Array): Cid[];
+/** True when `bytes` starts like a CARv1 archive (header varint, then a dag-cbor map with `roots`). */
+export declare function looksLikeCar(bytes: Uint8Array): boolean;
+/**
+ * Parse a CARv1 archive into a block map and return a BlockSource over it. The
+ * header's roots are not trusted: callers re-walk from the CID they want and
+ * verify every block.
+ */
+export declare function carBlockSource(car: Uint8Array): {
+    source: BlockSource;
+    blocks: number;
+};