feat(vz-backend): Phase 1 — scaffold elastos-vz crate (no Vz calls yet)

Per docs/vz-backend/PLAN.md Phase 1. Adds a new compute-provider
substrate for macOS that mirrors elastos-crosvm's public surface and
fails closed at every entry point. Phase 2 wires the actual
Apple Virtualization.framework calls.

New crate: elastos/crates/elastos-vz
  - VzProvider implements ComputeProvider; every method returns
    PHASE_1_STUB_MESSAGE ("vz backend not yet implemented (Phase 2)").
  - VzConfig + VmConfig mirror crosvm shapes minus pivot_root_dir.
    Boot-args helper rewrites `console=ttyS0` → `console=hvc0` per
    Phase 0 finding (Vz exposes the kernel console only as
    virtio-console).
  - NetworkConfig (macOS) + network_stub.rs (non-macOS) mirror the
    crosvm pattern; setup() fails closed in Phase 1.
  - RunningVm placeholder; start() fails closed, stop() is an
    idempotent no-op (matches crosvm semantics on already-stopped VMs).
  - src/ffi/ placeholder documents the Phase 2 fill-in (per-class
    wrappers for VZLinuxBootLoader, VZVirtioBlockDeviceConfiguration,
    VZVirtioSocketDeviceConfiguration, etc.).
  - objc2-virtualization 0.3.2 declared as a target-conditional dep
    (cfg(target_os = "macos") only). Not yet `use`d in any function
    body.
  - 27 unit tests + 10 smoke tests; cargo clippy clean.

Wired into elastos-server:
  - elastos-vz added as a platform-conditional dep
    (cfg(target_os = "macos") only). Linux build is byte-equivalent.
  - main.rs::create_runtime gets a SIBLING #[cfg(target_os = "macos")]
    registration block after the crosvm block. The crosvm block at
    L1862–L1876 is not touched.
  - supervisor.rs::launch_capsule cfg-gates the bail at L931:
      • Linux: identical behavior to pre-Vz commit.
      • macOS: fails closed with PHASE_1_STUB_MESSAGE so capsule
        launches surface the Phase status with a clear "Phase 2"
        marker rather than the (misleading) /dev/kvm message.
      • Other OS: bails with "no microVM substrate available".

Linux-untouched gate:
  - scripts/check-linux-untouched.sh diffs the four protected
    crates (elastos-crosvm, elastos-runtime, elastos-common,
    elastos-compute) against a base ref and fails non-zero on any
    modification. Verified clean against Phase 0 baseline (a65dad3).

Phase 1 prelude tool:
  - scripts/dev/mac-vz-feature-check/ — placeholder for the
    desk-research-confirming feature probe described in
    docs/vz-backend/PHASE_0_SCOPE.md appendix A. To be filled in
    Phase 1 Day 2 before Phase 2 begins.

Verification gates passed:
  - cargo build -p elastos-vz                (macOS)         ✅
  - cargo build --workspace                  (macOS)         ✅
  - cargo test  -p elastos-vz                (37 tests)      ✅
  - cargo clippy -p elastos-vz --all-targets (-D warnings)   ✅
  - cargo clippy -p elastos-server                            ✅
  - runtime start logs:
      "vz provider enabled (Apple Virtualization.framework
       available; Phase 1 stub — microVM launch fails closed)"
  - protected crates touched: 0

Three pre-existing setup.rs test failures (darwin-arm64 component
lookup) are inherited from Pre-Work commit 9fc4a7e and are not
introduced or worsened by this commit.

Linux behavior: byte-equivalent. Mac behavior: registration scaffolded,
launch path fail-closed with Phase 2 marker. No Vz API calls.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: SashaMIT

elastos/Cargo.lock

@@ -4,6 +4,7 @@ members = [
     "crates/elastos-storage",
     "crates/elastos-compute",
     "crates/elastos-crosvm",
+    "crates/elastos-vz",
     "crates/elastos-tls",
     "crates/elastos-identity",
     "crates/elastos-namespace",

elastos/Cargo.toml

@@ -97,6 +97,13 @@ futures-lite = "2.6"
 getrandom = "0.2"
 data-encoding = "2.6"
 
+# Apple Virtualization.framework substrate — only compiled into the
+# server on macOS hosts. On Linux/Windows the server keeps its
+# Linux/crosvm-only behaviour byte-for-byte. Anchored in
+# docs/vz-backend/PLAN.md (Linux-untouched gate).
+[target.'cfg(target_os = "macos")'.dependencies]
+elastos-vz = { path = "../elastos-vz" }
+
 [dev-dependencies]
 tokio = { version = "1.0", features = ["full", "test-util"] }
 tempfile = "3.10"

elastos/crates/elastos-server/Cargo.toml

@@ -1875,6 +1875,34 @@ pub(crate) async fn create_runtime(
         }
     }
 
