refactor(polkavm): isolate optional host composition

[replghost]

Current repair qualification — 2026-10-02

• Current source: a572456b90dc6932476f2fb5a71985fbe9fcbd84. Canonical base artifact-generation and Wasm revisions are this same commit. Prior main-integration baselines are retained: native bda6ac518c8cc59319491b12e4e23b96777375fd, frontend f4012c50c3400d1186c332ad2ae50298cefd153d.
• Consumers: dotli #238 at 0a24db4aa189adad7b93f9ff508c7949e39196ee; dotli #185 at abca1e079e90781a97fa9492331ddb7ad669d2b7. Complete matching SDK/host packages remain 0.23.0; codegen and Wasm were rebuilt canonically. Generated client bytes are unchanged. Production features: wasm-signing-host; separate testing bundle: wasm-signing-host,test-host.

Canonical artifact	SHA-256
Client npm archive	3c060958d3bd519c7c8f5f706115fbb2108be640b2fa8777d50969e3851ef442
Client dist/generated/client.js	7ab13b5840a03360f9687d11b14090b5e8685dda6cea22bcee2fd14b91065973
Host npm archive	79a96ac9f24de2dae05e5e799a7b58d8d9c8f6289fbf31a17bf582331f245360
Browser signing Wasm	7f794f459e52e50065b1e3a2371e4b5d6330b19185547ee582ee6a565058d754
Local QA CLI	4823ce5910aae52c52f4e0e78436f28b62e4c22465fcb110cd5e64ebb4952cdf

Native correction and causal limits

Bulletin mortal signatures now anchor to a finalized checkpoint, while nonce/runtime state comes from the freshest available signing snapshot. A checkpoint at least 64 blocks behind is rejected before broadcast. Regression coverage verifies the actual signature with a newer nonce and older finalized checkpoint, and the expiry boundary. Existing transaction retries/deadlines are unchanged; no chain error is suppressed. The affected test fixture uses parking_lot::Mutex.

The former Seity Extrinsic marked as invalid run used noncanonical best-block anchors, but retained evidence lacks the signed bytes and typed pool reason. Fork-sensitive mortality was a real correctness hazard; it is not claimed as the conclusively proved cause of that historical failure. Prior hosted Factory/Genesis timeout causes also remain unproved. No broker/readiness workaround, prewarming, extra retry, or timeout increase was added.

Executed verification

• Exact-head native CI: success, 25 successful jobs, 1 skipped (E2E (playground inside dotli)); job totals include control jobs. This is the CI workflow result, not an assertion that every advisory PR check or release credential is green.
• Each of the five native variants passed 21 Bulletin RPC regression tests, all-target Clippy with -D warnings, CLI build, and canonical browser/testing Wasm packaging. Base full library: 1,246 passed.
• All six frontend consumers passed configured build, typecheck and lint. The later frontend-only formatting correction passed targeted Prettier checks; it did not change runtime source or canonical native artifacts.

Local original sequence	Tested frontend head	Result, retries=0	Genesis after navigation	Factory	Submit
#238	0a24db4aa189adad7b93f9ff508c7949e39196ee	42 passed, 20 skipped; no failed/flaky cases	1107ms	9625ms	6057ms
#255	301a235ba13248ef4281e9e3d859919fb6cfbe06	42 passed, 20 skipped; no failed/flaky cases	1045ms	11023ms	13548ms
#287	d3dc8a41807c36b8bcdf001c47eccb9735305499	42 passed, 20 skipped; no failed/flaky cases	1029ms	6496ms	5530ms

The Chat/Seity tested heads above precede documentation-only formatting merges; their native/Wasm pins and runtime code are unchanged. Final hosted frontend results are recorded on the linked consumer PRs, separately from these exact-head local results.

Final hosted retest: failures remain

Frontend PR	Tests workflow	Functional	E2E
#238	success	79 passed	42 passed, 20 skipped
#185	success	89 passed, 3 skipped	41 passed, 1 flaky, 20 skipped
#255	success	89 passed, 3 skipped	42 passed, 20 skipped
#287	failure	85 passed, 4 failed, 3 skipped	42 passed, 20 skipped
#290	success	87 passed, 2 failed, 3 skipped	42 passed, 20 skipped
#291	failure	86 passed, 5 failed, 3 skipped	41 passed, 1 flaky, 20 skipped

