Initial commit: VMware vSphere API simulator scaffold.

Add the FastAPI app, PostgreSQL migrations, Docker/Helm packaging, API
contracts, docs, client examples, and the unit/integration/compatibility
test suite for local client and tooling labs without a real vCenter.

docs/ru/api-versions.md

@@ -0,0 +1,77 @@
+**Language / Язык:** [English](../api-versions.md) | [Русский](api-versions.md)
+
+# Версии API (vSphere catalog majors 6–9)
+
+Web UI и evidence/compatibility отчёты просматривают четыре целочисленных **catalog
+majors**, которые сопоставляются с label floors vSphere Automation API:
+
+| Major | Метка vSphere | Строка версии contract |
+|---|---|---|
+| 6 | 7.0 | `7.0.0` |
+| 7 | 7.0 U3 | `7.0.3` |
+| 8 | 8.0 | `8.0.0` |
+| 9 | 8.0 U2 (Automation 9.1 surface) | `8.0.2` |
+
+Определения находятся в [`app/vsphere/contracts/matrix.py`](../../app/vsphere/contracts/matrix.py)
+(`VERSIONS`, `PATH_FLOOR`). Каждый зарегистрированный REST path имеет **floor** —
+наименьший major, при котором он появляется в catalog — из того же
+модуля. Undated paths по умолчанию получают наивысший major (9), пока не catalogued.
+
+## Runtime vs catalog
+
+Это самое важное различие в проекте:
+
+- **Catalog major** — управляет тем, что показывает Web UI endpoint tree, `/ui/api/catalog`,
+  и compatibility/evidence отчёты для данного major.
+- **Runtime surface** — симулятор всегда обслуживает **полную зарегистрированную
+  route table** с deep handlers или DB-backed stubs, независимо от
+  активного catalog major. Известный path никогда не возвращается как HTTP 501 из-за
+  version floor.
+
+Hot-swap catalog major — это **documentation/browse**
+переключатель, а не compatibility gate для live traffic. См.
+[`available_for_request()`](../../app/vsphere/contracts/matrix.py) для точной
+политики.
+
+## Cold start
+
+`GET /api/appliance/system/version` сообщает version string текущего
+выбранного runtime source (по умолчанию `8.0.2` / major 9, если процесс не
+переопределяет `app.state.runtime_source_version`).
+
+## Hot-swap (catalog browse)
+
+Просматривайте любой major в Web UI catalog или вызывайте:
+
+```http
+POST /ui/api/contract/apply?major=7
+```
+
+Эффекты:
+
+- Web UI catalog, `/ui/api/compatibility` и evidence отчёты переключаются на
+  floor major 7 и ledger (`evidence/vsphere-7.0.3.json`).
+- Изменение **process-local** и **не сохраняется**; restart возвращает
+  default (major 9).
+- Зарегистрированные REST/SOAP routes продолжают отвечать своими реальными
+  handlers независимо от применённого major.
+
+### Рекомендации для клиентов
+
+- Большинству клиентов (pyvmomi, govmomi, Terraform, Pulumi, Ansible `uri`) не
+  нужно pin'ить catalog major — runtime surface не меняет форму
+  на его основе.
+- Используйте catalog majors, когда нужно, чтобы Web UI / evidence view
+  отражали более старую метку vSphere для документации или скриншотов.
+- После apply перепроверьте `/ui/api/compatibility?major=N` для активного
+  catalog state.
+
+## Регенерация catalog artifacts
+
+```bash
+make vsphere-bundles     # stub OpenAPI matrices + evidence ledgers
+make vsphere-universe    # regenerate universe.json from the Broadcom operations index
+make evidence            # regenerate per-major verified surface evidence ledgers
+```
+
+См. [Поверхность API](api-surface.md) и [Совместимость](compatibility.md).