RFC: Runtime-aware App executables

[replghost]

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.html as its entrypoint.
• App manifest v2 declares exactly one explicit web or polkavm runtime.
• 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 fileTypes hint.
• Unsupported runtime requirements affect only the App executable.
• Hosts do not silently substitute another runtime or graphics profile.
• The App subname's contenthash remains the executable identity and update signal.
• Detailed graphics, device-input, audio, and packaging contracts are specified separately from the manifest RFC.

Initial graphics profiles

• framebuffer
• tri2d
• webgpu-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 base truapi artifact remains PolkaVM-free. Native runtime bindings belong to the standalone runtime distribution.
• Source-built @parity/polkavm-browser-runtime package, 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

[replghost]

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]

Repository boundary and execution plan

The PolkaVM App runtime will live in a standalone paritytech/pvm-host-runtime repository so its Rust runtime, GPU wire format, browser workers, deterministic artifacts, and conformance suite can iterate independently of unrelated TrUAPI workspace lanes.

host-rust-core will retain a small truapi-pvm-host bridge 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:

1. Extract the runtime from refactor(polkavm): isolate optional host composition #540 with history, using the reviewed 56c67a3 runtime as the behavioral baseline and the current refactor(polkavm): isolate optional host composition #540 head as the source tree.
2. Add path-aware standalone CI, deterministic asset reproduction, conformance, and an immutable release manifest tying Rust, npm, and browser artifacts to one source revision.
3. Publish the baseline standalone release.
4. Add truapi-pvm-host, cut host-rust-core over atomically, and remove the in-tree runtime implementation.
5. Migrate Epoca, Brevity, dotli, and remaining consumers to the bridge/exported assets.
6. Audit out every direct runtime pin and copied worker build path.

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]

Standalone extraction and Host cutover complete

The repository boundary described above is now implemented:

• standalone repository: https://github.com/paritytech/pvm-host-runtime
• baseline release: https://github.com/paritytech/pvm-host-runtime/releases/tag/v0.1.0
• immutable runtime source: 2ce39a291de97d6465c0b430ab638de56fe973c9
• host bridge: refactor(polkavm): isolate optional host composition #540 at d155fe267d5ec2f7e484016b1246fb05315450de
• Epoca migration: https://github.com/paritytech/epoca/pull/390
• Brevity migration: https://github.com/paritytech/brevity-dozer/pull/1136
• Dotli migration: feat(polkavm): run App Manifest v2 runtimes in Dotli dotli-community#185

pvm-host-runtime now owns pvm-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-core now owns only truapi-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-only pvm-gpu-wire dependency 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:

• standalone release source and post-release reproducibility workflow: green.
• host bridge full Rust, TypeScript, iOS binding/package, browser-provider, codegen, and license matrix: green.
• Epoca local/native/Android/bridge gates: green; exact-source full engine candidate and macOS lanes are running.
• Brevity local full workspace, desktop, codegen/bindgen, asset-contract, and physical Pixel seven-app matrix: green; hosted native lanes are running.
• Dotli unit, functional, build, asset-contract, and seven-app matrix: green. Its broad live Host-playground E2E remains red on the same external account/allowance path documented for current 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]

Final qualification result

The standalone extraction and consumer cutover are fully qualified.

• pvm-host-runtime main Runtime CI: green; baseline release v0.1.0 remains bound to source 2ce39a291de97d6465c0b430ab638de56fe973c9.
• host bridge refactor(polkavm): isolate optional host composition #540: full Rust workspace, browser provider, TypeScript packages, iOS bindings/package, codegen, licenses, and CI aggregator green at d155fe267d5ec2f7e484016b1246fb05315450de.
• Epoca AuthState::LoginFailed carries only free text, so hosts must regex-match prose to classify a failure #390 exact source d5142a73baa4583569cb106fae69af49d5201ca4: 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.
• Brevity Funding: core #1136 exact source bc4eea9a5960f8eb1340001ce90199bd14c731c7: core, desktop, Android, iOS, both permission matrices, sandbox, generated bindings/codegen, 102-case battery, asset contract, and Merge readiness all green.
• Dotli diagnosis: iOS host report #185 exact source 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 affecting main; it does not exercise the PVM adapter.

The dependency audit found no Host consumer directly pinning the standalone native runtime. truapi-pvm-host is 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]

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:

• release: https://github.com/paritytech/pvm-host-runtime/releases/tag/v0.1.4
• source: 235d1d407f3340fb73cb7a698fe973a9dad5251f
• host bridge: 90191e369a709d604631180931581b0563c2d0c7 in refactor(polkavm): isolate optional host composition #540

