Add a stateful Proxmox API console and broad handler coverage beyond the

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
2026-07-16 01:08:01 +03:00
parent 003ee5d634
commit 777926487b
189 changed files with 241501 additions and 944 deletions
@@ -0,0 +1,75 @@
+# 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).