• PVM and JAM Genesis Hash still flaked after navigation: the product stayed pending for the helper's existing 20 seconds; the existing CI retry passed. The helper reports this timeout as error; it is not evidence of a chain rejection. Retained traces include People-chain/local development sockets but do not expose the Asset Hub gateway WebSocket exchange, so these new failures do not establish an upstream or broker cause.
• Peer: two navigation product-render timeouts at 45 seconds. The existing threshold tolerates these, so its green workflow is not a clean functional suite.
• Seity: cache-off RPC-gateway resolution timed out; two navigation renders timed out; another navigation case reported failure to connect to trusted provider paseo-bulletin-next-ipfs.polkadot.io. The zero-failure host-settings gate correctly failed.
• JAM: cache-on reload and two navigation cases reported that same provider connection error; two more navigation cases timed out. The zero-failure host-settings gate correctly failed. These logs do not establish whether the underlying cause was provider availability, runner networking, CORS, or another transport failure.
• All six final Static Analysis and hosted cold-start Performance workflows passed; all five native CI workflows passed. That does not clear the red functional gates, Genesis flakes, or Doom matrix. No additional CI rerun, timeout/retry increase, threshold relaxation, or speculative transport patch was made.

Doom: criterion corrected, backend matrix still unqualified

The user explicitly approved 35 FPS sustained over 30 seconds, with one frame of sampling-boundary tolerance: frames + 1 >= elapsedMs * 35 / 1000. This replaces the instantaneous FPS >= 35 sample; it is an acceptance-criterion change, not a runtime speedup. Runtime and displayed FPS are unchanged; raw samples are not rounded to force a pass. Update p95 <28.6ms, cold/warm first-frame limits <3,000/<1,000ms, audio and translation-cache checks remain. The revised official RPC benchmark passed once before the vendor replacement.

The later isolated matrix used the rebuilt base pair at frontend 238ab5fa739788b2eb948ba1f807a1876edbacad, with fresh owned Chrome profiles and no concurrent builds/E2E:

Backend	Observed result	Qualification
smoldot-direct	1,050 frames / 30,001.1ms; p95 17.7ms; cold/warm 202.9/152.8ms; audio/cache passed	PASS under the approved criterion
smoldot-shared-worker	1,038 frames / 30,001.4ms = 34.5983854 FPS; p95 17ms; cold/warm 186.4/158.4ms; other checks passed	FAIL: cadence deficit retained
rpc-gateway	Warm-readiness helper timed out. Its null snapshot conflated missing frame, missing canvas and evaluation errors, and earlier cold/cadence values were not retained by that helper	NOT QUALIFIED; iframe disappearance is not established

Distinct diagnostics found no presentation loss in a later instrumented 24-second shared-worker sample and observed a successful hidden RPC new-document reload. Neither diagnostic supersedes the failures or qualifies performance. No evidence-proved runtime fix, guest rebuild, speculative tuning, or further unchanged gate rerun was made. The original strict RPC failure and every new failure remain retained. Next causal capture must instrument the original early 30-second window and distinguish warm lifecycle states before proposing a runtime fix.

Retention and rollout boundary

Local verification used paseo-next-v2, the pinned host-playground fixture f56294cea4430163bf16ec068844b1327441073c, and existing private QA identities. All three corrected sequences paired on their first existing setup attempt. A prior local launch failure and a misconfigured Previewnet-product run (34 passed, 20 skipped, 8 Chain/Contract failures) are retained separately, not presented as reproductions of the hosted Genesis timeout. Private traces/auth/signers were not published.

The first repair heads also exposed a README formatting failure (corrected by documentation-only commits) and a PVM cache-unit-test 5,000ms timeout. No cache runtime/test change, limit increase, or causal claim was made for that isolated timeout. Older in-flight runs superseded by the formatting correction remain recorded as cancelled, not passed.

