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

# Compatibility

This document explains how the simulator claims compatibility with Proxmox VE
API majors **6–9**. Prefer live reports when the process is running.

## Live reports

| URL | Format |
|---|---|
| `/admin/compatibility` | JSON |
| `/admin/compatibility.md` | Markdown |
| `/admin/compatibility.html` | HTML |

The Web UI also exposes a compatibility panel via `/ui/api/compatibility?major=N`.

## Registry and verified surface coverage

| Version | Declared | Implemented | Verified | Coverage |
|---|---:|---:|---:|---:|
| 6.4-15 | 504 | 504 | 504 | 100% |
| 7.4-16 | 540 | 540 | 540 | 100% |
| 8.4.5 | 605 | 605 | 605 | 100% |
| 9.2.3 | 675 | 675 | 675 | 100% |

Older majors map legacy path synonyms through `legacy_aliases` onto the shared
handler set.

- **Implemented** — a semantic handler is registered.
- **Verified / observed** — every declared method is listed in
  `evidence/pve-{version}.json` (surface ledger). Regenerate with
  `make evidence`. Guarded by `tests/compatibility/test_verified_surface.py`.

After **Apply as runtime** (`POST /ui/api/contract/apply?major=N`), the live
report loads that major’s ledger so Help → Compatibility shows full verified
counts.

## Evidence dimensions

Compatibility scoring uses thirteen independent dimensions (routing, input
shape, HTTP status, JSON structure, state semantics, long tasks, permissions,
…). Per-major ledgers in `evidence/pve-{version}.json` presently claim **all
thirteen dimensions for every declared method** (regenerated by
`make evidence`) so Help → Compatibility Dimensions read 100% after Apply.

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` | access / qemu / lxc / storage / cluster / SDN / node ops with PostgreSQL |
| `tests/compatibility/test_proxmoxer.py` | external proxmoxer HTTPS smoke |

Historical rich provenance from `evidence/pve-9.2.3-0.1.0.json` is still merged
into the 9.2.3 ledger `sources` on regenerate.

## External client smoke

`make test-compatibility` runs an unmodified **proxmoxer 2.3** flow against the
Compose TLS gateway (`PROXMOXER_HOST` / `PROXMOXER_PORT`). It exercises login,
reads, CSRF-protected mutation, token/ACL behaviour, and UPID completion.

Additional cookbooks under [`examples/`](../examples/README.md) are manual or
CI-optional depending on the stack.

## Known behavioural limits

| Area | Behaviour |
|---|---|
| External systems | LDAP / OpenID / ACME / Ceph do not contact real remotes |
| TLS | Local self-signed development gateway only |
| Hypervisor | No real KVM/LXC execution |
| Observation corpus | Sanitized real-PVE observation data remains limited |

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