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.
• Device input and audio may be declared as separately versioned runtime capabilities.
• 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.
• 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.
• Swift and Kotlin access through the existing UniFFI Host artifact.
• Source-built @parity/pvm-browser-runtime package.
• Pinned PolkaVM native and browser translator revisions.

Implementation references

• RFC document: RFC: Runtime-aware App executables #507
• Host-neutral core runtime: feat(pvm): expose standalone runtime through host bridge #540
• 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 — RFC: Runtime-aware App executables #507
• RFC review and acceptance
• Product Manifest v2 schema and publisher validation
• Host-neutral runtime implementation — feat(pvm): expose standalone runtime through host bridge #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
• 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 feat(pvm): expose standalone runtime through host bridge #540 with history, using the reviewed 56c67a3 runtime as the behavioral baseline and the current feat(pvm): expose standalone runtime through host bridge #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: feat(pvm): expose standalone runtime through host bridge #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(pvm): 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 feat(pvm): expose standalone runtime through host bridge #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 #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 feat(pvm): expose standalone runtime through host bridge #540

Final consumer heads:

• Epoca AuthState::LoginFailed carries only free text, so hosts must regex-match prose to classify a failure #390: 350fe296d629264e9de8b60b158cd625e33f20d3
• Brevity #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.