From 3edb19328e7b0c24c64f9d323b9b6bf6dd5572ce Mon Sep 17 00:00:00 2001 From: w Date: Tue, 25 Aug 2026 21:39:00 -0400 Subject: [PATCH 1/6] RFC: runtime-aware App executables --- docs/rfcs/runtime-aware-app-executables.md | 324 +++++++++++++++++++++ 1 file changed, 324 insertions(+) create mode 100644 docs/rfcs/runtime-aware-app-executables.md diff --git a/docs/rfcs/runtime-aware-app-executables.md b/docs/rfcs/runtime-aware-app-executables.md new file mode 100644 index 000000000..b61dcfce1 --- /dev/null +++ b/docs/rfcs/runtime-aware-app-executables.md @@ -0,0 +1,324 @@ +--- +title: "Runtime-aware App executables" +owner: "@replghost" +status: draft +--- + +# RFC — Runtime-aware App executables + +## Summary + +This RFC introduces version 2 of the App executable manifest. The new format +makes an App's runtime and runtime requirements explicit. + +Web remains the mandatory App runtime and continues to be supported by every +Host that implements the App modality. Version 2 additionally allows a Product +to publish an App compiled for PolkaVM. A PolkaVM App declares the graphics, +device-input, and audio capabilities it requires from the Host. + +PolkaVM is an execution environment, not a modality or executable kind. +Framebuffer, Tri2D, and WebGPU Raster are graphics profiles provided to a +PolkaVM App. + +## Motivation + +The current App manifest describes a static web application: + +```ts +type AppManifestV1 = { + $v: 1; + kind: "app"; + appVersion: SemVer; +}; +``` + +Its runtime and entrypoint are implicit. The Host assumes that the artifact is +a web directory containing `index.html`. + +A PolkaVM App instead contains a program executed in a Host-owned sandbox. The +program does not receive a DOM, native view, filesystem, network connection, or +graphics device directly. It interacts with the Host through bounded, +versioned runtime contracts. + +A Host must be able to determine, before launch, which runtime an artifact +requires, where its entrypoint is, which graphics contract it uses, and whether +the current device can satisfy its input, audio, and resource requirements. + +Adding these fields to manifest version 1 would be unsafe. An older Host could +ignore them and attempt to launch a PolkaVM artifact as an `index.html` web +application. A new manifest version makes the incompatibility explicit and +fail-closed. + +## Detailed Design + +### App manifest v2 + +App executable manifests are stored in the existing `executable` text record +under: + +```text +app.. +``` + +Version 2 is a discriminated union over the runtime: + +```ts +type AppManifestV2 = + | WebAppManifestV2 + | PolkaVmAppManifestV2; + +type CommonAppFieldsV2 = { + $v: 2; + kind: "app"; + appVersion: SemVer; +}; + +type WebAppManifestV2 = CommonAppFieldsV2 & { + runtime: WebRuntime; +}; + +type PolkaVmAppManifestV2 = CommonAppFieldsV2 & { + runtime: PolkaVmRuntime; + capabilities: PolkaVmCapabilities; +}; + +type WebRuntime = { + kind: "web"; + entrypoint: string; +}; + +type PolkaVmRuntime = { + kind: "polkavm"; + abiVersion: 1; + entrypoint: string; +}; +``` + +An entrypoint is an archive-relative path. It must be non-empty, must not begin +with `/`, and must not contain `..` path segments. A web entrypoint must +identify an HTML document. A PolkaVM entrypoint must identify a `.polkavm` +program. + +The root Product manifest is unchanged and remains independently versioned. + +### Web runtime + +Web is the mandatory runtime for the App modality. + +A Host that implements the App modality must support web App executables. A +Host supporting App manifest version 2 must accept `runtime.kind: "web"`. + +App manifest version 1 remains valid and is equivalent to: + +```json +{ + "runtime": { + "kind": "web", + "entrypoint": "index.html" + } +} +``` + +Version 2 does not replace or deprecate the existing web execution model. It +makes the runtime explicit so that web and PolkaVM Apps can use the same +discovery mechanism. + +The PolkaVM capability declarations introduced by this RFC do not apply to web +Apps. Web permissions and capabilities continue to be governed by the web +sandbox and existing Host APIs. + +### PolkaVM runtime + +PolkaVM is an optional App runtime. + +A Host that does not implement PolkaVM skips the App executable and reports +that its runtime is unsupported. This does not make the Product malformed or +prevent the Host from using its other executable records. + +A PolkaVM App remains `ProductExecutionKind::App` for TruAPI service gating. +Its runtime does not create a new Product identity or permission scope. + +Implementing PolkaVM must not reduce or replace the Host's support for web +Apps. + +### PolkaVM capabilities + +A PolkaVM App declares the capabilities it requires: + +```ts +type PolkaVmCapabilities = { + graphics: GraphicsRequirement; + deviceInput?: DeviceInputRequirement; + audio?: AudioRequirement; +}; + +type GraphicsRequirement = { + abiVersion: 1; + profile: "framebuffer" | "tri2d" | "webgpu-raster"; + requiredFeatures: string[]; + requiredLimits?: Record; +}; + +type DeviceInputRequirement = { + abiVersion: 1; + requiredFeatures: Array< + "pointer" | "keyboard" | "touch" | "wheel" | + "text" | "ime" | "focus" + >; +}; + +type AudioRequirement = { + abiVersion: 1; + requiredFeatures: string[]; +}; +``` + +Graphics is required. Device input and audio are optional and should be omitted +when unused. + +The graphics profiles have the following roles: + +- `framebuffer` accepts complete packed pixel frames; +- `tri2d` accepts bounded texture updates and clipped indexed triangles through + a fixed Host rendering contract; +- `webgpu-raster` provides a bounded raster model aligned with WebGPU + semantics, including retained resources, WGSL shaders, pipelines, render + passes, and depth attachments. + +The profile describes application-visible behavior, not the Host's graphics +backend. A Host may implement a profile over Metal, Vulkan, WebGPU, or another +backend while preserving the specified behavior. + +Profile names describe application-visible Host contracts rather than +application architecture or platform graphics APIs. The unqualified name +`webgpu` is reserved for a future contract with a defined level of WebGPU +conformance. + +`deviceInput` is distinct from any user-facing Input modality. It describes +operating-system input delivered to a running App. Surface dimensions, scale, +format, and resize generation belong to the graphics contract. + +### Capability negotiation + +Before starting a PolkaVM App, the Host compares the manifest requirements with +its effective runtime capabilities. + +The Host skips the App executable when: + +- the runtime or an ABI version is unsupported; +- the graphics profile is unsupported; +- a required feature is unavailable; +- an effective limit is below a declared minimum; +- a required runtime capability cannot be initialized. + +Unknown required feature names and limit keys are rejected. Required limit +values must be positive safe integers within the ceilings defined by the +selected profile. + +The Host must not silently substitute a different runtime, graphics profile, +or software fallback. Each App executable declares exactly one runtime. + +### Embedded manifest + +Every version 2 App artifact must contain its executable manifest at: + +```text +manifest.json +``` + +The file must be byte-for-byte identical to the UTF-8 JSON stored in the App +subname's `executable` text record. + +A Host installing through dotNS validates the external manifest, fetches the +artifact identified by `contenthash`, and rejects the executable if the +embedded manifest is absent or differs from the external record. + +A Host installing an artifact locally or offline uses the embedded manifest as +the executable description. + +Publisher tooling should generate the manifest once and use the same bytes for +both locations. + +### Artifact identity and versioning + +The App subname's `contenthash` remains the executable's immutable identity and +update signal. + +`appVersion` remains a publisher-defined, user-visible release label. Hosts +must not use it to determine whether executable bytes changed. + +The following versions evolve independently: + +- App manifest schema version; +- PolkaVM application ABI version; +- graphics, device-input, and audio ABI versions; +- publisher-defined `appVersion`. + +### Runtime contract ownership + +This RFC defines runtime discovery and capability negotiation. It does not +define the binary protocol of each runtime capability. + +Normative profile specifications, checked decoders, shared constants, and +cross-Host conformance fixtures live in this repository under a Product +Runtime Contracts namespace separate from ordinary TruAPI services. + +A platform implementation is not itself normative. A Host may advertise a +profile only when it passes the conformance suite for the declared ABI version. + +### Compatibility + +Hosts that do not recognize App manifest version 2 skip the App executable and +report an unsupported manifest version. They must not attempt to interpret its +artifact as a version 1 web application. + +Hosts supporting version 2 continue to accept version 1 App manifests. + +Publisher tooling for version 2 must validate: + +- the manifest schema; +- entrypoint paths; +- valid runtime and capability combinations; +- profile-defined feature and limit names; +- the dotNS text-record size budget; +- presence and equality of the embedded manifest; +- required artifact files. + +This RFC changes only the App executable. Other executable kinds and +user-facing surfaces remain outside its scope. + +## Drawbacks + +Hosts and publisher tooling must support two App manifest versions during +migration. + +A valid Product may contain an App that cannot run on a particular Host. The +Host must present this as a compatibility limitation rather than as a malformed +or untrusted Product. + +The proposal also depends on separately maintained graphics, input, and audio +contracts with conformance coverage across participating Hosts. + +Embedding the manifest duplicates information stored in dotNS and introduces +an additional publishing-integrity check. + +## Alternatives + +### Extend App manifest version 1 + +Rejected because an older Host could ignore the new fields and attempt to +launch a PolkaVM artifact as web content. + +### Define PolkaVM as an executable kind + +Rejected because PolkaVM describes how an App executes, not the surface through +which the user encounters it. + +### Define Graphics as a modality or executable + +Rejected because graphics is a capability of the running App and does not +introduce a separate user-facing surface or lifecycle. + +## Unresolved Questions + +None. From 6b7a65f50d414ff47cb44e92efc7c2d82a246145 Mon Sep 17 00:00:00 2001 From: w Date: Thu, 27 Aug 2026 08:59:06 -0400 Subject: [PATCH 2/6] Clarify per-record manifest versioning --- docs/rfcs/runtime-aware-app-executables.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/rfcs/runtime-aware-app-executables.md b/docs/rfcs/runtime-aware-app-executables.md index b61dcfce1..b8250b84f 100644 --- a/docs/rfcs/runtime-aware-app-executables.md +++ b/docs/rfcs/runtime-aware-app-executables.md @@ -8,8 +8,9 @@ status: draft ## Summary -This RFC introduces version 2 of the App executable manifest. The new format -makes an App's runtime and runtime requirements explicit. +This RFC extends the Product Manifest Format with version 2 of the App +executable manifest. The new format makes an App's runtime and runtime +requirements explicit. Web remains the mandatory App runtime and continues to be supported by every Host that implements the App modality. Version 2 additionally allows a Product @@ -22,7 +23,7 @@ PolkaVM App. ## Motivation -The current App manifest describes a static web application: +The version 1 App manifest describes a static web application: ```ts type AppManifestV1 = { @@ -100,6 +101,8 @@ identify an HTML document. A PolkaVM entrypoint must identify a `.polkavm` program. The root Product manifest is unchanged and remains independently versioned. +The `$v` discriminator versions the individual record in which it appears. A +version 1 root manifest may therefore reference a version 2 App executable. ### Web runtime From 5c12e2cad500011ef72de1fa98037fc7228b1da2 Mon Sep 17 00:00:00 2001 From: w Date: Thu, 27 Aug 2026 19:20:40 -0400 Subject: [PATCH 3/6] Simplify runtime-aware App RFC --- docs/rfcs/runtime-aware-app-executables.md | 352 +++++++-------------- 1 file changed, 122 insertions(+), 230 deletions(-) diff --git a/docs/rfcs/runtime-aware-app-executables.md b/docs/rfcs/runtime-aware-app-executables.md index b8250b84f..1ffb90c96 100644 --- a/docs/rfcs/runtime-aware-app-executables.md +++ b/docs/rfcs/runtime-aware-app-executables.md @@ -8,113 +8,62 @@ status: draft ## Summary -This RFC extends the Product Manifest Format with version 2 of the App -executable manifest. The new format makes an App's runtime and runtime -requirements explicit. +This RFC introduces version 2 of the App executable manifest. It allows an App +to declare whether it runs as a web application or as a PolkaVM program. -Web remains the mandatory App runtime and continues to be supported by every -Host that implements the App modality. Version 2 additionally allows a Product -to publish an App compiled for PolkaVM. A PolkaVM App declares the graphics, -device-input, and audio capabilities it requires from the Host. +Web remains the mandatory App runtime. PolkaVM is an optional runtime that a +Host may additionally support. A PolkaVM App declares the versioned graphics +and other runtime capabilities it requires. -PolkaVM is an execution environment, not a modality or executable kind. -Framebuffer, Tri2D, and WebGPU Raster are graphics profiles provided to a -PolkaVM App. +PolkaVM is a runtime, not a new modality or executable kind. A PolkaVM App +retains the identity, lifecycle, and TruAPI access of an App. ## Motivation -The version 1 App manifest describes a static web application: +The version 1 App manifest assumes that every App is a web directory containing +`index.html`: -```ts -type AppManifestV1 = { - $v: 1; - kind: "app"; - appVersion: SemVer; -}; +```json +{ + "$v": 1, + "kind": "app", + "appVersion": [1, 0, 0] +} ``` -Its runtime and entrypoint are implicit. The Host assumes that the artifact is -a web directory containing `index.html`. - -A PolkaVM App instead contains a program executed in a Host-owned sandbox. The -program does not receive a DOM, native view, filesystem, network connection, or -graphics device directly. It interacts with the Host through bounded, -versioned runtime contracts. - -A Host must be able to determine, before launch, which runtime an artifact -requires, where its entrypoint is, which graphics contract it uses, and whether -the current device can satisfy its input, audio, and resource requirements. +This is insufficient for an App distributed as a PolkaVM program. Before +launch, a Host must know which runtime the artifact requires, where its +entrypoint is, and which Host capabilities are needed to present and operate +it. -Adding these fields to manifest version 1 would be unsafe. An older Host could -ignore them and attempt to launch a PolkaVM artifact as an `index.html` web -application. A new manifest version makes the incompatibility explicit and -fail-closed. +Adding these fields to version 1 would be unsafe. An older Host could ignore +them and attempt to launch a PolkaVM artifact as web content. Version 2 makes +the distinction explicit and fail-closed. ## Detailed Design -### App manifest v2 +### Manifest location and versioning -App executable manifests are stored in the existing `executable` text record -under: +App manifests remain stored in the `executable` text record under: ```text app.. ``` -Version 2 is a discriminated union over the runtime: - -```ts -type AppManifestV2 = - | WebAppManifestV2 - | PolkaVmAppManifestV2; - -type CommonAppFieldsV2 = { - $v: 2; - kind: "app"; - appVersion: SemVer; -}; - -type WebAppManifestV2 = CommonAppFieldsV2 & { - runtime: WebRuntime; -}; - -type PolkaVmAppManifestV2 = CommonAppFieldsV2 & { - runtime: PolkaVmRuntime; - capabilities: PolkaVmCapabilities; -}; - -type WebRuntime = { - kind: "web"; - entrypoint: string; -}; - -type PolkaVmRuntime = { - kind: "polkavm"; - abiVersion: 1; - entrypoint: string; -}; -``` - -An entrypoint is an archive-relative path. It must be non-empty, must not begin -with `/`, and must not contain `..` path segments. A web entrypoint must -identify an HTML document. A PolkaVM entrypoint must identify a `.polkavm` -program. +The root Product manifest is unchanged. Manifest versions apply to individual +records, so a version 1 root manifest may reference a version 2 App executable. -The root Product manifest is unchanged and remains independently versioned. -The `$v` discriminator versions the individual record in which it appears. A -version 1 root manifest may therefore reference a version 2 App executable. +Each version 2 App declares exactly one runtime. ### Web runtime -Web is the mandatory runtime for the App modality. - -A Host that implements the App modality must support web App executables. A -Host supporting App manifest version 2 must accept `runtime.kind: "web"`. - -App manifest version 1 remains valid and is equivalent to: +A version 2 web App declares its entrypoint explicitly: ```json { + "$v": 2, + "kind": "app", + "appVersion": [1, 4, 0], "runtime": { "kind": "web", "entrypoint": "index.html" @@ -122,206 +71,149 @@ App manifest version 1 remains valid and is equivalent to: } ``` +Web is the mandatory runtime for Hosts implementing the App modality. App +manifest version 1 remains valid and continues to imply a web runtime with +`index.html` as its entrypoint. + Version 2 does not replace or deprecate the existing web execution model. It makes the runtime explicit so that web and PolkaVM Apps can use the same discovery mechanism. -The PolkaVM capability declarations introduced by this RFC do not apply to web -Apps. Web permissions and capabilities continue to be governed by the web -sandbox and existing Host APIs. - ### PolkaVM runtime -PolkaVM is an optional App runtime. - -A Host that does not implement PolkaVM skips the App executable and reports -that its runtime is unsupported. This does not make the Product malformed or -prevent the Host from using its other executable records. - -A PolkaVM App remains `ProductExecutionKind::App` for TruAPI service gating. -Its runtime does not create a new Product identity or permission scope. - -Implementing PolkaVM must not reduce or replace the Host's support for web -Apps. - -### PolkaVM capabilities - -A PolkaVM App declares the capabilities it requires: - -```ts -type PolkaVmCapabilities = { - graphics: GraphicsRequirement; - deviceInput?: DeviceInputRequirement; - audio?: AudioRequirement; -}; - -type GraphicsRequirement = { - abiVersion: 1; - profile: "framebuffer" | "tri2d" | "webgpu-raster"; - requiredFeatures: string[]; - requiredLimits?: Record; -}; +A PolkaVM App declares its program, application ABI, and required Host +capabilities: -type DeviceInputRequirement = { - abiVersion: 1; - requiredFeatures: Array< - "pointer" | "keyboard" | "touch" | "wheel" | - "text" | "ime" | "focus" - >; -}; - -type AudioRequirement = { - abiVersion: 1; - requiredFeatures: string[]; -}; +```json +{ + "$v": 2, + "kind": "app", + "appVersion": [0, 1, 0], + "runtime": { + "kind": "polkavm", + "abiVersion": 1, + "entrypoint": "app.polkavm" + }, + "capabilities": { + "graphics": { + "abiVersion": 1, + "profile": "tri2d" + }, + "deviceInput": { + "abiVersion": 1 + }, + "audio": { + "abiVersion": 1 + } + } +} ``` -Graphics is required. Device input and audio are optional and should be omitted -when unused. - -The graphics profiles have the following roles: +PolkaVM support is optional. A Host that does not implement the PolkaVM runtime +skips the App executable and reports it as unsupported. This does not make the +Product malformed or affect its other executable records. -- `framebuffer` accepts complete packed pixel frames; -- `tri2d` accepts bounded texture updates and clipped indexed triangles through - a fixed Host rendering contract; -- `webgpu-raster` provides a bounded raster model aligned with WebGPU - semantics, including retained resources, WGSL shaders, pipelines, render - passes, and depth attachments. +A PolkaVM App must declare a graphics capability. Device input and audio are +optional and should be omitted when unused. -The profile describes application-visible behavior, not the Host's graphics -backend. A Host may implement a profile over Metal, Vulkan, WebGPU, or another -backend while preserving the specified behavior. +Runtime entrypoints are relative to the executable artifact. A web entrypoint +identifies an HTML document. A PolkaVM entrypoint identifies a `.polkavm` +program. -Profile names describe application-visible Host contracts rather than -application architecture or platform graphics APIs. The unqualified name -`webgpu` is reserved for a future contract with a defined level of WebGPU -conformance. +A PolkaVM App remains `ProductExecutionKind::App`. Its runtime does not create +a new Product identity, executable kind, or permission scope. -`deviceInput` is distinct from any user-facing Input modality. It describes -operating-system input delivered to a running App. Surface dimensions, scale, -format, and resize generation belong to the graphics contract. +### Graphics profiles -### Capability negotiation +Graphics ABI version 1 initially identifies three profiles: -Before starting a PolkaVM App, the Host compares the manifest requirements with -its effective runtime capabilities. +- `framebuffer` for complete packed pixel frames; +- `tri2d` for bounded textures and clipped indexed triangles; +- `webgpu-raster` for a bounded raster contract aligned with WebGPU semantics. -The Host skips the App executable when: +These profiles describe application-visible behavior, not the graphics backend +used by a particular Host. Different Hosts may implement the same profile +through different platform facilities. -- the runtime or an ABI version is unsupported; -- the graphics profile is unsupported; -- a required feature is unavailable; -- an effective limit is below a declared minimum; -- a required runtime capability cannot be initialized. +The operations, wire formats, feature vocabularies, limits, error behavior, +and conformance requirements of each profile are defined in separate +runtime-profile specifications. -Unknown required feature names and limit keys are rejected. Required limit -values must be positive safe integers within the ceilings defined by the -selected profile. +The unqualified name `webgpu` is reserved for a future contract with a defined +level of WebGPU conformance. -The Host must not silently substitute a different runtime, graphics profile, -or software fallback. Each App executable declares exactly one runtime. +Device input and audio follow the same versioning model: the App manifest +declares the required ABI version, while a separate runtime specification +defines its operations and behavior. -### Embedded manifest +### Host behavior -Every version 2 App artifact must contain its executable manifest at: +Before launch, the Host checks whether it supports: -```text -manifest.json -``` +- the declared runtime and runtime ABI; +- the declared graphics profile and ABI; +- the ABI versions of any other declared capabilities. -The file must be byte-for-byte identical to the UTF-8 JSON stored in the App -subname's `executable` text record. +If a requirement is unsupported, the Host skips that App executable and +reports it as incompatible. The Product and its other executable records +remain valid. -A Host installing through dotNS validates the external manifest, fetches the -artifact identified by `contenthash`, and rejects the executable if the -embedded manifest is absent or differs from the external record. +The Host must not silently substitute another runtime or graphics profile. It +either launches the declared runtime or reports the App as unsupported. -A Host installing an artifact locally or offline uses the embedded manifest as -the executable description. +A Host is not required to implement PolkaVM or every graphics profile. +Implementing PolkaVM must not reduce or replace its support for web Apps. -Publisher tooling should generate the manifest once and use the same bytes for -both locations. +### Artifact identity -### Artifact identity and versioning - -The App subname's `contenthash` remains the executable's immutable identity and -update signal. +The App subname's `contenthash` remains the executable artifact's immutable +identity and update signal. `appVersion` remains a publisher-defined, user-visible release label. Hosts must not use it to determine whether executable bytes changed. -The following versions evolve independently: - -- App manifest schema version; -- PolkaVM application ABI version; -- graphics, device-input, and audio ABI versions; -- publisher-defined `appVersion`. - -### Runtime contract ownership - -This RFC defines runtime discovery and capability negotiation. It does not -define the binary protocol of each runtime capability. - -Normative profile specifications, checked decoders, shared constants, and -cross-Host conformance fixtures live in this repository under a Product -Runtime Contracts namespace separate from ordinary TruAPI services. - -A platform implementation is not itself normative. A Host may advertise a -profile only when it passes the conformance suite for the declared ABI version. +The manifest schema, PolkaVM application ABI, runtime-capability ABIs, and +`appVersion` evolve independently. ### Compatibility -Hosts that do not recognize App manifest version 2 skip the App executable and -report an unsupported manifest version. They must not attempt to interpret its -artifact as a version 1 web application. - -Hosts supporting version 2 continue to accept version 1 App manifests. +A Host that does not recognize App manifest version 2 skips the App executable. +It must not interpret its artifact as a version 1 web application. -Publisher tooling for version 2 must validate: - -- the manifest schema; -- entrypoint paths; -- valid runtime and capability combinations; -- profile-defined feature and limit names; -- the dotNS text-record size budget; -- presence and equality of the embedded manifest; -- required artifact files. +A Host supporting version 2 continues to accept version 1 App manifests. This RFC changes only the App executable. Other executable kinds and -user-facing surfaces remain outside its scope. +user-facing surfaces are outside its scope. ## Drawbacks -Hosts and publisher tooling must support two App manifest versions during -migration. - -A valid Product may contain an App that cannot run on a particular Host. The -Host must present this as a compatibility limitation rather than as a malformed -or untrusted Product. +Hosts and publisher tooling must support two App manifest versions. -The proposal also depends on separately maintained graphics, input, and audio -contracts with conformance coverage across participating Hosts. +A valid Product may contain an App that is unavailable on a particular Host. +The Host must present this as a compatibility limitation rather than as a +malformed or untrusted Product. -Embedding the manifest duplicates information stored in dotNS and introduces -an additional publishing-integrity check. +The runtime capabilities named by this RFC require separate specifications and +cross-Host conformance tests. ## Alternatives ### Extend App manifest version 1 -Rejected because an older Host could ignore the new fields and attempt to -launch a PolkaVM artifact as web content. +Rejected because older Hosts could ignore the new fields and attempt to launch +a PolkaVM artifact as web content. ### Define PolkaVM as an executable kind -Rejected because PolkaVM describes how an App executes, not the surface through -which the user encounters it. +Rejected because PolkaVM describes how an App executes, not how the Product is +presented to the user. -### Define Graphics as a modality or executable +### Define Graphics as a modality -Rejected because graphics is a capability of the running App and does not -introduce a separate user-facing surface or lifecycle. +Rejected because graphics is a capability of a running App and does not +introduce a separate user-facing surface. ## Unresolved Questions -None. +The detailed graphics, device-input, and audio contracts will be proposed +separately. From 8be794c6d338bc34768c301377a1002a32a6b96a Mon Sep 17 00:00:00 2001 From: w Date: Mon, 28 Sep 2026 19:54:14 -0400 Subject: [PATCH 4/6] docs: make app input a baseline contract --- docs/rfcs/runtime-aware-app-executables.md | 52 ++++++++++++++++------ 1 file changed, 38 insertions(+), 14 deletions(-) diff --git a/docs/rfcs/runtime-aware-app-executables.md b/docs/rfcs/runtime-aware-app-executables.md index 1ffb90c96..7f140e178 100644 --- a/docs/rfcs/runtime-aware-app-executables.md +++ b/docs/rfcs/runtime-aware-app-executables.md @@ -13,7 +13,7 @@ to declare whether it runs as a web application or as a PolkaVM program. Web remains the mandatory App runtime. PolkaVM is an optional runtime that a Host may additionally support. A PolkaVM App declares the versioned graphics -and other runtime capabilities it requires. +and optional audio capabilities it requires. PolkaVM is a runtime, not a new modality or executable kind. A PolkaVM App retains the identity, lifecycle, and TruAPI access of an App. @@ -99,9 +99,6 @@ capabilities: "abiVersion": 1, "profile": "tri2d" }, - "deviceInput": { - "abiVersion": 1 - }, "audio": { "abiVersion": 1 } @@ -113,8 +110,8 @@ PolkaVM support is optional. A Host that does not implement the PolkaVM runtime skips the App executable and reports it as unsupported. This does not make the Product malformed or affect its other executable records. -A PolkaVM App must declare a graphics capability. Device input and audio are -optional and should be omitted when unused. +A PolkaVM App must declare a graphics capability. Audio is optional and should +be omitted when unused. Runtime entrypoints are relative to the executable artifact. A web entrypoint identifies an HTML document. A PolkaVM entrypoint identifies a `.polkavm` @@ -142,9 +139,32 @@ runtime-profile specifications. The unqualified name `webgpu` is reserved for a future contract with a defined level of WebGPU conformance. -Device input and audio follow the same versioning model: the App manifest -declares the required ABI version, while a separate runtime specification -defines its operations and behavior. +Audio follows the same versioning model: the App manifest declares the +required ABI version, while a separate runtime specification defines its +operations and behavior. + +### Baseline application input + +PolkaVM application ABI version 1 includes baseline interactive input. A Host +that implements this ABI provides pointer movement and buttons, physical key +transitions, committed UTF-8 text, wheel scrolling, focus changes, and surface +dimensions and scale. The Host normalizes platform input into this contract. +For example, a touch screen can provide pointer interaction and a software +keyboard can provide committed text. + +Baseline input is neither a manifest capability nor a permission. An App does +not declare pointer, keyboard, text, wheel, focus, or surface-metric +requirements, and a Host does not reject an App based on those declarations. +Committed text is distinct from clipboard access. It contains text entered +through the platform text system and grants no access to clipboard contents. + +Physical motion sensors and clipboard access are runtime-authorized facilities. +An App requests them when needed. The Host reports granted, denied, or +unavailable without changing whether the executable is structurally valid. +Physical motion access is foreground-scoped and stops when its execution loses +the foreground, closes, or loses authorization. Clipboard access requires a +separate permission and explicit user action; approved pasted text may then be +delivered through baseline committed-text input. ### Host behavior @@ -152,7 +172,7 @@ Before launch, the Host checks whether it supports: - the declared runtime and runtime ABI; - the declared graphics profile and ABI; -- the ABI versions of any other declared capabilities. +- the ABI version of a declared audio capability. If a requirement is unsupported, the Host skips that App executable and reports it as incompatible. The Product and its other executable records @@ -172,8 +192,8 @@ identity and update signal. `appVersion` remains a publisher-defined, user-visible release label. Hosts must not use it to determine whether executable bytes changed. -The manifest schema, PolkaVM application ABI, runtime-capability ABIs, and -`appVersion` evolve independently. +The manifest schema, PolkaVM application ABI, graphics and audio capability +ABIs, and `appVersion` evolve independently. ### Compatibility @@ -182,6 +202,11 @@ It must not interpret its artifact as a version 1 web application. A Host supporting version 2 continues to accept version 1 App manifests. +Draft implementations emitted a `deviceInput` capability before the baseline +input contract was settled. That field is not part of App manifest version 2. +Publishers must republish those executable manifests without it; Hosts must not +derive permission or input-delivery behavior from it. + This RFC changes only the App executable. Other executable kinds and user-facing surfaces are outside its scope. @@ -215,5 +240,4 @@ introduce a separate user-facing surface. ## Unresolved Questions -The detailed graphics, device-input, and audio contracts will be proposed -separately. +The detailed graphics and audio contracts will be proposed separately. From 48a04686d22891b7d420818e369def04607135a4 Mon Sep 17 00:00:00 2001 From: w Date: Tue, 29 Sep 2026 12:23:01 -0400 Subject: [PATCH 5/6] docs(rfc): add runtime file input and the fileTypes hint User files are runtime-authorized: Apps register handlers while running and receive a file only through the user's selection in Host UI. PolkaVM App manifests may carry an advisory top-level fileTypes list. The draft fileInput capability is not part of App manifest v2. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/rfcs/runtime-aware-app-executables.md | 52 ++++++++++++++++++++-- 1 file changed, 48 insertions(+), 4 deletions(-) diff --git a/docs/rfcs/runtime-aware-app-executables.md b/docs/rfcs/runtime-aware-app-executables.md index 7f140e178..50542b863 100644 --- a/docs/rfcs/runtime-aware-app-executables.md +++ b/docs/rfcs/runtime-aware-app-executables.md @@ -166,6 +166,48 @@ the foreground, closes, or loses authorization. Clipboard access requires a separate permission and explicit user action; approved pasted text may then be delivered through baseline committed-text input. +User files are runtime-authorized in the same way. An App registers file +handlers while it runs, and a file reaches it only when the user selects one in +Host UI. A handler either delivers the file to the running App or relaunches +the App with the file mounted as an asset. The PolkaVM application ABI defines +the registration and delivery contract. + +### File-type hint + +A PolkaVM App may list the files it opens in a top-level `fileTypes` field: + +```json +{ + "$v": 2, + "kind": "app", + "appVersion": [0, 5, 0], + "runtime": { + "kind": "polkavm", + "abiVersion": 1, + "entrypoint": "app.polkavm" + }, + "capabilities": { + "graphics": { "abiVersion": 1, "profile": "framebuffer" } + }, + "fileTypes": [ + { + "label": "SNES cartridge image", + "extensions": [".sfc", ".smc"], + "handler": "snes-rom" + } + ] +} +``` + +Each entry names a label, file extensions or MIME types, and optionally the +runtime handler that receives those files. A Host may use the list to suggest +the App for a file before it has run, and a store may show it as the files the +App opens. The list is not a capability and grants nothing: a file is delivered +only to a handler the running App registered. + +`fileTypes` is defined only for the PolkaVM runtime. Publisher tooling rejects +it on a web App. + ### Host behavior Before launch, the Host checks whether it supports: @@ -174,6 +216,8 @@ Before launch, the Host checks whether it supports: - the declared graphics profile and ABI; - the ABI version of a declared audio capability. +`fileTypes` never makes an App incompatible. + If a requirement is unsupported, the Host skips that App executable and reports it as incompatible. The Product and its other executable records remain valid. @@ -202,10 +246,10 @@ It must not interpret its artifact as a version 1 web application. A Host supporting version 2 continues to accept version 1 App manifests. -Draft implementations emitted a `deviceInput` capability before the baseline -input contract was settled. That field is not part of App manifest version 2. -Publishers must republish those executable manifests without it; Hosts must not -derive permission or input-delivery behavior from it. +Draft implementations emitted `deviceInput` and `fileInput` capabilities. +Neither field is part of App manifest version 2. Publishers must republish +those executable manifests without them; Hosts must not derive permission or +input-delivery behavior from them. This RFC changes only the App executable. Other executable kinds and user-facing surfaces are outside its scope. From 554c719946f7f432ca0a5b3a48c5c6170044f118 Mon Sep 17 00:00:00 2001 From: w Date: Tue, 29 Sep 2026 15:29:30 -0400 Subject: [PATCH 6/6] docs(rfc): clarify optional runtime activation --- docs/rfcs/runtime-aware-app-executables.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/rfcs/runtime-aware-app-executables.md b/docs/rfcs/runtime-aware-app-executables.md index 50542b863..34500864c 100644 --- a/docs/rfcs/runtime-aware-app-executables.md +++ b/docs/rfcs/runtime-aware-app-executables.md @@ -228,6 +228,12 @@ either launches the declared runtime or reports the App as unsupported. A Host is not required to implement PolkaVM or every graphics profile. Implementing PolkaVM must not reduce or replace its support for web Apps. +Support for an optional runtime may depend on build configuration, deployment +policy, or a user-controlled experimental setting. An App cannot enable a +runtime for itself. A change to runtime availability takes effect on the next +executable launch; the Host may terminate and relaunch an active executable +when the setting changes. + ### Artifact identity The App subname's `contenthash` remains the executable artifact's immutable