docs(macos): add MAC.md and Apple Vz backend plan; retire Slice B framing

Companion to the manifest revert in the previous commit. Documents the
truthful current macOS status and the named path to first-class
support.

Changes:

- docs/MAC.md (new): honest current Mac story — daemon code compiles
  and runs natively, WASM and data capsules work, MicroVM capsules
  require Linux and fail closed on Mac per PRINCIPLES.md #11. Includes
  the trust-delta disclosure (KVM + auditable crosvm vs Apple-signed
  Virtualization.framework) that the Vz backend cannot erase.

- docs/vz-backend/PLAN.md (new): canonical, repo-resident plan for the
  Apple Virtualization.framework backend (`elastos-vz` as a sibling
  crate to `elastos-crosvm`, implementing the same ComputeProvider
  trait). Includes:
  * "Linux untouched: explicit guarantees" — no edits to
    elastos-crosvm, no edits to the ComputeProvider trait, all Mac
    dispatch cfg-gated, CI gate enforcing the file-set
  * Hypervisor trust delta disclosure
  * Pre-Work + Phase 0–6 sequencing (~6–10 weeks)
  * Risk register including code-signing/notarization, entitlements,
    and the Linux-untouched gate

- docs/PC2_CONVERGENCE.md: Slice B framing (in-process / host-binary
  provider substitution on non-Linux) is marked superseded; the
  "Apple Hypervisor.framework substrate, out of scope, tracked
  separately" line is replaced with a pointer to vz-backend/PLAN.md;
  decision log gains a 2026-05-22 entry recording the switch.

- state.md: Support boundary section gains a fail-closed summary of
  the current Mac status, with cross-references to docs/MAC.md and
  docs/vz-backend/PLAN.md.

No code changes. No Linux behaviour change.

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

Author: SashaMIT

docs/MAC.md

