简体中文

PVM Runtime

Build protected business screens once, compile them into signed bytecode, and execute them with one C++17 VM while Android, iOS, and HarmonyOS keep rendering real native UI.

PVM Runtime targets applications that need cross-platform delivery, native user experience, and stronger business-logic protection. Kotlin, Swift, ArkTS, and JavaScript business source does not enter the production package. The VM can reach native UI and system features only through a constrained UIHost and versioned Capability Host.

Runtime 5 · PVBC v5 · C++17 · Ed25519 · Android / iOS / HarmonyOS

Website · Download SDKs and Migration Studio · Quick start · 0.6.0 release notes · Documentation · Discussions · Report an issue

Android · HONOR physical device	iOS · iPhone 17 Pro Max Simulator	HarmonyOS · HUAWEI Pura 70 physical device

All three hosts execute platform-bound builds of the same Counter DSL. Native control events travel through the host into the C++17 VM, and UI Wire v2 returns incremental patches to RecyclerView, UICollectionView/SwiftUI, and ArkUI hosts.

Use the prebuilt SDKs

Download versioned artifacts from the latest GitHub Release; consumer applications do not need to build PVM Runtime itself. The release also contains PVMRuntime-demo-0.6.0-debug.apk for direct Android installation and evaluation.

Platform	Add to an existing app	Prebuilt artifact
Android	Maven dependency or local AAR	com.protectedvm:pvm-runtime:0.6.0 / pvm-runtime-android-0.6.0.aar
iOS	Binary Swift Package or XCFramework	PVMRuntimeBinaryPackage-0.6.0.zip / PVMRuntime-0.6.0.xcframework.zip
HarmonyOS	OHPM dependency from a local or private registry	pvm-runtime-harmony-0.6.0.har

Existing applications can migrate one class, several selected classes, or one or more modules with the downloadable Windows/macOS PVM Migration Studio. Generated DSL stays reviewable and must pass source-drift, structure, behavior, capability, signature, and C++17 runtime checks before it can be accepted.

What it solves

Cross-platform systems often trade native capability against dynamic delivery, offline availability, or source protection. PVM separates those concerns into a stable runtime and four explicit delivery profiles:

• One DSL source produces platform- and profile-bound signed modules with the same PVBC semantics. A single .pvm is never reused across platforms.
• One C++17 runtime validates signatures, bindings, rollback floors, bytecode, control flow, types, and resource budgets.
• Native hosts render the neutral UI tree. The current builds cover Android View, UIKit/SwiftUI, and ArkUI compiled with DevEco API 24.
• KMP publishes shared lifecycle and event APIs for JVM and Kotlin/Native. Compose/CMP and Kuikly renderers remain product-specific ports.
• The local migration scanner can select one class, multiple classes, or one or more existing modules and generate a reviewable DSL scaffold without modifying the legacy project. Strict verification blocks source drift, unresolved review items, unapproved capabilities, invalid DSL, and behavior mismatches before signing.
• Payments, maps, camera, media, push, and other privileged features remain in the host and are called through versioned capability IDs.
• Offline and network delivery are separate build outputs, not runtime flags that pretend to offer the same guarantees.

Architecture

Plane	Responsibility	Main outputs
Build Plane	DSL lint, profile/IDL constraints, deterministic compilation, remote signing	PVBC payload and signed .pvm
Delivery Plane	Content-addressed repository, signed manifests, activation, rollout, audit	Immutable modules and manifest envelopes
Device Plane	Signature verification, rollback prevention, preload, recovery, native rendering	LKG cache, UI tree, capability effects

See Architecture and data flow and Security model.

PVM Migration Studio

The C++17/Qt desktop application turns selective migration into a guided Scan → Convert → Review → Verify workflow. It supports one class, multiple classes, one module, multiple modules, or a combined selection, while using the same migration engine and verification gates as the CLI and CI.

make migration-studio-package
make migration-studio-run

Qt, tool caches, builds, packages, and migration outputs remain inside this repository. See Migration Studio for the workflow, package contents, verification boundary, and directory map.

Delivery profiles

Profile	How the module reaches the device	Typical use
Offline Sealed	The target app embeds a signed module in an APK/AAB, IPA, or HAP	Offline first launch, weak networks, regulated enterprise
Online Provisioned	Download after activation, then use a local LKG	Keep the complete module out of the static package
Store On-Demand	Deliver signed resources through mechanisms allowed by the store	Store-managed on-demand content
Enterprise Managed	Private repository, MDM, organization license, and audit	Private distribution and managed devices

The compiler turns channel policy into build constraints. For example, Android profiles reject delivered .dex, .jar, and .so, while iOS profiles reject native dynamic downloads.

Precompiled SDK distribution