+    // Add Apple Virtualization.framework provider on macOS. This is a
+    // SIBLING block to the crosvm registration above — it never
+    // executes on Linux (compiled out by `cfg(target_os = "macos")`)
+    // and the crosvm block above is byte-identical to the
+    // pre-Vz-backend commit. Per `docs/vz-backend/PLAN.md` Phase 1
+    // ("Linux-untouched gate"). Phase 1 wires the provider as a stub
+    // — every `load`/`start` call fails closed with the message in
+    // `elastos_vz::PHASE_1_STUB_MESSAGE`.
+    #[cfg(target_os = "macos")]
+    if elastos_vz::is_supported() {
+        match elastos_vz::VzProvider::new(elastos_vz::VzConfig::default()) {
+            Ok(provider) => {
+                if let Err(e) = provider.init().await {
+                    tracing::warn!("Failed to initialize vz provider: {}", e);
+                } else {
+                    tracing::info!(
+                        "vz provider enabled (Apple Virtualization.framework available; \
+                         Phase 1 stub — microVM launch fails closed)"
+                    );
+                    compute_providers.push(Arc::new(provider));
+                }
+            }
+            Err(e) => {
+                tracing::warn!("vz provider not available: {}", e);
+            }
+        }
+    }
+
     Ok(Runtime::with_providers(
         storage,
         compute_providers,

elastos/crates/elastos-server/src/main.rs

@@ -911,6 +911,19 @@ impl Supervisor {
     /// `config` is an opaque JSON payload from the CLI command. For the shell
     /// capsule, this contains the forwarded command (e.g. `{"command":"chat",...}`).
     /// It is base64-encoded and passed via the `elastos.command` kernel boot arg.
+    ///
+    /// **Linux:** the crosvm path below is the only substrate; behavior is
+    /// byte-identical to the pre-Vz-backend commit. **macOS:** the launch
+    /// path short-circuits at the substrate-check site below with a Phase 1
+    /// `vz backend not yet implemented` bail. Phase 2/3 (see
+    /// `docs/vz-backend/PLAN.md`) replace that bail with a real
+    /// `VzProvider.load(...)` route, at which point the rest of this
+    /// function body remains the Linux/crosvm-only code path.
+    ///
+    /// The `cfg_attr` below silences the expected `unreachable_code` warning
+    /// on macOS, where the Phase 1 bail makes the rest of the function dead
+    /// code. The warning is informational on Mac and a true error on Linux.
+    #[cfg_attr(not(target_os = "linux"), allow(unreachable_code, unused_variables))]
     async fn launch_capsule(&self, name: &str, config: serde_json::Value) -> Result<(String, u32)> {
         let (capsule_dir, manifest) = self.load_capsule_manifest(name).await?;
 
@@ -927,10 +940,42 @@ impl Supervisor {
                 .await;
         }
 
-        // VM path — hard require KVM
+        // VM path — hard require a microVM substrate.
+        //
+        // Linux: behavior is byte-identical to the pre-Vz-backend commit;
+        // crosvm is the only substrate, and `/dev/kvm` must be present.
+        //
+        // macOS: the Vz substrate is registered in main.rs but the
+        // per-VM launch path is not yet routed through it. Phase 1
+        // delivers scaffold only; Phase 2 wires `VzProvider.load(...)`
+        // and Phase 3 routes the supervisor through this site. Until
+        // then, fail closed with the same single-source-of-truth
+        // message used by VzProvider's stubs. See
+        // `docs/vz-backend/PLAN.md`.
+        //
+        // Other OS: no microVM substrate is available at all.
+        #[cfg(target_os = "linux")]
         if !elastos_crosvm::is_supported() {
             bail!("/dev/kvm not available — crosvm requires KVM. Cannot launch capsule '{name}'.");
         }
+
+        #[cfg(target_os = "macos")]
+        {
+            if !elastos_vz::is_supported() {
+                bail!(
+                    "Apple Virtualization.framework not available — cannot launch capsule '{name}' on this host. Requires macOS 12+ on Apple Silicon."
+                );
+            }
+            bail!(
+                "{} (supervisor: launch capsule '{}' on macOS not yet routed through Vz)",
+                elastos_vz::PHASE_1_STUB_MESSAGE,
+                name
+            );
+        }
+
+        #[cfg(not(any(target_os = "linux", target_os = "macos")))]
+        bail!("no microVM substrate available on this OS — cannot launch capsule '{name}'");
+
         self.crosvm_config.validate().map_err(|e| {
             anyhow::anyhow!(
                 "VM prerequisites missing: {}. Run `elastos setup --with crosvm --with vmlinux` \

elastos/crates/elastos-server/src/supervisor.rs

@@ -0,0 +1,36 @@
+[package]
+name = "elastos-vz"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+description = "ElastOS Apple Virtualization.framework Compute Provider — Run capsules in real microVMs on macOS (Phase 1: scaffold; no Vz API calls yet)"
+
+[dependencies]
+elastos-common = { path = "../elastos-common" }
+elastos-compute = { path = "../elastos-compute" }
+
+tokio = { version = "1.0", features = ["full", "process"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+uuid = { version = "1.0", features = ["v4"] }
+async-trait = "0.1"
+tracing = "0.1"
+thiserror = "1.0"
+libc = "0.2"
+
+# Apple Virtualization.framework bindings — fetched and linked ONLY on macOS.
+# On Linux the crate compiles as a stub (`is_supported()` returns false,
+# every entry point fails closed) so the workspace build stays green and
+# nothing is silently downgraded. The choice is anchored in
+# docs/vz-backend/PHASE_0_SCOPE.md §A. Phase 1 declares the dependency but
+# does not `use` it in any function body — actual Vz calls land in Phase 2.
+[target.'cfg(target_os = "macos")'.dependencies]
+objc2 = "0.6"
+objc2-virtualization = "0.3"
+objc2-foundation = "0.3"
+block2 = "0.6"
+dispatch2 = "0.3"
+
+[dev-dependencies]
+tokio = { version = "1.0", features = ["full", "test-util"] }
+tempfile = "3.10"