**Language / Язык:** [English](compatibility.md) | [Русский](ru/compatibility.md)

# Compatibility

This document explains how the simulator claims compatibility with the
vSphere Automation API across catalog majors **6–9**. Prefer live reports
when the process is running.

## Live reports

| URL | Format |
|---|---|
| `/ui/api/compatibility?major=N` | JSON |

The Web UI also exposes a compatibility panel driven by this endpoint.

## Registry vs verified surface coverage

| Major | vSphere label | Implemented / universe | Coverage |
|---|---|---:|---:|
| 6 | 7.0 | 31 / 1077 | 2.9% |
| 7 | 7.0 U3 | 77 / 1077 | 7.2% |
| 8 | 8.0 | 103 / 1077 | 9.6% |
| 9 | 8.0 U2 (Automation 9.1 surface) | **1077 / 1077** | **100%** |

- **Universe** — unique verb+path routes derived from the public
  [vSphere Automation API operations index](https://developer.broadcom.com/xapis/vsphere-automation-api/latest/operation-index/)
  (1348 documented operations → ~1037 unique routes → 1077 registered in this
  simulator's route table, since some paths back multiple named operations).
- **Implemented (per major)** — routes whose catalog floor
  (`app/vsphere/contracts/matrix.py`) is at or below that major. This is a
  **catalog/documentation** score, not a live-traffic gate.
- **Runtime** — regardless of the applied catalog major, every registered
  route is always served by its real handler (104 deep handlers) or the
  DB-backed stub surface. See [API surface](api-surface.md).

After **Apply as runtime** (`POST /ui/api/contract/apply?major=N`), the live
report loads that major's ledger (`evidence/vsphere-{version}.json`) so the
Web UI compatibility panel reflects the selected major.

## Evidence dimensions

Per-major ledgers in `evidence/vsphere-{version}.json` record `declared`,
`implemented`, `observed`, and `verified` counts plus per-HTTP-verb and
per-domain (`auth_session`, `inventory`, …) breakdowns. Regenerate with:

```bash
make evidence          # app/evidence_gen.py
make vsphere-bundles   # stub OpenAPI matrices + evidence ledgers together
```

Executable backing for those claims:

| Suite | Role |
|---|---|
| `tests/compatibility/test_verified_surface.py` | hot-swap + ledger drift + score gates |
| `tests/compatibility/test_group_smoke.py` | representative REST group mutations with PostgreSQL |
| `tests/compatibility/test_vsphere_pyvmomi.py` | external pyvmomi SOAP smoke |
| `tests/integration/test_vsphere_full_api.py` | broad REST/SOAP integration coverage |

Additional cookbooks under [`examples/`](../examples/README.md) and the
`pulumi-vsphere` lab suite under [`pulumi-tests/`](../pulumi-tests/README.md)
(`make pulumi-tests`) are manual or CI-optional depending on the stack.

### Latest lab run (2026-07-18)

| Suite | Result |
|---|---|
| `make test` (offline) | **161 passed** |
| `make test-vsphere` (pytest + surface/matrix/dump/nonempty) | **73** pytest passed; probes **0 failures** (Terraform cookbook binary mismatch only) |
| `make pulumi-tests` (full hybrid) | **7 / 7 passed**; Layer A REST **1987 / 1987**, `critical=0` |

Details and report paths: [`pulumi-tests/README.md`](../pulumi-tests/README.md#latest-lab-run-2026-07-18).

## Known behavioural limits

| Area | Behaviour |
|---|---|
| External systems | NSX Manager, live LDAP/SAML/OIDC IdPs, and ACME directories do not contact real remotes; seeded/local state only |
| TLS | Local self-signed development gateway only (Compose); use your own certs / cert-manager for real deployments |
| Hypervisor | No real ESXi/KVM execution; no binary NFC uploads |
| Observation corpus | Sanitized real-vCenter observation data remains limited; deep semantic parity is verified path-by-path via the suites above, not by exhaustive production diffing |

Historical release notes: [compatibility-0.1.0.md](compatibility-0.1.0.md).