Consumer applications do not need to compile the PVM Runtime source. A versioned SDK release contains:

Platform	Precompiled dependency	Consumer entry
Android	pvm-runtime-android-0.6.0.aar or Maven	com.protectedvm:pvm-runtime:0.6.0
iOS	PVMRuntimeBinaryPackage-0.6.0.zip or PVMRuntime-0.6.0.xcframework.zip	import PVMRuntime
HarmonyOS	pvm-runtime-harmony-0.6.0.har	import ... from '@pvm/runtime'

Maintainers with all three SDK toolchains run make sdk-release-assets; the command builds, validates, and writes immutable upload inputs plus dist/release/SHA256SUMS. Publishing a GitHub Release automatically publishes the Android Maven coordinate to GitHub Packages. Target applications still own their App ID, embedded business module, permissions, signing, and store package.

Current capabilities

Compiler and module format

• JSON-backed private DSL for state, UI trees, events, synchronous/asynchronous effects, and resource budgets.
• Deterministic PVBC v5 bytecode; Runtime 5 can read PVBC v1 through v5.
• Ed25519 module signatures, application/channel/platform/profile/release binding, SHA-256 content addressing, and signed manifests.
• Stable v4 persistence_id migration for renamed or added state fields, with type-conflict rejection.
• v5 event.value safely carries Input/Switch change and submit values into handlers and state.

Runtime and hosts

• C++17 loader, bytecode verifier, interpreter, stack type checks, control-flow validation, and an instruction watchdog.
• C ABI v4 enforces application/channel/platform/profile/release-floor binding, selects UI Wire v2 patch delivery, and is bridged through Android JNI, iOS Objective-C++, and HarmonyOS Node-API. C ABI v1–v3 retain complete-tree compatibility.
• Lifecycle: create → optional restore → one start → dispatch/complete → cancel → destroy. Events and async completion are rejected before start; restore and repeated start are rejected after start.
• Neutral UI tree, event routing, native surfaces, and sync/async capabilities.
• Android View, UIKit/SwiftUI, and ArkUI share absent→present appear semantics and discard late callbacks after cancellation.
• KMP commonMain APIs compile for JVM and iOS, run lifecycle regression tests, and publish to Maven.

Protected delivery

• Manifest and module verification, immutable module URLs, same-origin policy, and first-install release floors.
• Temporary downloads, size/hash checks, VM preload, atomic activation, two-version history, and LKG fallback.
• Stable rollout buckets, emergency rollout stop, remote signer protocol, and JSONL audit.
• Linux ASan+UBSan, macOS UBSan, a libFuzzer package-parser entry point, and malicious-bytecode regression tests.

Quick start

Requirements

• CMake 3.16+
• Clang or GCC with C++17
• Python 3.9+
• OpenSSL 3

On macOS, the build probes Homebrew OpenSSL first. Elsewhere, set PVM_OPENSSL=/path/to/openssl when needed.

Run the complete desktop demo

make demo

The command creates development-only Ed25519 keys, builds the VM, compiles and publishes the sample DSL, starts a temporary module service, verifies and caches the signed module, renders the counter, processes an event, and persists state. A second run verifies the release and restores the previous state.

Build Android APK, AAB, and Runtime SDK

With JDK 17, Android SDK 36, and NDK 28.0.13004108 installed:

make android-demo-check

Artifact	Path	Purpose
Debug APK	dist/android/PVMRuntime-demo-debug.apk	Direct installation and integration
Debug AAB	dist/android/PVMRuntime-demo-debug.aab	Bundle packaging validation
R8 smoke APK	dist/android/PVMRuntime-demo-minified-smoke.apk	Non-debuggable R8/JNI device regression
Runtime AAR	dist/android/pvm-runtime-0.6.0.aar	Android runtime library
Maven repository	dist/android/maven/	com.protectedvm:pvm-runtime:0.6.0

The gate checks development signatures, API 36, both ABIs, embedded module/key/bootstrap consistency, tamper rejection, Maven/AAR consistency, APK ZIP alignment, and 16 KiB ELF PT_LOAD alignment.

Counter changes, asynchronous storage, and input values travel through native control → host → C++17 VM → native redraw; they are not static mocks. Android and HarmonyOS images are physical-device smoke evidence. The iOS image is simulator evidence. None replaces a complete production device matrix.

The development APK/AAB uses debug/test signing. A production app should consume the Maven/AAR, embed the module for its own platform/profile, and use its own application ID, public key, release floor, and production signing identity.

Build the iOS Runtime SDK and demo

On macOS with full Xcode:

make ios-sdk-check
make ios-demo-check
make ios-demo-run
make ios-demo-restore-check
make ios-demo-screenshot

