docs(C-shell + кросс-док): ретро-ревью (6 находок) + синхронизация

C-shell v2: - GPS-скорость для distraction — домен K (ru.shturman.Location), не E (E это OBD, v2); E — уточнение OBD-скорости в v2 + быстрый статус машины - механизм поверхности: Wayland slot-протокол ru.shturman.shell_slot + slot-token, не «handle по D-Bus» - fail-safe distraction при потере/устаревании скорости (консервативный дефолт, гистерезис, арбитраж GPS/OBD) - контракт статус-бара: network «unknown» до Connectivity; часы — до синка времени Кросс-док: - architecture §1 (ELM327-оговорка к «физическому» read-only), §5 (положение/GPS из Location/K, не Vehicle-Data), §7 (Perm-Broker = грантодатель, статика — прокси+sandbox), §8 (surface через Wayland slot-протокол) - ipc Shell.RegisterScreen → slot_token - dev-environment: cage → smithay/weston в журнале и списке пакетов Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 01:06:05 +03:00
parent 64ef300ef4
commit d112f5397d
4 changed files with 43 additions and 15 deletions
@@ -20,7 +20,9 @@ capabilities). Это делает открытый API не лозунгом,
 Ключевое следствие для безопасности: к «опасным» ресурсам (CAN, питание)
 прикасается ровно один привилегированный сервис каждый. **Read-only CAN — не
 правило, а физический факт:** к шине машины прикасается только Vehicle-Data, и в
-нём нет write-кода.
+нём нет write-кода. *(Точнее: «физический» инвариант — для нативного CAN в silent-режиме;
+на старте через ELM327 read-only держится software-дисциплиной, т.к. ELM327 — полноценный
+CAN-узел. См. [contracts/hardware.md](contracts/hardware.md) §4.)*

 ---

@@ -111,7 +113,8 @@ dashcam-фронтальная, surround), расширяемый плагина
 | Assistant | Vehicle-Data | D-Bus | live-контекст машины в промпт |
 | Assistant | Connectivity → сеть | D-Bus/сеть | онлайн RU-LLM (GigaChat/YandexGPT) |
 | Assistant, Media, Phone | PipeWire | audio | микрофон, TTS, музыка, BT-аудио |
-| Nav, Shell | Vehicle-Data | D-Bus | скорость/положение для карты и виджетов |
+| Nav, Shell | Location (домен K) | D-Bus | GPS-положение/скорость (карта, distraction v1) |
+| Shell | Vehicle-Data | D-Bus | OBD-скорость (v2) + быстрый статус машины |
 | Nav, Media, камеры-виды | Wayland | graphics | богатые поверхности в слот shell |
 | Shell | все апы | D-Bus + Wayland | хостинг UI: декларативные вклады + поверхности |
 | все апы | Settings/State | D-Bus | чтение/запись настроек |
@@ -169,7 +172,7 @@ graph TD
 плагин не запишет в CAN — write-пути нет).

 - **Механизм:** апы/плагины — в **bubblewrap**-песочнице (namespaces, seccomp, минимальный FS); ядро — **systemd-hardening**. WASM — опциональный тир для лёгких логических плагинов позже.
- **Модель разрешений:** манифест декларирует capabilities (`vehicle_read:[…]`, `assistant_intents`, `ui_tiles`, `network`, `storage`…). **Perm-Broker — единственная дверь** к привилегиям (модель «порталов» как у Flatpak): плагин не трогает ресурсы напрямую, а просит брокера.
+- **Модель разрешений:** манифест декларирует capabilities (`vehicle_read:[…]`, `assistant_intents`, `ui_tiles`, `network`, `storage`…). **Perm-Broker — единый грантодатель/портал** (политика и рантайм-согласия), но **статическую** фильтрацию делает per-app D-Bus-прокси + bubblewrap (настраивает App-Host из манифеста) — не «брокер в каждом вызове». Детали — [contracts/security-privacy.md](contracts/security-privacy.md) §5.
 - **Грант:** first-party — авто; сторонние — показываем запрашиваемые capabilities при установке, пользователь подтверждает.

 Детали модели разрешений и приватности — [contracts/security-privacy.md](contracts/security-privacy.md).
@@ -186,7 +189,9 @@ Shell — Wayland-хост; апы/плагины — отдельные пес
  **сам shell** своими Slint-компонентами → единый стиль, безопасность (чужой код
  в процесс shell не пускаем).
 - **Wayland-поверхности** для богатых апов: нав-карта, медиа, камеры, GPU-тяжёлое.
-  Ап рисует у себя и отдаёт shell готовую поверхность.
+  Ап рисует у себя и подключается клиентом к **Wayland-сокету Shell**; привязка surface→слот —
+  через приватный **slot-протокол** (`ru.shturman.shell_slot`) + slot-token от
+  `Shell.RegisterScreen` (не «handle по D-Bus»). Детали — [domains/c-shell-ux.md](domains/c-shell-ux.md) §4.

 **Модель слотов:** shell задаёт слоты (грид home, полноэкранная зона, оверлей,
 статус-бар); ап вкладывает либо декларативный элемент, либо поверхность. Так
