feat(vz-backend): Phase 2 Day 4 — codesign helper, vm-debug boot, first-boot attempt

Ship the local-dev codesign helper that bestows
`com.apple.security.virtualization` on a `cargo build`
`elastos` binary so Apple's `VZVirtualMachineConfiguration.validateWithError`
accepts it, unblocking the Day 3 lifecycle wiring. Add
`elastos vm-debug boot --rootfs … --kernel …` so a Mac dev can
drive the Day 3 path end-to-end (load → start → wait for Ctrl-C
or guest-stop → stop) and stream guest kernel printk to stdout
via the existing `vm_console` tracing target.

New files:
- scripts/dev/sign-elastos-vz/sign.sh — idempotent macOS-only
  ad-hoc signer (`codesign --force --sign - --entitlements …`).
  Refuses to run off macOS, verifies the entitlement landed
  before exiting 0, supports `--verify-only` for inspection.
- scripts/dev/sign-elastos-vz/vz.entitlements.plist — minimal
  entitlements plist granting one key:
  `com.apple.security.virtualization`. Single source of truth.
- scripts/dev/sign-elastos-vz/README.md — one-page operator
  guide: why, how, what NOT to expect (no notarization, no
  developer cert).
- elastos/crates/elastos-server/src/vm_debug_cmd.rs — clap
  `VmDebugCommand::Boot` handler. Validates inputs (rootfs +
  kernel exist, memory >= 64 MiB, vcpus >= 1), stages a
  tempdir capsule layout (hard-link rootfs in, fall back to
  copy), synthesises a minimal `CapsuleManifest` with the
  Vz-mandated boot args, calls `VzProvider::load`/`start`,
  races `tokio::signal::ctrl_c()` against polled
  `provider.status` so the CLI exits cleanly whether the user
  Ctrl-Cs or the guest halts itself. macOS-only impl; Linux
  fall-through returns a typed "see docs/MAC.md" error.
- docs/vz-backend/PHASE_2_DAY_4_NOTES.md — verbatim outcome
  log of the first-boot attempt on this dev machine.

Touched files:
- elastos/crates/elastos-server/src/main.rs —
  `Commands::VmDebug(VmDebugCommand)` added; dispatch arm hands
  off to `vm_debug_cmd::run`. The `EnvFilter` is widened by one
  additive directive (`vm_console=info`) so guest-kernel printk
  from BOTH the crosvm and Vz backends is visible without
  forcing operators to set `RUST_LOG`. `RUST_LOG` still
  overrides.
- docs/MAC.md — appends the "First boot on Apple Silicon"
  operator recipe and the kernel-artifact note.

End-to-end attempt on macOS 26.4.1 / Apple Silicon (full output
in PHASE_2_DAY_4_NOTES.md):

1. cargo build, sign, --verify-only — all clean.
2. `vm-debug boot` with stand-in artifacts reached
   `provider.load` and `provider.start` cleanly. Apple's Vz
   framework returned its expected "Internal Virtualization
   error. The virtual machine failed to start." because the
   stand-in kernel is 18 bytes. **Day 4 contract met: the
   wiring is end-to-end correct on a signed binary; only a
   real arm64 Linux Image + rootfs is missing for actual
   guest boot. That artifact procurement is Day 5.**
3. The Day 3 `ENTITLEMENT_HINT` message did NOT appear, which
   is the regression target — it should appear only on
   unsigned binaries. Apple Silicon's hard signing requirement
   means we can't easily run an unsigned binary on this host
   to verify the negative case, but the pure-string Day 3 unit
   tests (`format_validate_error_embeds_day_4_hint_…`) cover
   the contract deterministically.

Tests added (5; all pass locally):
- vm_debug_cmd::tests::validate_boot_inputs_rejects_missing_rootfs
- vm_debug_cmd::tests::validate_boot_inputs_rejects_missing_kernel
- vm_debug_cmd::tests::validate_boot_inputs_rejects_tiny_memory
- vm_debug_cmd::tests::validate_boot_inputs_rejects_zero_vcpus
- vm_debug_cmd::tests::build_staging_layout_creates_capsule_dir_with_entrypoint_rootfs

Plus one cfg-gated Linux-only test
(`vm_debug_boot_on_non_macos_returns_typed_error_pointing_at_docs`)
which CI will exercise.

Gates re-run locally:
- cargo build --workspace
- cargo test -p elastos-vz (69 green)
- cargo test -p elastos-server --bin elastos vm_debug (5 green)
- cargo clippy -p elastos-vz -p elastos-server --all-targets -- -D warnings
- cargo fmt --check
- scripts/check-linux-untouched.sh bcf5a0a (gate OK)
- scripts/dev/mac-vz-feature-check probe (still exit 0; validate
  line still SKIPs because the probe is its own unsigned binary)

