RFC: Runtime-aware App executables

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: #507
• Host-neutral core runtime: #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 — #507
• RFC review and acceptance
• Product Manifest v2 schema and publisher validation
• Host-neutral runtime implementation — #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

Start with docs/rfcs/runtime-aware-app-executables.md and the host-neutral runtime implementation in #540. Review the remaining manifest, ABI, packaging, graphics, device, audio, conformance, and host-adoption tasks to identify a focused work item. Done requires the relevant contract or implementation to be specified, reviewed, and covered by the listed conformance or reproducible examples.