Commit Graph

14 Commits

Author SHA1 Message Date
kk0t9 02f13db1f3 docs(domain D): v2 — ретро-ревью pass-2 (9 находок) + кросс-док
- AEC (эхоподавление, loopback-ref из PipeWire) добавлен в пайплайн — нужен для
  wake-word во время воспроизведения и barge-in (был полностью пропущен)
- auto-fallback: v1 = online degradation UX, офлайн-фолбэк (llama.cpp) = v3 (раньше
  фолбэкать в v1 было некуда); offline-first (#3) в v1 частично, полный — v3
- инференс: ONNX (Silero) + Vosk через нативный Kaldi (не «всё через ONNX»)
- vehicle-context: контракт инъектора — только quality=valid, гейт по состоянию машины,
  ассистент декларирует vehicle_read через прокси; деградация на простых авто
- wake-word по состояниям питания (не безусловно always-on, риск разряда; Stage 2; гейт Power/B)
- distraction: owner Shell §7, скорость K(GPS v1)/E(OBD v2); журнал wake-word/mic
- кросс-док: tech-stack (Porcupine отвергнут), principles #3 (фазировка офлайн-диалога)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 01:25:11 +03:00
kk0t9 d112f5397d 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
kk0t9 64ef300ef4 docs(plugin-sdk): v2 — ретро-ревью (6 находок)
- версионирование: shturman_api ↔ набор D-Bus-мажоров; хост экспортирует все
  поддерживаемые мажоры параллельно; неподдерж. версия → Error.Unsupported (не тихо)
- IntentHandler: обязательный dispatch-таймаут; крэш/таймаут/NotAvailable →
  деградированный ответ (#4), пайплайн не виснет (#11)
- vehicle_read: per-vehicle Unavailable (Subscribe ок, SignalChanged молчит, плагин
  деградирует); install-ревью предупреждает о неподдерживаемых сигналах
- авторитет манифеста: extension_points.tiles авторитетны, ui_tiles — квота (len ≤ N)
- storage: квота (ENOSPC плагину не системе — бережёт /data), remove чистит, миграция
- lifecycle: discover/install только для сторонних; first-party — в base-образе, без install
- network host-allowlist приведён к best-effort (синхрон с security-privacy)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 01:02:43 +03:00
kk0t9 d9209987e4 docs(hardware): v2 — ретро-ревью (8 находок)
- ELM327 = software-дисциплина (полноценный CAN-узел, может TX); физический read-only
  инвариант только на нативном CAN в silent-режиме (уточнить architecture/sec-privacy §1)
- конверт входа по ISO 7637-2/16750-2: 9-16В, cold-crank ~6В, jump-start 24В, load-dump TVS
  (вместо размытого «40+В»); under-voltage brown-out + гистерезис → graceful shutdown
- hold-up как числовой контракт (ток×hold-time×дератинг −40°C/старение) + load-shedding
- §1a тепловой/механический конверт + темп-класс (industrial/AEC-Q100) + cold-start + охлаждение
- детект ACC кондиционированный: debounce + crank-приоритет (нет ложного shutdown на старте)
- контракт задней камеры (CVBS, reverse-сигнал, latency-бюджет #11, fail-safe), CAN front-end
  (трансивер/заземление/ESD/backfeed pin16), тир носителей /data (eMMC прод / SD dev)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 00:58:10 +03:00
kk0t9 3790715fc7 docs(security-privacy): v2 — ретро-ревью (10 находок)
- аудио per-node гейтинг (PipeWire Security Context + WirePlumber), не голый сокет:
  audio_out ≠ audio_in; capture только по runtime-гранту
- сеть: строгая гарантия только бинарно on/off; host-allowlist best-effort
  (DNS-allowlist обходится прямым IP — нужен forced-proxy по SNI/Host)
- якорь first-party не существует до v4: v0-v3 = trust-by-build/физконтроль
- целостность id при установке (отказ при коллизии; ru.shturman.plugin.* зарезервирован)
- жизненный цикл гранта: while-in-use, авто-снятие на stop/crash; enforce-split
  (статически прокси+sandbox/App-Host, рантайм-гранты Perm-Broker)
- НОВОЕ: §1a Модель угроз (адверсарии↔слои + out-of-scope)
- 152-ФЗ: явное отзываемое согласие (не только уведомление), минимизация VIN/локации,
  роли оператора/обработчика в BYO, локализация ≠ правовое основание
- audit-log промотирован в нормативный (владелец A §9 + UI домена C)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 00:55:15 +03:00
kk0t9 76596408e1 docs(data-model): ретро-ревью (5 находок)
- dtc_count диапазон 0..255 → 0..127 (поле 7-битное)
- добавлено runtime-поле quality (valid/stale/unavailable) + max_age, ортогонально
  статической availability (синхрон с ipc GetSignal/SignalChanged)
- §3: детект Mode 03/07/0A через trial-read (нет support-bitmask); пустой PID 0x00
  не каскадит «всё Unavailable»; MVP (mil_on + Mode 03) не зависит от пробинга
- убран ложный ярлык «SI» (km/h, rpm, °C — не СИ) → «канонический набор единиц»
- module_voltage: отметка, что property в ipc = ModuleVoltage

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 00:51:10 +03:00
kk0t9 2a9f9925cc docs(ipc): v2 — ретро-ревью (10 находок)
- enforcement: прокси даёт грубую изоляцию (сервис/метод), тонкую (per-signal,
  per-key) делает сам сервис по идентичности sender — прокси не видит payload
- PermBroker: идентичность только из соединения, CheckCapability(cap) sender-scoped
  (не принимает app аргументом → нет спуфинга); GrantChanged адресный
- НОВЫЙ сервис ru.shturman.Location (домен K) — GPS/положение; GPS-скорость не через E
- ошибки Stale/Timeout (транзиентно) vs NotAvailable (постоянно); GetSignal с таймаутом
- desired_max_hz = агрегатный hint (не per-subscriber троттл); подписки owner-bound,
  авто-снятие по NameOwnerChanged; quality-поле; BatteryVoltage→ModuleVoltage
- RegisterIntents(handler_path) — фразы из манифеста; версии-мажоры сосуществуют

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 00:49:41 +03:00
kk0t9 231a64300d docs(domain A): v2 после adversarial-ревью (24 находки) + кросс-док
Существенная переработка base-system по итогам multi-agent ревью:
- A/B-единица = весь boot-юнит (kernel+dtb+initramfs+rootfs) на слот; загрузчик вне A/B
- bootcount/bootlimit + mark-good (Shell-кадр) — иначе откат не срабатывает
- overlay upper/work на tmpfs; персист только через /data
- ФС /data: f2fs(рек)/ext4 + power-safe mount + durable-write (fsync/rename)
- at-rest шифрование /data (fscrypt, eFuse-bound, v4)
- watchdog: SoC+MCU разведены, вооружён в boot-окне, единственный владелец
- boot-порядок исправлен под architecture §6 (splash в Stage 0, ядро в Stage 1)
- secure boot = OTP-eFuse необратим + key-mgmt (не «мягкий переключатель»)
- НОВОЕ: время (RTC/NTP/GPS, TLS-gating), память (zram/OOM/cgroup), логи
  (journald volatile + критичное в /data + pstore), first-boot, factory-reset, локаль
- OTA: A=механизм/подпись, L=канал; verified-boot в бюджете boot; SD-тир; образ v0≠v4

Кросс-док: roadmap (образ v4 = флешируемый релиз), hardware (тепло/eMMC  резолв),
security-privacy (at-rest шифрование как открытый→направлен в A §3).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 21:12:35 +03:00
kk0t9 47d53d0956 docs(domain C): Shell/UX — спека + ревью-фиксы; cage→smithay
- спека домена C: композитор, слот-модель, декларативный UI-DSL (резолв вопроса),
  тема, driver-distraction, интеграция ассистента, ввод
- КОРРЕКЦИЯ: shell = кастомный multi-client композитор на smithay (Rust); cage
  (single-app kiosk) не годится для мульти-поверхностной слот-модели → правка
  в tech-stack и dev-environment
- ревью-де-риск v0: shell стартует как Slint-ап без внешних поверхностей, полный
  smithay-композитор — с первым surface-апом
- ревью-фазинг: статус машины в статус-баре → v2; distraction по GPS-скорости в v1
  (раньше OBD); день/ночь v0 по времени/GPS; настройки растут с фичами

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 20:53:05 +03:00
kk0t9 a8895ab99f docs(domain D): Assistant — спека + ревью-фиксы
- спека домена D: пайплайн (wake→VAD→STT→router→[локальные/LLM]→TTS, ONNX Runtime),
  функции (MVP/later), vehicle-context injection (killer), provider-agnostic LLM,
  интенты, память о водителе (.md), приватность
- ревью: openWakeWord вместо проприетарного Porcupine (принцип #12); мягкая
  деградация при нестабильной сети до офлайн-фолбэка; креды LLM — свои у пользователя;
  + контекст-размер, офлайн-STT в шуме, function-calling, обучение wake-word

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 20:45:20 +03:00
kk0t9 01119a4ccf docs(domain E): Vehicle-Data — спека + ревью-фиксы
- спека домена E по шаблону: назначение/границы, функции (MVP/later),
  данные/интерфейсы, зависимости, открытые вопросы, журнал решений
- MVP-ядро killer-фичи: MIL-статус (PID 01) + чтение DTC (Mode 03), универсально
- ревью: покрытие OBD-протоколов (не-CAN старые авто → ELM327 мульти-протокол),
  OBD-порт ≠ все шины, коалесцированный опрос, объём DTC-базы, ELM327-клоны, staleness

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 20:29:07 +03:00
kk0t9 fb27d8d2fe docs: завершить Tier 1 (контракты) + ревью-фикс red-line CAN
- security-privacy: изоляция, capabilities, гейтинг по каналам, приватность/152-ФЗ;
  first-party = вшит в подписанный образ; рисковые комбинации (vehicle_read+network)
- plugin-sdk: манифест, точки расширения, коллизия интентов, host-allowlist
- hardware: RK3588, power-safe, периферия, HAL/BSP портирование
- ВАЖНО: уточнён red-line CAN (принцип #2 + hardware §4): «чтение» = без
  управляющих/actuator/write-передач; диагностические OBD read-запросы допустимы
  (иначе не прочитать DTC); listen-only — только пассивный сниффинг
- + автозащита питания, тепло, износ eMMC; кросс-доковые аннотации

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 20:28:52 +03:00
kk0t9 3d13bb5827 docs: tech-stack + контракты ipc/data-model (+ ревью-фиксы)
- tech-stack: Rust-first (один прод-рантайм; Python — dev-only), полный стек, крейты
- architecture: ассистент Python→Rust для консистентности; boot-порядок
  (Broker+App-Host до Shell); потолок частоты сигналов ~10–20 Гц
- contracts/ipc: реестр D-Bus (сервисы ядра/апов, соглашения, портал-брокеринг)
  + открытые вопросы из self-review
- contracts/data-model: VSS-aligned каталог сигналов, OBD-PID маппинг, DTC-модель;
  добавлен MIL-статус (PID 0x01) для killer-фичи, состояние машины, расход-estimate

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 20:01:36 +03:00
kk0t9 9e685edd02 docs: заложить фундамент проектирования Штурмана
Каркас документации + содержательный фундамент (фаза проектирования,
реализация отложена):

- vision: видение, позиционирование, границы (вариант B, 2 красные линии)
- principles: 13 сквозных принципов (red lines, offline-first, power-safe…)
- architecture: тонкое ядро + SDK, planes, lifecycle, песочница, хостинг UI,
  карта связей + журнал из 6 решений
- dev-environment: разработка с Mac (Lima/ARM64, vcan, Vehicle Simulator)
- индексы contracts/ и domains/ (+ единый шаблон домена, заделы по камерам)
- заготовки glossary, capability-catalog, roadmap

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-20 19:28:16 +03:00