Repository navigation
Description
Source RFC: #507 · docs/rfcs/runtime-aware-app-executables.md · @replghost
Core implementation: #540
Problem
Hosts need to execute content-addressed App products through runtimes other than the implicit web index.html runtime defined by App manifest v1. Implementing the PolkaVM runtime, hostcalls, graphics transports, and native bindings independently in each Host would create incompatible manifest, bounds, and ABI behavior.
Goal
Define a runtime-aware App manifest and provide one host-neutral PolkaVM implementation that browser and native Hosts can consume from the same reviewed source.
Web remains the mandatory App runtime. PolkaVM is optional and remains an App runtime rather than becoming a new modality or executable kind.
Requirements
- App manifest v1 remains valid and implies a web runtime with
index.htmlas its entrypoint. - App manifest v2 declares exactly one explicit
weborpolkavmruntime. - A PolkaVM App declares its application ABI and a graphics profile.
- Audio may be declared as a separately versioned runtime capability; baseline input is part of the application ABI.
- User file input is runtime-authorized; the manifest carries only an advisory
fileTypeshint. - Unsupported runtime requirements affect only the App executable.
- Hosts do not silently substitute another runtime or graphics profile.
- The App subname's
contenthashremains the executable identity and update signal. - Detailed graphics, device-input, audio, and packaging contracts are specified separately from the manifest RFC.
Initial graphics profiles
framebuffertri2dwebgpu-raster
The profiles describe application-visible Host contracts rather than a particular platform graphics backend.
Core implementation scope
- Host-neutral PolkaVM App runtime and GPU wire crates in
paritytech/polkavm-host-runtime. - Bounded program, memory, asset, hostcall, input, audio, save, log, Tri2D, and WebGPU resources.
- Framebuffer, Tri2D, and WebGPU Raster presentation without profile substitution.
- Cooperative and CoreVM guest execution.
- Browser compiler backend with guarded interpreter fallback.
- Optional native composition through
truapi-polkavm-host; the basetruapiartifact remains PolkaVM-free. Native runtime bindings belong to the standalone runtime distribution. - Source-built
@parity/polkavm-browser-runtimepackage, consumed directly from the standalone runtime distribution. - Pinned PolkaVM native and browser translator revisions.
Implementation references
- RFC document: docs(rfc): runtime-aware app executables #507
- Optional TrUAPI runtime composition: refactor(polkavm): isolate optional host composition #540
- Standalone runtime, browser assets, and native bindings: https://github.com/paritytech/polkavm-host-runtime
- Epoca 0.2.0 and later: https://github.com/paritytech/epoca
- dotli-community implementation branch: https://github.com/paritytech/dotli-community/tree/feat/pvm-wasm
- Reproducible examples: https://github.com/paritytech/product-runtime-examples
Tasks
- RFC document body — docs(rfc): runtime-aware app executables #507
- RFC review and acceptance
- Product Manifest v2 schema and publisher validation
- Host-neutral runtime implementation — refactor(polkavm): isolate optional host composition #540
- Specify and publish PolkaVM application runtime ABI v1
- App v2 artifact packaging contract, including embedded/external manifest equality
- Framebuffer runtime contract
- Tri2D runtime contract
- WebGPU Raster runtime contract
- Device-input runtime contract
- File-input runtime contract — docs(abi): register file handlers at runtime polkavm-host-runtime#69
- Audio runtime contract
- Cross-Host conformance fixtures
- Reproducible App manifest v2 examples — https://github.com/paritytech/product-runtime-examples
- Host adoption
- Epoca 0.2.0+
- dotli-community
- iOS
- Android
Activity
[-]Add a host-neutral PolkaVM App v2 runtime[/-][+]RFC: Runtime-aware App executables[/+]replghost commentedon Aug 29, 2026
PolkaVM application runtime ABI v1 is now drafted in #540 at
docs/runtime/polkavm-app-abi-v1.md(commit 2c08d25). The checklist remains open until the contract's import names, input-v1 scope, limits, scheduling, save behavior, and CoreVM separation are reviewed and the conformance fixtures land.The GPU imports were cut over to the Host-neutral
host_gpu_*namespace, with consumer updates in paritytech/polkavm-app-kit#2 and paritytech/epoca#385.replghost commentedon Aug 29, 2026
Repository boundary and execution plan
The PolkaVM App runtime will live in a standalone
paritytech/pvm-host-runtimerepository so its Rust runtime, GPU wire format, browser workers, deterministic artifacts, and conformance suite can iterate independently of unrelated TrUAPI workspace lanes.host-rust-corewill retain a smalltruapi-pvm-hostbridge crate. The bridge pins one immutable standalone runtime revision, re-exports the supported host-facing Rust API, and exposes the matching browser asset identities to native and browser Hosts. Downstream Hosts consume only this bridge; direct standalone-runtime pins are not part of the supported integration surface.Execution order:
56c67a3runtime as the behavioral baseline and the current refactor(polkavm): isolate optional host composition #540 head as the source tree.truapi-pvm-host, cut host-rust-core over atomically, and remove the in-tree runtime implementation.Both repositories will use one always-running merge-readiness aggregator. Runtime-local PRs run only the affected Rust/browser/artifact lanes; bridge, shared-lock, merge-queue, release, and nightly changes run the complete matrix. Superseded runs are cancelled and caches are keyed by the immutable runtime source revision.
The runtime ABI draft and conformance checklist remain tracked here; implementation and release work moves to the standalone repository.
replghost commentedon Aug 29, 2026
Standalone extraction and Host cutover complete
The repository boundary described above is now implemented:
2ce39a291de97d6465c0b430ab638de56fe973c9d155fe267d5ec2f7e484016b1246fb05315450depvm-host-runtimenow ownspvm-runtime,pvm-gpu-wire, browser workers, deterministic asset generation, the App ABI draft, path-aware Rust/browser CI, release manifests, and reproducible release assets. The release binds Rust, npm, and seven embedded browser assets to one source revision and published SHA-256 manifest.host-rust-corenow owns onlytruapi-pvm-host, which pins that source, re-exports the native API, preserves the UniFFI namespace, and exports the exact browser asset set. The in-tree runtime crates, browser package, and duplicate ABI document were removed.Consumer audit result: Host consumers pin only
truapi-pvm-host@d155fe2; the bridge alone pins the native standalone runtime. Epoca's guest-onlypvm-gpu-wiredependency pins the same standalone release because it is the application-facing wire contract. All copied worker build paths were replaced with bridge-export-and-hash gates.Qualification so far:
main; it does not exercise the PVM adapter.The remaining blockers are repository review protection on #540 and completion of the hosted Epoca/Brevity exact-source matrices. No direct runtime pin remains in a Host consumer.
replghost commentedon Aug 29, 2026
Final qualification result
The standalone extraction and consumer cutover are fully qualified.
pvm-host-runtimemain Runtime CI: green; baseline releasev0.1.0remains bound to source2ce39a291de97d6465c0b430ab638de56fe973c9.d155fe267d5ec2f7e484016b1246fb05315450de.AuthState::LoginFailedcarries only free text, so hosts must regex-match prose to classify a failure #390 exact sourced5142a73baa4583569cb106fae69af49d5201ca4: clean candidate build/full Zen/package/clean-profile smoke green; immutable baseline green; before/after regression comparison green; Linux browser integration green; macOS Metal integration green; Android and policy/lint gates green.bc4eea9a5960f8eb1340001ce90199bd14c731c7: core, desktop, Android, iOS, both permission matrices, sandbox, generated bindings/codegen, 102-case battery, asset contract, and Merge readiness all green.4b6a13317dc1b5b3ec2ad14b5b038cdae5130b1a: byte-exact bridge asset gate, Unit, Functional, build, and seven-app PVM coverage green. The broad live Host-playground E2E remains red on the separately documented external account/allowance/signing path also affectingmain; it does not exercise the PVM adapter.The dependency audit found no Host consumer directly pinning the standalone native runtime.
truapi-pvm-hostis the sole Host integration boundary; Epoca's guest-only GPU wire pin is the application-facing ABI contract at the same standalone release.Implementation is complete. Remaining PR blockers are repository review requirements, not code or qualification failures.
replghost commentedon Aug 30, 2026
Runtime hardening rollout complete
Follow-up browser/runtime testing exposed three behaviors that belonged upstream rather than in consumer-owned worker patches: explicit interpreter selection/startup diagnostics, baseline TrUAPI transport and bounded input handling, and Safari-compatible single-memory translated guests. Those changes are now published through the standalone boundary rather than patched in Dotli or Epoca.
Authoritative release:
235d1d407f3340fb73cb7a698fe973a9dad5251f90191e369a709d604631180931581b0563c2d0c7in refactor(polkavm): isolate optional host composition #540Final consumer heads:
AuthState::LoginFailedcarries only free text, so hosts must regex-match prose to classify a failure #390:350fe296d629264e9de8b60b158cd625e33f20d37283491be4052347b9a3c7fe46eb28e7ae93d9f45ba1ffa468ae09fa58d8d9c93caf314e06288286Qualification:
main; it does not exercise the PVM adapter.Every Host consumer is back on the
truapi-pvm-hostbridge exporter. No temporary direct standalone-runtime integration remains.replghost commentedon Sep 3, 2026
GPUI/WebGPU and canonical UI-input rollout
The standalone runtime line is now published as
v0.1.7, source1a8a68a662cac9d8d5baece39515b643ff210b04.Merged standalone work:
R8Unorm, read-only storage buffers, 64 MiB programs, aligned Host-call bounds, deterministic browser assets, and browser/native coverage.v0.1.7release; release workflow and artifacts green.Bridge #540 is green at
4d17a862250370b5bd8c5d5446b28cb9ad2cafbe, pinned to thev0.1.7release source. Its generated Swift surface exposessendTextInput,sendInputRecord, andtakeUiSemantics; the iOS binding and Swift-package checks pass. GitHub rejects admin bypass here: #540 still needsparitytech/host-sdk-teamapproval and the merge queue.Epoca adoption is paritytech/epoca#409. It rebases the superseded input branch onto current
dev, pins bridge4d17a862, records runtimev0.1.7, regenerates exact browser/native Android artifacts, and transports logical text atomically to the native process host instead of truncating it throughInputEvent. Focused native, bridge-lock, process protocol, and semantic text-routing checks pass locally; hosted Linux/macOS/Android matrices are running.RFC #507 is current with
main, green, and mergeable; it has the same host-sdk-team approval + merge-queue gate. Obsolete release PR #548 was closed because it reintroduced the removed in-tree runtime and duplicated the standalone package publication boundary.replghost commentedon Sep 3, 2026
Follow-up qualification found one browser-worker regression before Host merge: the generated GPU worker still referenced the removed
submittedvariable, so Epoca lint caught ano-undeferror that standalone tests did not. The fix is merged in paritytech/polkavm-host-runtime#25 with aGpuEngine.executeregression test for resource-only batches.The corrected immutable release is now
v0.1.8, source530885a9d6dbf5a2742d4f2ff9f5c71b05f2a762; release workflow and artifacts are green. Bridge #540 is updated at85effb1b05cdfefa1e48ba3b2da4fb58684cd780and all required checks pass. Auto-merge is armed, waiting only for host-sdk-team approval and the required merge queue.Epoca #409 pins that exact bridge/runtime release, refreshes browser and both Android native artifacts, and removes the now-obsolete worker guard. Android and PR-policy/lint checks are green; exact-source baseline/candidate and Linux/macOS browser matrices are still running. The generated Polkadot icon also received its missing canonical MPL header after current
devlint exposed the pre-existing #401 omission.replghost commentedon Sep 3, 2026
Qualification update: Epoca lint caught an undefined
submittedreference in the v0.1.7 GPU worker before Host merge. The source fix and resource-only batch regression test are merged as paritytech/polkavm-host-runtime#25; immutable hotfix v0.1.8, source530885a9d6dbf5a2742d4f2ff9f5c71b05f2a762, is published with a green release workflow.Bridge #540 is green at
85effb1b05cdfefa1e48ba3b2da4fb58684cd780, pinning v0.1.8, with auto-merge armed pending host-sdk-team approval and merge queue. Epoca #409 pins that bridge head and v0.1.8, and has green Android, PR-policy/lint, baseline, and Linux PVM integration lanes; externally canceled candidate/macOS jobs are being retried.docs(rfc): separate incoming sessions from the input modality, add tr…
replghost commentedon Sep 29, 2026
Current integration boundary and qualification
This issue is the tracking issue, not a pull request. Its acceptance checkboxes remain unchanged; CI passing is not RFC acceptance or cross-Host conformance approval.
ab6471645b2500719e0d0f7af1cc514c5ec75582; CI and RFC validation pass ate8f4ad0d994c3a97ded8311c05d83fe8c5bcdb80.e73014d21dcab5064b3484a9d599310fa523ef2d.e60a6135has green runtime and release qualification: runtime CI, release.cf85255c21402d420f3daecafcbfc23dcd586483passed all eight published PVM product scenarios and 19 TrUAPI capability checks. Independent Chromium verification rendered the deployed guest and confirmed that exact release.The current repository boundary supersedes the historical bridge-export-only guidance above:
truapi-polkavm-hostis optional native composition, while the basetruapiartifact remains PolkaVM-free. Native runtime bindings and the directly consumed@parity/polkavm-browser-runtimedistribution belong to the standalone runtime repository. Web remains mandatory; PolkaVM remains optional, with no silent runtime/profile substitution.Chat, Seity, and peer transport remain separate stacked reviews. Their hosted qualification is recorded on their own PRs, not inferred from #540. No PR approval or merge was performed.
docs(rfc): separate incoming sessions from the input modality, add tr…