Pre-existing failures in `elastos-server::setup::tests::*`
(3 tests around vmlinux platform-entry lookup for darwin-arm64)
are unrelated to Day 4 — verified by running them on the prior
commit (2994515) where they also fail. They belong to the
upstream darwin-runtime setup work, not the Vz backend, and
are outside this commit's scope.

Day 4 does NOT include:
- VZVirtualMachineDelegate (Day 5+)
- shipping a vmlinux artifact in the repo (kernel procurement
  is Day 5)
- production notarization / distribution signing (Phase 6)
- touching the four Linux-untouched protected crates

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

Author: SashaMIT

docs/MAC.md

@@ -140,9 +140,57 @@ trade-off.
   Linux host) and connect to it. This mirrors how Docker Desktop and
   the Kubernetes control plane handle the Mac case.
 
+## First boot on Apple Silicon (Phase 2 Day 4+)
+
+Once the Vz backend lands you'll be able to boot a Linux guest
+end-to-end against your own kernel + rootfs. The wiring is in
+place as of Phase 2 Day 4; the only remaining gap is "a real
+arm64 Linux kernel image that Apple's `VZLinuxBootLoader`
+accepts" — see [`vz-backend/PHASE_2_DAY_4_NOTES.md`](vz-backend/PHASE_2_DAY_4_NOTES.md)
+for the verified outcome of the Day 4 attempt.
+
+The operator recipe, once kernel artifacts are available:
+
+```bash
+# 1. Build the runtime binary.
+cargo build -p elastos-server
+
+# 2. Sign it with com.apple.security.virtualization so Apple's
+#    VZVirtualMachineConfiguration.validateWithError accepts the
+#    config. The script is idempotent — re-run after every
+#    `cargo build`.
+scripts/dev/sign-elastos-vz/sign.sh
+
+# 3. Boot the guest. The kernel must be a raw arm64 Linux Image
+#    (NOT a bzImage). The rootfs will be exposed as /dev/vda
+#    inside the guest. Guest kernel printk streams via the
+#    `vm_console` tracing target — visible by default.
+target/debug/elastos vm-debug boot \
+  --rootfs /path/to/rootfs.img \
+  --kernel /path/to/Image \
+  --memory-mb 256 \
+  --vcpus 1
+
+# Press Ctrl-C to stop. The VM also stops itself if the guest
+# shuts down.
+```
+
+If step 2 is skipped you'll see a single operator-friendly
+error string when `vm-debug boot` calls `provider.load`:
+
+> `vz validate (vm_id='…'): missing com.apple.security.virtualization entitlement — sign the binary with scripts/dev/sign-elastos-vz/ (Phase 2 Day 4) or see docs/MAC.md. Apple error: …`
+
+If the kernel artifact isn't a Vz-compatible arm64 Image, Apple
+returns `Internal Virtualization error. The virtual machine
+failed to start.` from `provider.start`. That's the signal you
+need a real kernel — Day 5 (and Phase 3 in `PLAN.md`) covers
+how to get one.
+
 ## Cross-references
 
 - The plan: [`docs/vz-backend/PLAN.md`](vz-backend/PLAN.md)