@@ -0,0 +1,153 @@
+# macOS
+
+Honest current status of `elastos-runtime` on macOS, plus the named path
+to first-class support.
+
+> This document is the truthful Mac-side companion to
+> [`state.md`](../state.md) ("Support boundary"). If anything in this file
+> conflicts with the canonical [`PRINCIPLES.md`](../PRINCIPLES.md) or
+> [`state.md`](../state.md), those win.
+
+## TL;DR
+
+- The runtime daemon **compiles and runs natively on macOS** today (Apple
+  Silicon, `aarch64-apple-darwin`). Developers can build and iterate on
+  the daemon code without a Linux VM.
+- `WASM` and `data` capsules — for example `home`, `system`, `chat-room`,
+  `gba-emulator` — run natively on macOS with the same isolation
+  guarantees they have on Linux (wasmtime sandbox + capability tokens).
+- `MicroVM` capsules **do not yet run on macOS**. The repo refuses to
+  pretend otherwise: `elastos setup --list` will report
+  `[skip] <name> — not available for darwin-arm64` for any `type: microvm`
+  capsule. This is intentional fail-closed behaviour per
+  [`PRINCIPLES.md` #11 *Fail Closed, Then Explain*](../PRINCIPLES.md).
+- The named, scoped project that makes macOS a first-class ElastOS host
+  with **identical microVM isolation** to Linux is the **Apple
+  Virtualization.framework backend** ([`vz-backend/PLAN.md`](vz-backend/PLAN.md)).
+
+## What runs natively on macOS today
+
+| Capsule kind | Substrate | Status on Mac |
+|---|---|---|
+| `type: wasm` (e.g. `home`, `system`, `chat-room`) | wasmtime, capability tokens | Same as Linux |
+| `type: data` (e.g. `documents`, `library`, `inbox`, `gba-emulator`) | static assets, served by gateway | Same as Linux |
+| `type: microvm` (e.g. `chat`, `agent`, `localhost-provider`, `did-provider`, `shell`, `webspace-provider`, `ipfs-provider`, `tunnel-provider`, ...) | KVM + crosvm | **Not on macOS yet.** See "Path to first-class support" below. |
+
+The browser-hosted Home surface
+(`http://127.0.0.1:8090/apps/home/`) and its child apps (System, Inbox,
+Documents, Library, Chat Room, GBA) are reachable from macOS through
+`elastos gateway`. This matches [`state.md`](../state.md) L88: *"The
+default Home path must remain a KVM-independent browser-hosted adapter
+so macOS and Windows stay in scope without pretending to offer Linux
+parity."*
+
+## Why MicroVM capsules don't run on Mac yet
+
+ElastOS's central security thesis — *every `type: microvm` capsule in
+its own hardware-isolated microVM, communicating only through Carrier
+with explicit capability tokens* — is true on Linux via KVM + the
+[`elastos-crosvm`](../elastos/crates/elastos-crosvm/) crate. KVM is a
+Linux-kernel feature; macOS does not have it.
+
+The runtime preserves that contract by failing closed when the
+substrate is missing, rather than silently swapping to a weaker
+isolation model. The supervisor explicitly checks:
+
+```rust
+// elastos/crates/elastos-server/src/supervisor.rs (L930)
+if !elastos_crosvm::is_supported() {
+    bail!("/dev/kvm not available — crosvm requires KVM. Cannot launch capsule '{name}'.");
+}
+```
+
+That is the truthful, principled answer on Mac today: *the substrate is
+not available, so the capsule will not run.* Not a downgrade.
+
+> **Note on Slice B (commits `a02045e`, `a229638`, `d623ba7`):** an
+> earlier exploratory branch added darwin entries to
+> [`components.json`](../components.json) for `shell`,
+> `localhost-provider`, `did-provider`, and `webspace-provider`. Those
+> entries were misleading — they implied "this `type: microvm` capsule
+> runs natively on Mac" while in fact the runtime was launching them as
+> plain host-binary subprocesses without microVM isolation. The
+> Pre-Work step of [`vz-backend/PLAN.md`](vz-backend/PLAN.md) removes
+> those entries so the manifest tells the truth. The daemon-portability
+> improvements from those same commits (`pid_is_alive`,
+> `ELASTOS_DATA_DIR`, smoke-script Bash 3.2 portability, the
+> [`elastos-crosvm`](../elastos/crates/elastos-crosvm/) `cfg`-gated
+> non-Linux build) are preserved — they are universally-good
+> portability work and do not touch the Linux microVM substrate.
+
+## Path to first-class support
+
+The named, scoped project is the **Apple Virtualization.framework
+backend**. Read the full plan in
+[`vz-backend/PLAN.md`](vz-backend/PLAN.md). Headlines:
+
+- **Strategy.** Add `elastos-vz` as a *sibling* crate to
+  [`elastos-crosvm`](../elastos/crates/elastos-crosvm/), implementing
+  the same
+  [`ComputeProvider` trait](../elastos/crates/elastos-compute/src/traits.rs)
+  on top of Apple's `Virtualization.framework`. No edits to
+  [`elastos-crosvm`](../elastos/crates/elastos-crosvm/). No edits to
+  the trait. No edits to the capsules. No edits to Carrier. No edits to
+  the capability-token plane. Linux execution path byte-equivalent to
+  pre-change.
+- **End state.** Every `type: microvm` capsule artifact that runs on
+  Linux runs on Mac with **identical hardware-enforced isolation,
+  identical Carrier semantics, identical capability tokens, identical
+  fail-closed behaviour**. The capsule itself does not know it is on
+  Mac.
+- **Effort.** 6–10 weeks for one focused systems-Rust engineer, phased
+  Pre-Work → Phase 0 (1 wk research) → Phase 1 (scaffold) → Phase 2
+  (first guest boot) → Phase 3 (virtio plumbing) → Phase 4 (first
+  capsule end-to-end) → Phase 5 (hardening) → Phase 6 (ship).
+
+## Honest trust delta
+
+For [`PRINCIPLES.md` #12 *Docs, Code, Tests, and Ops Must Agree*](../PRINCIPLES.md),
+the one honest difference between Linux and macOS isolation that the
+Vz backend does *not* erase:
+
+|  | Linux today | macOS after Vz backend |
+|---|---|---|
+| Hardware isolation | CPU virt extensions (VT-x / SVM / ARM EL2) | CPU virt extensions (Apple Silicon EL2) |
+| Hypervisor | [`elastos-crosvm`](../elastos/crates/elastos-crosvm/) — open source, auditable, vendored | Apple `Virtualization.framework` — closed source, signed and shipped with macOS |
+| Trust source | We audit crosvm | We trust Apple's signed binary |
+| Integrity verification | Implicit (distro packaging) | Apple System Integrity Protection + binary code signing |
+
+**Net:** hardware-level isolation parity is full. The trust *source*
+differs. This is the same trade-off Docker Desktop, OrbStack, Lima,
+Tart, and every Mac-targeting VMM accepts. We disclose the delta
+honestly; we do not paper over it.
+
+The capability-token plane, the Carrier transport, the capsule
+artifact, and the fail-closed semantics are **unchanged** by this
+trade-off.
+
+## What this means for users today
+
+- **You can develop the daemon code on a Mac.** `cargo build` and
+  `cargo test` work. The daemon process runs, gateway serves the
+  browser Home, WASM and data capsules execute.
+- **You cannot run microVM capsules on a Mac.** Until the Vz backend
+  lands, install of any `type: microvm` capsule will be skipped with a
+  clear "not available for darwin-arm64" message. To run the full
+  microVM-isolated ElastOS today, use Linux (`x86_64-linux` or
+  `aarch64-linux`).
+- **If you need to test microVM capsules from a Mac**, run the runtime
+  inside a Linux VM (Lima, Apple Vz-managed manually, or a remote
+  Linux host) and connect to it. This mirrors how Docker Desktop and
+  the Kubernetes control plane handle the Mac case.
+
+## Cross-references
+
+- The plan: [`docs/vz-backend/PLAN.md`](vz-backend/PLAN.md)
+- The principles this plan obeys: [`PRINCIPLES.md`](../PRINCIPLES.md)
+  (#10, #11, #12 in particular)
+- The runtime's support boundary: [`state.md`](../state.md)
+  ("Support boundary" section)
+- The convergence context with PC2/Home:
+  [`docs/PC2_CONVERGENCE.md`](PC2_CONVERGENCE.md)
+- The Linux microVM substrate (untouched by this work):
+  [`elastos/crates/elastos-crosvm/`](../elastos/crates/elastos-crosvm/)

docs/PC2_CONVERGENCE.md

@@ -173,7 +173,39 @@ unchanged.
 
 ### Slice B — Critical providers available on non-Linux (Layer 2)
 
-**Status:** scope concretized; implementation open.
+> **Superseded (2026-05-22).** The original framing of Slice B —
+> *make MicroVM-typed providers available on non-Linux as in-process /
+> host-binary substitutes* — has been retired. After the exploratory
+> attempt landed in commit `a02045e`, review against
+> [`PRINCIPLES.md` #10 *One Canonical Path* and #11 *Fail Closed, Then
+> Explain*](../PRINCIPLES.md) concluded that running a `type: microvm`
+> capsule as an unsandboxed host subprocess on Mac silently downgrades
+> the isolation contract those capsules declare. The principled path is
+> to give Mac a real microVM substrate, not a soft alternate.
+>
+> **The replacement project is the Apple Virtualization.framework
+> backend** — [`docs/vz-backend/PLAN.md`](vz-backend/PLAN.md). It adds
+> `elastos-vz` as a sibling crate to
+> [`elastos-crosvm`](../elastos/crates/elastos-crosvm/) implementing the
+> same
+> [`ComputeProvider` trait](../elastos/crates/elastos-compute/src/traits.rs)
+> on Apple Vz. Linux code untouched; Mac gains identical hardware-isolated
+> microVM execution.
+>
+> **Pre-Work for that plan has reverted the misleading darwin entries**
+> added to [`components.json`](../components.json) in `a02045e` for
+> `shell`, `localhost-provider`, `did-provider`, and `webspace-provider`.
+> The daemon-portability improvements from the same commits
+> (`pid_is_alive`, `ELASTOS_DATA_DIR`, smoke-script Bash 3.2 portability,
+> the `elastos-crosvm` `cfg`-gated non-Linux build, the `darwin-arm64`
+> platform identity, and the universal-platform demo-capsule installs
+> `chat-room` / `gba-emulator` / `gba-ucity`) are kept — they do not
+> touch the Linux microVM substrate.
+>
+> The original Slice B prose below is preserved for historical context.
+
+**Status:** ~~scope concretized; implementation open.~~ Superseded — see
+[`vz-backend/PLAN.md`](vz-backend/PLAN.md).
 
 **Smallest shippable slice:** make `localhost-provider` available as an
 **in-process provider** on non-Linux. The runtime already registers
@@ -228,8 +260,10 @@ itself once; substrate selection is a runtime-policy detail bound to
   attributable.
 - A WASM substrate variant of these providers. Possibly correct
   long-term, but bigger than Layer 2. Layer 2 should not block on it.
-- An Apple Hypervisor.framework substrate. Out of scope here; tracked
-  separately.
+- ~~An Apple Hypervisor.framework substrate. Out of scope here; tracked
+  separately.~~ — now the **named replacement** for this slice's
+  intent. See [`vz-backend/PLAN.md`](vz-backend/PLAN.md). Apple
+  `Virtualization.framework`, not the older `Hypervisor.framework`.
 
 ### Slice C — Platform identity on macOS
 
@@ -332,9 +366,12 @@ ships until its gate passes.
 10. **Launcher Slice 2 + 3** as the underlying capsule and registry
     contracts harden
 
-Apple Hypervisor.framework substrate, dedicated browser capsule, and
-deeper Puter-derived UI deprecation are explicitly later. They should
-not distort the immediate sequence above.
+The Apple Virtualization.framework backend
+([`vz-backend/PLAN.md`](vz-backend/PLAN.md)) is the named replacement
+for Slice B's intent; its sequencing is owned by that plan and runs
+independently of the launcher slices above. Dedicated browser capsule
+and deeper Puter-derived UI deprecation are explicitly later. They
+should not distort the immediate sequence above.
 
 ## Decision Log Stub
 
@@ -347,3 +384,14 @@ Track decisions here when they pin down a previously open choice.
   `localhost-provider` only, not WASM-substrate provider rework.
   Driver: matches existing `documents-provider` in-process mechanism,
   fewer new concepts.
+- **2026-05-22** — Slice B retired in favour of a native Apple
+  Virtualization.framework backend ([`vz-backend/PLAN.md`](vz-backend/PLAN.md)).
+  Driver: running a `type: microvm` capsule as an unsandboxed host
+  subprocess violates [`PRINCIPLES.md` #10 and #11](../PRINCIPLES.md);
+  the principled fix is a real microVM substrate on Mac, not a soft
+  alternate. The Vz backend gives Mac identical hardware-enforced
+  isolation to Linux/KVM while leaving the
+  [`elastos-crosvm`](../elastos/crates/elastos-crosvm/) Linux code path
+  untouched. Pre-Work reverts the misleading darwin entries in
+  [`components.json`](../components.json) added by `a02045e`; the
+  daemon-portability improvements from that commit chain are kept.