Final consumer heads:

• Epoca AuthState::LoginFailed carries only free text, so hosts must regex-match prose to classify a failure #390: 350fe296d629264e9de8b60b158cd625e33f20d3
• Brevity Funding: core #1136: 7283491be4052347b9a3c7fe46eb28e7ae93d9f4
• Dotli diagnosis: iOS host report #185: 5ba1ffa468ae09fa58d8d9c93caf314e06288286

Qualification:

• standalone v0.1.4: Runtime CI and immutable release workflow green; 6 browser tests and 39 Rust tests.
• host bridge: complete Rust/JS/iOS/codegen/license matrix green.
• Epoca: lint/policy, exact clean candidate build/full Zen/package/clean-profile smoke, immutable baseline, before/after regression comparison, Linux browser, macOS Metal, and Android all green.
• Brevity: core, desktop, Android, iOS, both permission matrices, sandbox, 102-case battery, asset contract, and Merge readiness all green.
• Dotli: byte-exact bridge asset gate, Unit, Functional, production build, and focused compiler/interpreter PVM browser suite green. The broad live Host-playground E2E remains red on the separately documented external account/allowance/signing path also affecting main; it does not exercise the PVM adapter.

Every Host consumer is back on the truapi-pvm-host bridge exporter. No temporary direct standalone-runtime integration remains.

[replghost]

GPUI/WebGPU and canonical UI-input rollout

The standalone runtime line is now published as v0.1.7, source 1a8a68a662cac9d8d5baece39515b643ff210b04.

Merged standalone work:

• feat(runtime): support GPUI editor workloads polkavm-host-runtime#21 — R8Unorm, read-only storage buffers, 64 MiB programs, aligned Host-call bounds, deterministic browser assets, and browser/native coverage.
• feat(ffi): expose canonical UI input and semantics polkavm-host-runtime#23 — canonical native UniFFI surface: atomic UTF-8/IME text input, exact extended input records, and semantic output.
• chore(release): prepare v0.1.7 polkavm-host-runtime#24 — immutable v0.1.7 release; release workflow and artifacts green.

Bridge #540 is green at 4d17a862250370b5bd8c5d5446b28cb9ad2cafbe, pinned to the v0.1.7 release source. Its generated Swift surface exposes sendTextInput, sendInputRecord, and takeUiSemantics; the iOS binding and Swift-package checks pass. GitHub rejects admin bypass here: #540 still needs paritytech/host-sdk-team approval and the merge queue.

Epoca adoption is paritytech/epoca#409. It rebases the superseded input branch onto current dev, pins bridge 4d17a862, records runtime v0.1.7, regenerates exact browser/native Android artifacts, and transports logical text atomically to the native process host instead of truncating it through InputEvent. 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]

Follow-up qualification found one browser-worker regression before Host merge: the generated GPU worker still referenced the removed submitted variable, so Epoca lint caught a no-undef error that standalone tests did not. The fix is merged in paritytech/polkavm-host-runtime#25 with a GpuEngine.execute regression test for resource-only batches.

The corrected immutable release is now v0.1.8, source 530885a9d6dbf5a2742d4f2ff9f5c71b05f2a762; release workflow and artifacts are green. Bridge #540 is updated at 85effb1b05cdfefa1e48ba3b2da4fb58684cd780 and 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 dev lint exposed the pre-existing #401 omission.

[replghost]

Qualification update: Epoca lint caught an undefined submitted reference 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, source 530885a9d6dbf5a2742d4f2ff9f5c71b05f2a762, 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.

[replghost]

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.

• RFC docs(rfc): runtime-aware app executables #507 includes main through ab6471645b2500719e0d0f7af1cc514c5ec75582; CI and RFC validation pass at e8f4ad0d994c3a97ded8311c05d83fe8c5bcdb80.
• Implementation refactor(polkavm): isolate optional host composition #540 has green core CI and green full iOS CI at e73014d21dcab5064b3484a9d599310fa523ef2d.
• The immutable native standalone pin e60a6135 has green runtime and release qualification: runtime CI, release.
• The five refreshed dotli consumer branches (diagnosis: iOS host report #185, feat(truapi-server): add host logic primitives #255, fix(dev): prevent stale generated bindings #287, feat: Add MoQ-over-Iroh #290, fix(host): cover Dotli signing regressions #291) have green checks. The combined paseo.fyi deployment at cf85255c21402d420f3daecafcbfc23dcd586483 passed 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-host is optional native composition, while the base truapi artifact remains PolkaVM-free. Native runtime bindings and the directly consumed @parity/polkavm-browser-runtime distribution 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.