@@ -97,7 +97,7 @@
 - Контекст машины подмешивается ассистентом из `VehicleData` (см. architecture §5).

 ### `ru.shturman.Shell` — UX-host (слот-модель, решение №6)
- **Методы:** `RegisterTile(decl)`, `RegisterScreen(decl | surface_handle)`, `RequestForeground(slot)`, `ShowOverlay(decl)`.
+- **Методы:** `RegisterTile(decl)`, `RegisterScreen(decl) → slot_token` (для поверхности клиент предъявляет slot-token в Wayland slot-протоколе `ru.shturman.shell_slot`, не передаёт `wl_surface` по D-Bus — см. c-shell §4), `RequestForeground(slot)`, `ShowOverlay(decl)`.
 - **Сигналы:** `ForegroundChanged(app)`, `NavigatedTo(screen)`, `DistractionModeChanged(level)`.
 - Декларативный вклад = данные (рендерит shell); богатый = Wayland-поверхность.

@@ -91,7 +91,7 @@ ELM327-emulator. **Эталонный тест killer-фичи:** симулят
 ## Воспроизводимость

 - **Lima-шаблон** (`lima.yaml`): Ubuntu ARM64, модули (`vcan`), пакеты (systemd,
-  dbus, pipewire, cage, can-utils, rust, python).
+  dbus, pipewire, weston (вложенный композитор для dev), can-utils, rust, python).
 - **Provisioning-скрипт** + **`justfile`** с целями для подъёма/симуляции/тестов.
 - Минимальный порог входа для контрибьюторов.
 - **Nix** — опция *позже* для эталонно-пиннутого тулчейна (power-users), не сейчас.
@@ -126,7 +126,7 @@ GitHub Actions на ARM64-Linux-раннерах:
 | Решение | Выбор | Дата |
 |---------|-------|------|
 | Linux-окружение | Lima (vz-backend), ARM64, нативная виртуализация | 2026-06-16 |
-| Итерация UI | гибрид: нативный Slint на macOS + `cage` в VM | 2026-06-16 |
+| Итерация UI | гибрид: нативный Slint на macOS + shell-композитор (`smithay`, вложенно в `weston`) в VM; `cage` — только bring-up одного апа | 2026-06-16 |
 | Изоляция сервисов в dev | systemd-юниты + bubblewrap (зеркало прода) | 2026-06-16 |
 | Воспроизводимость | Lima-шаблон + provisioning + `justfile` (Nix — позже) | 2026-06-16 |
 | CI | GitHub Actions, ARM64-Linux | 2026-06-16 |
@@ -4,8 +4,8 @@
 > и в слоты которого встраивается UI всех апов/плагинов. v0-артефакт и главный
 > UX-дифференциатор («красиво и не лагает» против китайских блоков).

