Sergey Antropoff
777926487b
initial QEMU slice, backed by imported contracts for majors 6–9. - Implement durable handlers for access/auth, cluster, LXC, storage, HA, firewall, Ceph, SDN, ACME, notifications, pools, mapping, and node ops - Serve an interactive Web UI with catalog browsing, demo seed controls, and OpenAPI/help surfaces - Bundle PVE 6.4-15, 7.4-16, and 8.4.5 contract revisions alongside 9.2.3 - Support in-memory runtime contract Apply (POST /ui/api/contract/apply) so /version and /api2 routes follow the selected major until restart - Expand seed profiles (including demo-cluster), migrations 007–008, TLS gateway config, Compose/Makefile tooling, and compatibility evidence - Tighten .gitignore for macOS, hidden directories (.*/), and local secrets
76 lines
2.8 KiB
Markdown
76 lines
2.8 KiB
Markdown
# 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).
|