# Support matrix

What each `i9` operation does on each host: what a test has shown to work,
what the binary refuses, and what nobody has tested.

For the verbs themselves, see the [CLI reference](cli.md). For how a host
differs in what it can capture, see
[How the /vm surface works](architecture.md#hosts-differ-in-what-they-can-do).

## How to read the cells

| Cell | Meaning |
|------|---------|
| **Verified** | A test or a recorded run of the published binary performed the operation on this host and checked the result. The basis follows in parentheses |
| **Refused** | The binary stops the operation on this host and prints the stated message |
| **Not verified** | No test and no recorded run has performed this operation on this host. It may work. Nothing published says it does |

A cell never reads Verified because the code looks right. Where the only
evidence is a run by hand rather than a scheduled test, the cell says so.

A recorded run is a run of the published binary on that host, with each
result checked and kept. It is not a scheduled test. Through MCP means the
operation ran through the matching `i9 mcp serve` tool.

## Operations by host

| Operation | Linux arm64 (KVM) | Linux x86_64 (KVM) | macOS Apple silicon (HVF) | Windows x86_64 (WHP) |
|-----------|-------------------|--------------------|---------------------------|----------------------|
| `i9 run` | Verified (release gate, nightly) | Verified (nightly through MCP; recorded run of the published binary) | Verified (daily first-contact run of the installer; recorded run of the published binary) | Verified (recorded run of the published binary, by hand) |
| `i9 vm exec` | Verified (release gate, nightly) | Verified (nightly through MCP; recorded run of the published binary) | Verified (daily first-contact run; recorded run of the published binary) | Verified (recorded run, by hand) |
| `i9 vm save` | Verified (release gate, nightly). Refused on a host without userfaultfd write-protect | Verified (nightly through MCP; recorded run of the published binary). Refused on a host without userfaultfd write-protect | Verified (recorded run of the published binary) | Verified (recorded run, by hand) |
| `i9 vm rewind` | Verified (release gate, nightly) | Verified (nightly through MCP; recorded run of the published binary) | Verified (recorded run): marker restored, guest clock advances | Verified (recorded run, by hand): the guest clock advances after the rewind |
| `i9 vm fork` | Verified (release gate, nightly) | Verified (nightly through MCP; recorded run of the published binary) | Verified (recorded run): the child sees the saved state, the parent keeps running, see below | Not verified |
| `i9 vm stop` | Verified (release gate, nightly) | Verified (nightly through MCP; recorded run of the published binary) | Verified (recorded run), including a fork child | Verified (recorded run, by hand): `--discard` is slow after a rewind, see below |
| `i9 vm cp` | Verified (release gate, nightly) | Verified (nightly through MCP; recorded run of the published binary) | Verified (recorded run) | Not verified |
| `i9 vm ports` | Verified (recorded run of the published binary): a host request through a published port is answered | Verified (nightly through MCP; recorded run of the published binary) | Verified (recorded run): a host request through a published port is answered | Not verified |
| `i9 mcp serve` with a running VM | Not verified. The tool table is tested without a guest | Verified (nightly, and on every change to the MCP surface) | Not verified | Not verified |

The nightly runs are scheduled tests of the public build. The release gate
holds a release back when its arm64 test fails.

## Refusals

| Situation | What the binary does | Exit status |
|-----------|----------------------|-------------|
| `i9 vm rewind` while the VM has live fork children | Refuses, names each child, and gives `i9 vm stop <child-url> --discard` as the way to free it | 6 (`EREFUSED`) |
| `i9 vm exec` or `i9 vm cp` on a paused VM | Refuses until `i9 vm resume` | 11 (`EVMPAUSED`) |
| `i9 vm exec` or `i9 vm cp` on a VM whose parent was restored or destroyed | Refuses; `i9 vm stop --discard` frees the slot | 12 (`EVMUNREACHABLE`) |
| `i9 vm exec` or `i9 vm cp` during an exclusive save or restore | Refuses; wait for the save or restore to finish, then run the command again | 13 (`EVMBUSY`) |
| `i9 vm save` on a Linux host whose kernel lacks userfaultfd write-protect | Refuses with `host_kernel_no_uffd_wp` rather than write an archive no machine can restore | Not verified |
| `i9 vm save` on Windows on Arm | The Windows on Arm backend restores snapshots and does not capture them | Not verified |

`i9 doctor` reports `can_run`, `can_restore` and `can_capture` for the
current host before any work depends on them. On a Linux host that can run
and restore but not capture, it says so in words.

Every exit status is defined in the [CLI reference](cli.md).

## Host notes

**Linux.** Running a guest needs a readable `/dev/kvm`. Capturing needs
`userfaultfd` with its write-protect feature in addition. A host without that
feature boots and restores normally and refuses `vm save`.

**macOS.** Hypervisor.framework permits one VM per process, so each
`i9 vm fork` child runs in a process of its own and the parent keeps
running beside it, as on Linux. A recorded run on an M4 Mac shows a parent
forked twice while its first child ran, each child seeing the parent's state
at its own fork, and eight concurrent forks of one parent all answering. No
scheduled test covers macOS forking.

**Windows x86_64.** The installer attaches your terminal to the guest.
Windows has no detached mode, so an agent drives the VM through an attached
terminal. The cells above come from a recorded run on Windows Server 2022
with the published `i9.exe`: run, exec, save, rewind, exec again, stop. No
scheduled test performs that sequence. Stopping a VM after a rewind can take
about ten minutes to return; this is a current limit of the Windows backend, not a refusal.

**Windows on Arm.** The backend restores an existing snapshot. It does not
capture one, and it has no cold boot of its own.

**Restoring on another host.** A snapshot restores on the machine that saved
it: its memory and disk are kept in that machine's snapshot store, so copying
the file to another host does not move it; `i9 snapshot export <snapshot> --out
<file>` writes a standalone copy that does. The published /vm image is
self-contained and restores on any host of its architecture that can restore.
The restore backend refuses a snapshot of another architecture. No test exercises that
refusal, so its message and exit status are Not verified.

**The CPU a snapshot needs.** A snapshot records the CPU features its guest
ran with. By default, a capture uses the portable profile of its host's
architecture, so it does not record every feature of the machine that saved it:

- On x86_64 the profile is `I9P1-X86`. A capture on an Intel host is clipped
  to the T2S feature set, and one on an AMD host to the T2A set.
- On arm64 it is `I9P1-ARM`, an Armv8.2 floor.

A snapshot restores on any host of the same architecture, and on x86_64 the
same CPU vendor, whose KVM offers the features the snapshot recorded. Moving a
snapshot between an Intel and an AMD host is not supported.

On a host below that floor, the restore is refused by the CPU-identity check,
which names each missing feature. `i9 run <snapshot>` then cold-boots the
snapshot's own image and disk instead, and says so: `restore of <image>
refused by the CPU-identity gate (this host is below the guest's floor);
cold-booting the same rootfs`. The files on the snapshot's disk are kept; the
guest's memory, meaning its running processes, is not.