No PR merge, force push, deployment, environment approval, SDK/npm/product/guest publication, or rollback was performed by this repair. JAM remains JAM-TEST-INSTANCE, never JAM-PUBLIC-DEVNET. The user-owned deploy: paseo.fyi label is retained; repair-triggered deployment runs 36970790399 and 36971286469 were cancelled before deployment. The earlier rollout audit is retained below: an older workflow deployed 56cea5d37577bf82684fb5c6b6e4ba81d2142938; this record does not claim live remained unchanged historically.

Historical integration qualification (superseded; retained verbatim)

Current main refresh and qualification — 2026-10-01

• Current source: e0a8d59a07e72c4c7f36e6bab6c1db34c06d35dc. Native main bda6ac518c8cc59319491b12e4e23b96777375fd is integrated; the frontend stack includes dotli main f4012c50c3400d1186c332ad2ae50298cefd153d (merged chore(deps): bump postcss from 8.5.15 to 8.5.23 in /explorer #313). Histories and worktrees were preserved; pushes used fetched-head ancestry guards, never force.
• Canonical base artifact-generation revision: 9dcf66544e02b3bb3994e05f3a1400738f742331. Later native changes are test/docs/iOS-only, not SDK/Wasm inputs, so the artifact pin intentionally differs from the current head. Complete matching client and host packages remain 0.23.0, generated rather than hand-edited. Browser signing Wasm uses web-wasm-signing-host without test-host; testing Wasm is separate.
• Browser consumers: dotli #238 at 70845db96bdd21409310daeff5e471b74ab5a1c9; dotli #185 at 351e5d73fab803a0fd2a4007ce2d2557aebaff05.

Canonical artifact	SHA-256
Client npm archive	3c060958d3bd519c7c8f5f706115fbb2108be640b2fa8777d50969e3851ef442
Client dist/generated/client.js (not dist/index.js)	7ab13b5840a03360f9687d11b14090b5e8685dda6cea22bcee2fd14b91065973
Host npm archive	7b4042f8d659e0f39d9eeeddf75963c0a8826578295634a92d37f17ff35f5bdd
Browser signing Wasm	2de619b24ed76f302801290c12574bff53e27546294b19e719d1fd0285d4d834

Qualification

• Frontend #238 exact-head Tests: functional 79 passed; E2E 41 passed, 1 flaky, 20 skipped. Hosted E2E retained one flaky Preimage → Factory case: it failed on the first attempt and passed the existing CI retry. No retry setting was changed.

• Frontend #185 exact-head Tests: functional 89 passed, 3 skipped; E2E 42 passed, 20 skipped. No flaky case in this final hosted Tests run.

• Current-head Core CI: 24 required jobs green — 22 passed, 2 path-filter skips. This includes core Swift/Android coverage, not a claim that full iOS application CI ran at this head. The separate existing release-signing-credentials advisory failure remains distinct from Core CI.

• Local: Rust workspace: 1,834 passed across 27 suites, 21 ignored. Client/host SDK: 280/285 passed. Canonical codegen and complete feature-specific package construction were qualified locally.

• Browser/native proof: Actual browser/native terminal recovery passed: one original CoreWorker/client/transport and native connection remained open; an uncaught shared-worker error retired the worker, stopped the old follow, and a later real chain query succeeded through a new worker generation in 8,147ms. A new follow on the same client delivered 76 live NewBlock events. The old follow did not continue. Same-partition second-tab sharing was verified before and after replacement. Evidence: main-refresh-terminal-verified-pvm.json and screenshot.

Retained cross-stack limits

• The isolated strict Doom matrix is not fully green: RPC measured 34.54231433545555 FPS against ≥35 FPS. Direct smoldot measured 35.06721215581914 and shared-worker smoldot 35.48895899032775. All three passed p95/cold/warm/cache/audio criteria; warm runs used a new document and zero translation. No threshold, clock, timeout, or retry policy was weakened.
• Latest local Seity E2E attempt: 41 passed, 20 existing skips, 1 Submit failure (Extrinsic marked as invalid). Two existing native broadcast attempts were validated then invalidated; none was found included in the inspected canonical range. [INFERENCE] Noncanonical mortality anchors may explain invalidation; the exact cause is not established and signed extrinsic bytes were not retained. The earlier Factory deadline failure is also retained: inclusion took 47,516ms against the unchanged 30s product deadline. A separate unchanged manual Factory attempt passed in 10.918s. These failures are not erased by other passing checks.
• Evidence JSON/screenshots are retained beside the refresh worktrees; private browser profiles and throwaway harnesses were removed. No bearer references, keys, signing configuration, or .auth contents are included here.

This refresh authorizes no deployment, environment approval, PR merge, SDK/npm publication, or guest/product publication. Its QA writes were testnet-only.

All three refresh-triggered JAM Deploy runs were cancelled before rollout; final-head cancellation proof is for frontend dcdef40499119183aed82a39f784ef740d494341. No refreshed source head was deployed.

The live environment changed during qualification: older Deploy run 36945647296, attempt 3 was approved under GitHub account replghost, explicitly checked out baseline 56cea5d37577bf82684fb5c6b6e4ba81d2142938, and recorded deployment success at 2026-10-02 01:19:01 UTC. Its later published-product smoke failed. The operator/client/session behind that account is unproven; this qualification granted no approval and performed no rollback. The observed live content hash changed from 4a7caf047fb7f350c1833039b93ba634698a47c56f051b8c7fc0525d4c59a5c8 to 5882695ee20df5d24a6ed2feb9e997f176fe27ecf4eafe742fabb39eba92885f; these are content hashes, not Git SHAs, and their exact byte-level mapping to a source commit is unproven. Earlier revision/deployment records below remain historical evidence and do not override this current section.

Execution callback ownership

createProvider(product, callbacks) binds platform callbacks to one execution of a shared native host. Retired executions cannot route later callbacks through the core's default callback scope; wallet authentication and storage retain core ownership. Native contacts installed after core construction remain available unless the execution supplies its own contacts adapter.

Current head: a4c2dd7ab45c7ac15b1cf7522553e9cd825a10b9. Canonical codegen, default web/testing Wasm, signing-only browser Wasm, host SDK tests, and harness typing are qualified. Hosted CI is green, including Rust workspace, Wasm bridge, Android compilation and iOS Swift/WebKit checks. No package publication.

Earlier source and qualification (superseded)

Head 953519aa65f02412ae487ce2356d04ed56b5622d includes main aa6ae62ca038bf4a6356edae8eb78e595d52ce24 through history-preserving merge commits. Client and host package manifests remain 0.23.0 with pending Changesets.

Canonical pinned-nightly codegen, client/host TypeScript builds, CLI typecheck, release-version check, 280 client tests, 126 script tests, eight Rust Bulletin-lookup tests, and the no-default-features truapi/truapi-client build pass locally. The actual CLI fetched and verified an existing 66-byte Bulletin preimage through bitswap_v1_get. Release wallet WASM uses wasm-signing-host without test-host; the separately built testing bundle uses both features. The intended wallet-variant host suite passes 286 tests with Bun 1.4.2; the one default pairing-only negative export assertion is inapplicable to this explicit signing-host build and remains unchanged for default-build CI. Bun 1.3.14 caused six subprocess/server/packing failures; the same assertions pass under the CI-pinned Bun 1.4.2. Both npm packages remain 0.23.0, packed without publishing.

Current-head core CI passes, including Rust workspace, default WASM bridge, Android compile/unit checks, and iOS Swift + WebKit. Full local workspace/native qualification was interrupted by workstation disk exhaustion; the full current-head CI gate completes that qualification. Full iOS application CI also passes, including the in-tree core, application build, simulator preview, and tests. No PR was merged or approved, and no npm package was published. Deployment evidence below belongs to the explicitly named earlier revisions, not this source refresh.

Summary

Implements #507; tracked by #550.

• PolkaVM is optional. truapi-polkavm-host is an rlib-only composition crate exposing namespaced truapi and polkavm_host_runtime APIs. The base truapi has no PolkaVM dependency.
• The standalone runtime is pinned to version 0.3.0, source e60a6135be6e00c72c90ca4abe23d2002f4eb962.
• Browser/mobile PolkaVM distribution artifacts belong to the standalone runtime repository, not this core.
• The base Android ABI matrix includes armeabi-v7a.

Runtime and packaging boundaries

Protocol payloads build with no default features using no_std and alloc. host-api exposes async traits for codegen bootstrap; runtime includes the host implementation. Native and WASM packaging explicitly request shared/static outputs, so guest dependencies need no host allocator or panic symbols.

Published truapi_server artifact filenames are stable. The default web WASM bundle is pairing-only. A browser wallet selects --web-only --signing-host, without testing-only allocation shortcuts. Artifact tools use the Cargo-matched wasm-bindgen CLI and checksum-verified Binaryen 117. Each iOS static-library slice has its own Cargo invocation.

Earlier qualification evidence

Head 597e9251238fcf51131791698700564d016c1b7c includes main c5158448f3c4575f40350017d466053d6b19dacb. Core CI passed. Full iOS CI passed, including the real in-tree core, simulator preview, application build, and tests.

Local qualification includes the all-target/all-feature workspace check, 1,807 Rust tests, a compiled and instantiated no-std WASM guest performing codec round trips and rejecting trailing bytes, isolated no-default provider compilation, real pairing/testing WASM builds, host package tests, UniFFI generation, and the actual CLI help command. A throwaway native packaging probe produced both device and simulator static libraries and a two-slice XCFramework using the real build recipe and Xcode.

The playground bundles Instrument Serif, Geist, and JetBrains Mono with their upstream OFL notices, eliminating build-time Google Fonts CSS requests. Its production build passed with an unreachable HTTP/HTTPS proxy; Chromium loaded all four font faces locally and the rendered typography was visually checked.

SwiftPM selects the published host 0.23.0 XCFramework and its pinned checksum when no local artifact is present; TRUAPI_USE_LOCAL_BINARY=1 selects the locally built framework. Both selection paths were exercised with swift package dump-package. Native feature-branch testing still requires matching in-tree binaries.

Consumers

Chat authority belongs to #709. The refreshed stack also includes #1001, #1010, and #1011. Dot.li consumers paritytech/dotli-community#185, paritytech/dotli-community#255, paritytech/dotli-community#287, paritytech/dotli-community#290, and paritytech/dotli-community#291 carry exact SDK/WASM source and artifact hashes; their 0.23 browser wallet builds do not enable test-host. The combined browser deployment targets paseo.fyi.

No PR approval or merge is performed by this refresh.

[replghost]

@pgherveou @eugypalu all required checks are green, including Rust/Clippy, Android, iOS, browser artifacts, and license policy. Could one of you provide the required host-sdk-team approval so the merge queue can admit this dependency?

[pgherveou]

can we remove the generated files in the new js packages. Can't these be built from the src files ?

for the new bindings we can also added then to .gitattributes with linguist-generated=true, so that at least they show up as generated artifacts in the code review

[replghost]

Addressed in b0e178e: removed the committed browser dist/ tree, ignored it, and kept build/test/release generation source-driven. npm test now proves a clean package checkout builds the WASM and split workers before checksum verification; npm pack --dry-run --json still contains all ten release files. Added linguist-generated=true for the new Swift and FFI binding outputs in .gitattributes.

[replghost]

Cleanup CI is fully green; ready for rereview and merge queue admission.

[pgherveou]

DQ: why do all these things need to live in host-rust-core, they don't seem to have dependency on the rust-core stuff, and could be shipped independently ?

[replghost]

They share the Rust core directly rather than only co-locating artifacts:

• @parity/pvm-browser-runtime compiles rust/crates/pvm-runtime to wasm32-unknown-unknown; its JS workers are the adapter around that Wasm ABI.
• The same pvm-runtime crate is linked into truapi-server, so the existing UniFFI cdylib/XCFramework/AAR exports the native Swift/Kotlin runtime. A separate repository would require a second native library and package lifecycle in every host.
• pvm-gpu-wire is shared by the native and browser implementations, keeping bounds and binary GPU records identical.
• The existing host-rust-core CI/release jobs already regenerate UniFFI and publish the browser/native artifacts from one reviewed commit.

They could be split, but that would duplicate the Rust source/pins and create independent browser, XCFramework, and AAR versioning with an ABI-drift boundary. Keeping the runtime here makes the host-neutral Rust implementation the single source for all three targets; Epoca/Dotli/Brevity/Desktop remain independent consumers.

[replghost]

Does that shared Rust/UniFFI dependency path resolve the repository-placement concern, or do you want the runtime split into a separate repository before merge?

[replghost]

Additional review completed. Fixed three concrete boundary issues:

• Native constructors now enforce the same program, gas, asset-count, per-file, aggregate-byte, and safe-path limits as the browser ABI before guest compilation.
• The browser compiler backend now enforces the manifest graphics profile, one Tri2D submission per update, CoreVM framebuffer-only behavior, and GPU state/sequence errors consistently with the interpreter.
• Browser worker termination now closes its timer and MessageChannel ports; invalid launches no longer leak host-thread channels.

Added behavioral browser tests for malformed launch inputs and cross-profile framebuffer submission. Full workspace result: 1,205 tests passed, Clippy -D warnings passed, package tests 4/4 passed, and committed iOS bindings remain current.

Vendored commit 56c67a306fc276129829f94db85a622061e17882 into both consumers and exercised it end to end: Epoca App v2 10/10 plus seven-app browser matrix 45/45; Dotli Doom, Quake, Duke3D, NES, egui, GPU Cube, and Scene Lab all passed on the compiler backend.

[replghost]

PolkaVM dependency update:

• Rebased epoca/aarch64-jit-0.37 onto current paritytech/polkavm@master; branch head is e06cce9, 6 commits ahead / 0 behind.
• Ported the AArch64 JIT across the current code-blob, 32-bit address, dynamic-paging, memset, and 16 KiB page semantics.
• PolkaVM verification: 4,090 passed, 2 ignored; AArch64 assembler clippy passes with warnings denied.
• This PR now pins e06cce9 in commit 23f50c64.
• Host CI is green, including Rust workspace, native build, iOS bindings/package, browser provider, codegen, and dependency licenses.

[replghost]

Rebased the full PVM series onto current main (654c0cf0) with no semantic commit changes; git range-diff reports all 16 branch commits equivalent. New head: d0e16fcc.

Post-rebase verification:

• cargo test -p pvm-runtime --all-features: 20 passed
• npm test --prefix js/packages/pvm-browser-runtime: 4 passed

The PR is now up to date with main; remaining BLOCKED state is review protection while the refreshed CI run completes.

[replghost]

Added in 2c08d25:

• renamed the WebGPU Raster guest imports from epoca_gpu_* to the Host-neutral host_gpu_* namespace in the native and browser runtimes;
• added the draft docs/runtime/polkavm-app-abi-v1.md contract covering lifecycle, memory, Host imports, bounds, failure behavior, and conformance scope.

Consumer cutovers:

• paritytech/polkavm-app-kit#2
• paritytech/epoca#385

Verification remains green: cargo test -p pvm-runtime -p pvm-gpu-wire (33 passed), browser package tests (4 passed), App Kit tests (4 passed), reproducible example build/verify (six artifacts), and Epoca GPU tests (4 passed).

[replghost]

The repository-placement concern is now resolved by the extraction:

• the runtime implementation, GPU wire contract, browser workers/Wasm, tests, ABI documentation, and releases live in paritytech/pvm-host-runtime;
• the current immutable release is v0.1.4 at 235d1d407f3340fb73cb7a698fe973a9dad5251f;
• this PR now retains only the thin truapi-pvm-host integration boundary, truapi-server/UniFFI wiring, and the reviewed runtime/asset pin.

Generated browser output remains source-built and verified in the standalone repository; committed Swift/FFI bindings are marked generated. The full bridge matrix is green.

[github-actions]

This pull request touches an app, which is not built by default. Add a label for each build you want:

• iOS simulator build, ios-simulator-build: builds the iOS app, runs its tests and attaches a build for the iOS Simulator on a Mac.
• iOS device build, ios-device-build: attaches a signed build that installs on a registered iPhone or iPad.
• Android build, android-device-build: attaches an APK that installs on an Android phone or an emulator.

Each starts as soon as it is added and follows the branch from then on.