-Статус: **v1 (на ревью).**
-Связано с: [architecture.md](../architecture.md) (#6 хостинг UI) · [ipc.md](../contracts/ipc.md) (`Shell`) · [plugin-sdk.md](../contracts/plugin-sdk.md) (UI-вклад) · [tech-stack.md](../tech-stack.md) (Slint) · [security-privacy.md](../contracts/security-privacy.md) (consent UI) · [principles.md](../principles.md) (#6,#11) · домены D, E
+Статус: **v2 (на ревью).** v2 — после ретро-ревью (6 находок).
+Связано с: [architecture.md](../architecture.md) (#6 хостинг UI) · [ipc.md](../contracts/ipc.md) (`Shell`, `Location`) · [plugin-sdk.md](../contracts/plugin-sdk.md) (UI-вклад) · [tech-stack.md](../tech-stack.md) (Slint) · [security-privacy.md](../contracts/security-privacy.md) (consent UI) · [principles.md](../principles.md) (#6,#11) · домены D, E, **K (GPS/Location)**

 ---

@@ -41,21 +41,33 @@
 | Slint-shell: home/тайлы/настройки (без внешних поверхностей) | **MVP** | — | v0 |
 | Декларативный рендер тайлов/карточек | **MVP** | — | v0 |
 | Полный smithay-композитор (мульти-клиент) + слот-поверхности | later | — | с первым surface-апом (нав/медиа) |
-| Статус-бар: время, сеть | **MVP** | Connectivity | v0 |
+| Статус-бар: время, сеть (с initial «unknown») | **MVP** | Connectivity, время (a-base §7) | v0 |
 | Статус-бар: быстрый статус машины | later | E | v2 |
 | Анимации/переходы (полировка) | **MVP** | — | v0 |
 | Экран настроек (растёт: тема/единицы v0 → голос/LLM v1 → плагины v3) | **MVP** | Settings | v0+ |
 | Интеграция ассистента (PTT + лог диалога) | **MVP** | D | v1 |
-| Driver-distraction режим | **MVP** | GPS(speed)→E | v1 (GPS) / v2 (OBD) |
+| Driver-distraction режим | **MVP** | K (GPS speed) v1 / E (OBD speed) v2 | v1 / v2 |
 | Ввод с мультируля (кнопки руля) | later | K/E | v1/v2 |
 | UI управления разрешениями (review/revoke) | later | security-privacy | v3 |
 | Мультидисплей · профили водителей · виджеты | later | — | later |

+> **Статус-бар, начальный/деградированный контракт:** индикатор сети на первом кадре —
+> **«unknown»** (Connectivity не в Stage 1) → реактивно `GetStatus()`/`ConnectivityChanged`;
+> `Online` бинарный, «сервис не поднят» ≠ «offline» (не рисуем «offline» до первого ответа).
+> Часы: до синка времени (a-base §7) — пометка неопределённости/скрыть, не показывать
+> возможно-неверное cold-boot-значение.
+
 ## 4. Слот-модель (решение #6)

 Слоты: **home-грид**, **полноэкранная зона**, **оверлей** (ассистент/уведомления),
 **статус-бар**. Ап вкладывает в слот **декларативный элемент** или **Wayland-поверхность**.

+**Механизм поверхности (не «handle по D-Bus»):** ап подключается клиентом к **Wayland-сокету
+Shell** (его пробрасывает bubblewrap при `ui_*`, security-privacy §4) и создаёт там surface;
+привязка surface→слот — через приватный **Wayland slot-протокол** (`ru.shturman.shell_slot`),
+не по D-Bus. `RegisterScreen` по D-Bus возвращает **slot-token**, который клиент предъявляет
+в slot-протоколе; композитор сверяет peer-credentials сокета.
+
 ## 5. Декларативный UI-DSL *(резолв отложенного вопроса)*

 - **Констрейнт-набор, не произвольная вёрстка:** `tile` (icon/title/value/state/action),
@@ -72,9 +84,15 @@

 ## 7. Driver-distraction (принцип #6)

- Выше порога скорости → **упрощённый UI**, приоритет голосу, блокировка сложных
-  взаимодействий. Скорость — из **GPS уже в v1** (раньше, чем OBD), уточняется
-  OBD-скоростью (E) в v2. Конкретные пороги/что блокируется — в открытых вопросах.
+- Выше порога скорости → **упрощённый UI**, приоритет голосу, блокировка сложных взаимодействий.
+- **Источник скорости:** **GPS (домен K, `ru.shturman.Location`) уже в v1** (раньше OBD),
+  уточняется OBD-скоростью (E) в v2.
+- **Fail-safe при неизвестной/устаревшей скорости** (тоннель/нет фикса GPS, stale OBD — #3):
+  гейт по умолчанию в **консервативное состояние** (к безопасности), таймаут staleness +
+  видимая пометка «скорость неизвестна».
+- **Гистерезис/дебаунс:** раздельные пороги on/off, чтобы джиттер не мигал режимами.
+- **Арбитраж (v2):** правило GPS vs OBD (что авторитетно, поведение при расхождении/устаревании).
+- Конкретные числа порога и список блокируемого — в открытых вопросах.

 ## 8. Интеграция ассистента (D)

@@ -90,7 +108,8 @@

 - **Графика:** Wayland (smithay) + Panfrost/Mesa; **Slint** (tech-stack).
 - **Хостит:** UI апов/плагинов (App-Host их запускает; Shell композитит).
- **Данные:** E (speed для distraction, быстрый статус), D (ассистент-UI), Settings,
+- **Данные:** **K** (`ru.shturman.Location` — GPS-скорость для distraction v1, день/ночь-восход),
+  **E** (OBD-скорость уточнение v2 + быстрый статус машины), D (ассистент-UI), Settings,
  security-privacy (consent/permission UI), plugin-sdk (точки UI-вклада).

 ## 11. Открытые вопросы
@@ -100,6 +119,8 @@
 - ◻️ **UI управления разрешениями** (review/revoke) — из security-privacy. → этот домен + Settings.
 - ◻️ **Источник день/ночь** (время vs датчик освещённости vs сигнал машины). → реализация.
 - ◻️ **Мультидисплей, профили** — later.
+- ◻️ **Контракт Location/GPS (домен K)** — distraction v1 и день/ночь-восход гейтятся им; до K — мок-стаб (ipc `Location`).
+- 🟡 **Slot-протокол поверхностей** (`ru.shturman.shell_slot`: surface→слот, slot-token, peer-creds) — спроектировать (§4).

 ---

@@ -111,3 +132,5 @@
 | Хостинг UI | слот-модель: декларативный элемент (рендерит shell) или Wayland-поверхность | 2026-06-16 |
 | Декларативный DSL | констрейнт data-bound набор (tile/card/list/form); сложное → поверхность | 2026-06-16 |
 | Тема | день/ночь авто; токены | 2026-06-16 |
+| Скорость для distraction | GPS (домен K/`Location`) в v1, OBD (E) уточнение в v2; fail-safe при потере | 2026-06-16 |
+| Поверхности | через Wayland slot-протокол `ru.shturman.shell_slot` + slot-token, не «handle по D-Bus» | 2026-06-16 |