Package.swift remains available for source development. The release gate builds dist/ios/PVMRuntime.xcframework, which contains the Swift Host, UIKit/SwiftUI renderers, CryptoKit verifier, Objective-C++ bridge, and C++17 VM. It validates device and simulator slices, stable Swift interfaces, iOS 15 deployment targets, a real binary Swift consumer, and the absence of private keys or local paths.

The repository includes PVMRuntimeDemo.xcodeproj. ios-demo-restore-check backgrounds the Demo through the Simulator system browser, verifies the SceneDelegate snapshot, terminates the process, and requires the relaunched VM-rendered state to match. Current evidence covers an iPhone 17 Pro Max Simulator on iOS 26.2. A target app still needs physical-device lifecycle, archive/codesign, entitlements, and App Store review evidence.

offline_sealed is the default recommendation for iOS. Any online bytecode delivery must be reviewed against the actual feature and Apple App Review Guideline 2.5.2. A signature or constrained VM does not itself guarantee store compliance.

Build HarmonyOS Runtime HAR and demo HAP

With DevEco Studio 6.1.1/API 24:

make harmony-sdk-check
make harmony-demo-run
make harmony-demo-screenshot

The gate builds an API 23-compatible Runtime HAR and unsigned Offline Sealed demo HAP with arm64-v8a/x86_64 C++17 Node-API, ArkTS host, ArkUI renderer, and module/key/bootstrap binding. Outputs are written to dist/harmony/.

For a physical device, use a Huawei-signed HAP and explicit target:

HARMONY_DEVICE_TARGET=your-device-id \
HARMONY_SIGNED_HAP=/path/to/huawei-debug-signed.hap \
make harmony-device-screenshot

Current physical evidence covers one HUAWEI Pura 70 on HarmonyOS 6.1 with API 23 compatibility. It is not commercial/AppGallery signing evidence.

Run release gates

make release-check

The aggregate includes end-to-end and security tests, host build checks, IDL and renderer conformance, bilingual documentation checks, the 3-platform × 4-profile delivery matrix, historical bytecode compatibility, sanitizers, fuzzing, and KMP compilation. Android, Xcode, and DevEco artifact gates remain separate because they require their respective SDKs.

KMP uses a project-local Gradle cache and does not clean caches belonging to other desktop projects:

make kmp-check
make kmp-packages

Run the module service

make bootstrap publish
PVM_ACTIVATION_TOKEN='replace-me' make serve

The service supports TLS 1.2+, token files, liveness/readiness, request IDs, security headers, timeouts, and container health checks. Development keys live under ignored server/var/keys/; production must use an isolated signer or HSM.

Repository layout

.
├── client/                  C++17 VM, C ABI, platform hosts, module stores
├── server/                  DSL compiler, signing, publication, module service
├── spec/                    Host IDL, renderer, and release-gate contracts
├── generated/               Generated C++/Kotlin/Swift/ArkTS host interfaces
├── tools/                   C++17/Qt Migration Studio
├── docs/                    Architecture, security, platform, DSL, operations
└── tests/                   End-to-end and security regression tests

Security boundary

PVM raises the cost of static analysis, tampering, and incorrect delivery. It does not claim absolute resistance to reverse engineering:

• A fully compromised device may observe bytecode or state during execution.
• Simultaneous loss of source, build chain, and all signing keys is out of scope.
• Authorization, pricing, entitlement, and anti-fraud decisions remain on a trusted server.
• A remote module cannot add undeclared permissions or deliver native code.

See Security model and Security policy.

Documentation

Document	Purpose
Documentation hub	Reading order, terminology, document map
Architecture	Trust planes, loading, state, updates
Security model	Threats, keys, controls, non-goals
DSL and bytecode	DSL semantics and PVBC v1–v5
Selective migration	Migrate selected classes or modules from an existing app
Migration Studio	Guided C++17/Qt migration, review, logs, and verification
Platform integration	Android, iOS, HarmonyOS, KMP
Operations	Build, publish, rollout, rollback, audit
Delivery status	Automated and external evidence
Functional status	Implemented and remaining work
Contributing	Issue-to-PR and review workflow

Every English Markdown document has a Simplified Chinese .zh-CN.md peer.

Maturity

The repository closes the compiler→signature→delivery→cache→VM→platform-host loop and has repeatable CI evidence. Production adoption still requires the target organization's KMS/HSM, account identities, commercial capability adapters, broader device labs, store review, payment sandbox, sustained fuzzing, red-team work, and performance SLOs. Treat Functional status and Delivery status as the source of truth.

License

PVM Runtime is licensed under the Apache License 2.0. Commercial use, modification, redistribution, and private use are permitted under its terms. Redistributions must preserve the required copyright and license notices, identify modified files, and retain any applicable NOTICE attributions.