+- Day 4 outcome log: [`docs/vz-backend/PHASE_2_DAY_4_NOTES.md`](vz-backend/PHASE_2_DAY_4_NOTES.md)
+- Codesign helper: [`scripts/dev/sign-elastos-vz/README.md`](../scripts/dev/sign-elastos-vz/README.md)
 - The principles this plan obeys: [`PRINCIPLES.md`](../PRINCIPLES.md)
   (#10, #11, #12 in particular)
 - The runtime's support boundary: [`state.md`](../state.md)

docs/vz-backend/PHASE_2_DAY_4_NOTES.md

@@ -0,0 +1,137 @@
+# Phase 2 Day 4 — outcome log
+
+Operator-facing summary of what Day 4 actually achieved on real
+hardware. Single source of truth for "what works, what doesn't,
+what's next" so Day 5 can pick up without ambiguity. Companion
+to [`PLAN.md`](PLAN.md) (high-level phasing) and
+[`PHASE_0_SCOPE.md`](PHASE_0_SCOPE.md) (audit / risk register).
+
+## What this commit ships
+
+| Deliverable | Status |
+|---|---|
+| `scripts/dev/sign-elastos-vz/sign.sh` + `vz.entitlements.plist` + `README.md` | Done — ad-hoc signs the local `elastos` binary with `com.apple.security.virtualization`, idempotent, refuses to run off macOS |
+| `elastos vm-debug boot --rootfs … --kernel …` CLI subcommand | Done — `Commands::VmDebug` registered everywhere, real implementation gated to macOS, non-macOS returns typed "see docs/MAC.md" error |
+| `vm_console` tracing target opted into the default env filter | Done — single additive `add_directive("vm_console=info"…)` in `elastos-server/src/main.rs`; `RUST_LOG` still overrides |
+| End-to-end first boot attempt on this dev machine | **Attempted; outcome documented below** |
+
+## End-to-end attempt result
+
+**Host:** macOS 26.4.1 / aarch64 (Apple Silicon).
+
+**Procedure executed:**
+1. `cargo build -p elastos-server`
+2. `scripts/dev/sign-elastos-vz/sign.sh elastos/target/debug/elastos`
+3. `scripts/dev/sign-elastos-vz/sign.sh --verify-only elastos/target/debug/elastos` —
+   confirmed `com.apple.security.virtualization = true`.
+4. Created a stand-in 1 MiB zero-filled "rootfs" + an 18-byte
+   "kernel" stand-in (`/tmp/fake-rootfs.img`, `/tmp/fake-kernel.bin`).
+5. `elastos/target/debug/elastos vm-debug boot --rootfs /tmp/fake-rootfs.img --kernel /tmp/fake-kernel.bin --memory-mb 128`
+
+**Verbatim output:**
+
+```text
+vm-debug boot: loading capsule
+2026-05-22T06:42:40.529620Z  INFO elastos_vz::provider: Loaded MicroVM
+  capsule 'vm-debug-boot' with ID microvm-9c5055ad-cebe-4cbf-a49c-ad69945b0e63
+vm-debug boot: capsule loaded (microvm-9c5055ad-cebe-4cbf-a49c-ad69945b0e63); starting…
+Error: vm-debug boot: provider.start: Compute error:
+  vz start (vm_id='0d7f43ac-a550-454d-ade0-b58a73f7bb74'):
+  Internal Virtualization error. The virtual machine failed to start.
+```
+
+**Interpretation (line by line):**
+
+1. `vm-debug boot: loading capsule` — the CLI dispatch reached
+   `provider.load`. The staging-dir layout + manifest synth
+   worked end-to-end.
+2. `Loaded MicroVM capsule … ID microvm-…` — `VzProvider::load`
+   returned `Ok(CapsuleHandle)`. This implies all of:
+   - `ffi::builder::BuiltMachine::from_vm_config` accepted the
+     inputs (rootfs + kernel paths exist, sizing valid).
+   - `VZVirtualMachineConfiguration.validateWithError`
+     **succeeded** — the entitlement is real, the per-device
+     config the Day 2 builder produced is acceptable to Apple
+     for the host's macOS version, and the Day 1 probe's
+     extrapolation held.
+   - `VZVirtualMachine::initWithConfiguration:queue:` succeeded
+     — the per-provider GCD queue and the SendableVm wrapper
+     are correctly wired.
+3. `vz start (vm_id='…'): Internal Virtualization error. The
+   virtual machine failed to start.` — this is Apple's response
+   when it tries to actually boot the kernel image and finds
+   it isn't a valid Linux Image. **Expected** for an 18-byte
+   stand-in.
+
+**Conclusion.** The Phase 1–3 lifecycle wiring (validate →
+init → start → completion-handler block → Tokio oneshot →
+typed Rust error) is end-to-end functional on a signed Apple
+Silicon binary. The only thing Day 4 cannot verify is the
+actual guest boot, because we did not procure a real arm64
+Linux Image + matching rootfs.
+
+## What this rules out
+
+- ❌ Missing entitlement (would surface as the Day 3
+  `ENTITLEMENT_HINT` message; we don't see it).
+- ❌ Config-validation rejection (would surface from
+  `validateWithError` with a specific configuration error;
+  we don't see it).
+- ❌ GCD queue / dispatch wiring (the start call reached Apple
+  and Apple's framework reported back through our completion
+  handler).
+- ❌ FFI builder problem (the BuiltMachine assembled cleanly
+  for a config with both a kernel file and a rootfs file).
+
+## What's left for Day 5
+
+1. **Procure a Vz-compatible arm64 Linux kernel + minimal
+   rootfs.** Candidates ranked by effort:
+   - Apple's developer sample code under
+     `https://developer.apple.com/documentation/virtualization/running_linux_in_a_virtual_machine`
+     ships a known-working pair.
+   - Lima's published kernel + initramfs releases at
+     `https://github.com/lima-vm/alpine-lima/releases` are
+     reliable for arm64.
+   - Build from upstream: `arch/arm64/configs/defconfig` plus
+     `CONFIG_VIRTIO_BLK`, `CONFIG_VIRTIO_NET`, `CONFIG_HVC_DRIVER`,
+     `CONFIG_VIRTIO_CONSOLE` — see Phase 0 audit §C "kernel
+     config" for the full list.
+2. **First-boot acceptance test.** Run `vm-debug boot` against
+   the real artifacts; observe `vm_console` lines like
+   `[ 0.000000] Linux version …` reach stdout via the tracing
+   forwarder; clean Ctrl-C stop; verify no leftover state in
+   the tempdir.
+3. **VZVirtualMachineDelegate.** Once boot works, surface
+   guest-stop reasons and crash details via the delegate
+   protocol (Phase 0 §D pitfall #9; Day 3 deferred this).
+
+## Reproducing this attempt locally
+
+```bash
+# Sign the binary.
+cargo build -p elastos-server
+scripts/dev/sign-elastos-vz/sign.sh
+
+# Build stand-in artifacts so the "infrastructure works"
+# assertion is reproducible without a real kernel.
+dd if=/dev/zero of=/tmp/fake-rootfs.img bs=1M count=1
+echo "fake-kernel-bytes" > /tmp/fake-kernel.bin
+
+# Drive the lifecycle. Expected exit 1 with Apple's "Internal
+# Virtualization error" once we reach `provider.start`.
+target/debug/elastos vm-debug boot \
+  --rootfs /tmp/fake-rootfs.img \
+  --kernel /tmp/fake-kernel.bin \
+  --memory-mb 128
+```
+
+## Anchors
+
+- [`PLAN.md`](PLAN.md) — Phase 2 Day 4 in the phasing table
+- [`PHASE_0_SCOPE.md`](PHASE_0_SCOPE.md) §B, §D pitfalls #9, #10
+- [`scripts/dev/sign-elastos-vz/README.md`](../../scripts/dev/sign-elastos-vz/README.md)
+- [`docs/MAC.md`](../MAC.md) — operator recipe
+- `elastos-vz/src/ffi/lifecycle.rs::ENTITLEMENT_HINT` — the
+  string that does **not** appear in the Day 4 attempt above,
+  confirming the codesign path works

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

@@ -21,6 +21,7 @@ mod share_cmd;
 mod shares_cmd;
 mod site_cmd;
 mod trust_cmd;
+mod vm_debug_cmd;
 mod webspace_cmd;
 
 use clap::{Parser, Subcommand};
@@ -491,6 +492,12 @@ enum Commands {
         #[arg(long)]
         rollback_to: Option<String>,
     },
+
+    /// Developer entry point: drive the Apple Silicon Vz backend
+    /// directly. macOS only — see `docs/MAC.md` and
+    /// `docs/vz-backend/PLAN.md` (Phase 2 Day 4).
+    #[command(name = "vm-debug", subcommand)]
+    VmDebug(vm_debug_cmd::VmDebugCommand),
 }
 
 #[derive(Subcommand)]
@@ -1025,11 +1032,19 @@ async fn main() -> anyhow::Result<()> {
     let _ = rustls::crypto::ring::default_provider().install_default();
 
     // Initialize logging — uses ConditionalStderr so interactive VMs can suppress output.
+    //
+    // The extra `vm_console=info` directive opts the guest-kernel
+    // console target into the default filter so both the Linux
+    // (crosvm) and macOS (Vz) backends' `tracing::info!(target =
+    // "vm_console", …)` events are visible without forcing
+    // operators to set `RUST_LOG` by hand. `EnvFilter::from_default_env`
+    // still wins, so a user-provided `RUST_LOG` can override.
     tracing_subscriber::fmt()
         .with_writer(ConditionalStderr)
         .with_env_filter(
             tracing_subscriber::EnvFilter::from_default_env()
-                .add_directive("elastos=info".parse().expect("valid tracing directive")),
+                .add_directive("elastos=info".parse().expect("valid tracing directive"))
+                .add_directive("vm_console=info".parse().expect("valid tracing directive")),
         )
         .init();
 
@@ -1078,6 +1093,14 @@ async fn main() -> anyhow::Result<()> {
             return capsule_publish_cmd::run_publish(path).await;
         }
 
+        Commands::VmDebug(vm_debug) => {
+            // Phase 2 Day 4 (docs/vz-backend/PLAN.md). The
+            // subcommand itself decides whether the host is
+            // capable; here we just hand off so the typed error
+            // surface lives in one place.
+            return vm_debug_cmd::run(vm_debug).await;
+        }
+
         Commands::Share {
             path,
             channel,