Skip to content

RFC: Runtime-aware App executables #550

Open

Description

@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

Tasks

Activity

  1. added
    enhancementNew feature or request
    area:rfcAn RFC, or work tracked by one under docs/rfcs
    on Aug 28, 2026
  2. changed the title [-]Add a host-neutral PolkaVM App v2 runtime[/-] [+]RFC: Runtime-aware App executables[/+] on Aug 28, 2026
  3. replghost commented on Aug 29, 2026

    @replghost
    ContributorAuthor

    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.

  4. replghost commented on Aug 29, 2026

    @replghost
    ContributorAuthor

    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.

  5. replghost commented on Aug 29, 2026

    @replghost
    ContributorAuthor

    Standalone extraction and Host cutover complete

    The repository boundary described above is now implemented:

    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.

  6. replghost commented on Aug 29, 2026

    @replghost
    ContributorAuthor

    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.

  7. replghost commented on Aug 30, 2026

    @replghost
    ContributorAuthor

    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:

    Final consumer heads:

    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.

  8. replghost commented on Sep 3, 2026

    @replghost
    ContributorAuthor

    GPUI/WebGPU and canonical UI-input rollout

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

    Merged standalone work:

    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.

  9. replghost commented on Sep 3, 2026

    @replghost
    ContributorAuthor

    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.

  10. replghost commented on Sep 3, 2026

    @replghost
    ContributorAuthor

    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.

  11. replghost commented on Sep 29, 2026

    @replghost
    ContributorAuthor

    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.

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:rfcAn RFC, or work tracked by one under docs/rfcsenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions