Initial commit: Fabrilis docs, rules and deterministic core

Docs (architecture, decisions, coupling, determinism, UI, references), code rules enforced by tools/limits, deterministic core with units, time, math, sched, snapshot, vec and rng, plus smoke tests. ref/ stays out of git.
This commit is contained in:
Loki 2026-11-16 19:09:10 +01:00
commit 878d144b77
221 changed files with 5316 additions and 0 deletions

81
docs/ARCHITECTURE.md Normal file
View file

@ -0,0 +1,81 @@
# Архитектура
## Принципы
- Cargo workspace из маленьких crate'ов. Симуляция — чистый Rust без GPU и без Bevy.
- Зависимости идут только вниз. Подсистемы друг о друге не знают; их соединяют
`bridge` и планировщик из `core`.
- Одно приложение, три режима — пресеты `Fidelity` (см. MODES.md).
- Рендер только читает снимок состояния и не влияет на симуляцию.
## Слои и crate'ы
| Слой | Crate | Роль | Зависит от |
|---|---|---|---|
| Ядро | `core` | СИ-единицы, время (u64 нс), планировщик, Fidelity, снимки, `math`, `vec` (Vec3/Mat3/Quat/Transform) | — |
| | `platform` | топология P/E-ядер, GPU, бенчмарки, регулятор | core |
| | `storage` | форматы, миграции, blob по хешу, папка проекта | core |
| Данные | `materials` | материалы, масса/инерция по мешу, прочность | core |
| | `scene` | сцена и конструкция, импорт мешей | core, materials, storage |
| | `parts` | библиотека деталей (данные + плагины), BOM | core, materials, scene |
| Физика | `physics` | трейт `PhysicsBackend`, Rapier, шарниры, трение | core |
| | `structure` | балки, FEM, напряжения, разрушение | core, materials |
| | `thermal` | тепло, вентиляция | core, materials |
| | `aero` | аэродинамика, ветер | core |
| | `actuators` | мышцы, серво, моторы | core |
| Электроника | `analog` | MNA-решатель схем | core |
| | `wiring` | жгуты проводов | core, analog, thermal |
| | `cpu` | трейт `Cpu`, RISC-V (потом arm/avr) | core |
| | `soc` | шина, периферия, device tree, virtio | core, cpu |
| | `sensors` | IMU, энкодеры, токовые датчики, модели шума и задержки | core |
| | `bridge` | пины ↔ схема ↔ приводы ↔ физика | core, soc, analog, actuators, physics |
| Мир | `worldgen` | шум, высотная карта, чанки | core |
| Верх | `scripting` | Rhai, сценарии опытов | core |
| | `analysis` | описания опытов, развёрток, Monte Carlo и метрик устойчивости; исполняет их `app` через трейт `Experiment` | core |
| | `modes` | Bench / Lab / World | почти все |
| | `render` | wgpu: clipmap, инстансинг, режимы вида | core |
| | `ui` | свой immediate-mode UI на нашем рендере: редактор, инспектор, графики, event-driven redraw | core, render |
| | `app` | winit, главный цикл | core, platform, storage, modes, render, ui |
## Поток данных за такт
1. Планировщик (`core::sched`) делит время на эпохи по наибольшему периоду.
2. Внутри эпохи подсистемы делают свои шаги с фиксированным порядком; шаг режется
ближайшим событием из очереди (COUPLING.md).
3. Обмен только в точках синхронизации через `bridge` (защёлкнутые значения);
сильные связи решаются совместно, а не запаздыванием.
4. В конце эпохи пишется `Snapshot`: набор подснимков, по одному от подсистемы.
5. `render` и `ui` читают снимок; `storage` сохраняет по запросу.
`analysis` не запускает симуляцию сам: он описывает опыт (параметры, seeds,
проверки) и метрики, а прогон выполняет `app` через трейт `Experiment`. Иначе
`analysis` пришлось бы тянуть вверх все подсистемы и получить цикл слоёв.
## Бюджет производительности
Эталонная сцена — паук: 24 тела, 32 шарнира, 8 аналоговых узлов, 12 датчиков,
физика 1 кГц. Цель — RTF ≥ 1 на машине с RX 470 (AMD, 2016) при 60 кадрах.
Бюджет такта World: 0.5 мс на физику, 0.2 мс на электронику и датчики, остальное
на подготовку снимка. Бюджет проверяется бенчмарком в CI; выход за него — повод
переходить на `ash` (D24) или упрощать World, но не менять шаг.
## Адаптация под устройство
`platform` определяет ядра (P/E), SIMD, RAM, GPU и кеширует профиль. Адаптируется
только то, что не влияет на результат: число потоков, раскладка по ядрам, качество
рендера, место culling. Модели (Fidelity) от железа не зависят. Подробно: DETERMINISM.md.
## Расширяемость
Новая деталь = данные (RON) + при необходимости плагин с трейтом из `parts::plugin`.
Ядро править не нужно.
## Структура репозитория
```
fabrilis/
├── Cargo.toml, rustfmt.toml, clippy.toml, rust-toolchain.toml, LICENSE (MIT), TODO.md
├── docs/ документация (не подпадает под правила кода)
├── crates/ 24 crate'а симуляции, рендера и приложения
├── tools/limits/ проверка правил (CODE_RULES.md), вызывается из build.rs
├── tools/measure_deps.py замер веса кандидатов в зависимости
├── examples/ эталонные конструкции (первый: мех-паук)
├── ref/ клоны чужих проектов для чтения (gitignored, не проверяются)
├── .githooks/ pre-commit: правила, fmt, clippy
└── .github/ CI на Linux, Windows, macOS
```
Слои зависимостей закодированы в `tools/limits/src/rules/layers.rs`; новый crate
нужно внести туда, иначе сборка падает.

108
docs/CODE_RULES.md Normal file
View file

@ -0,0 +1,108 @@
# Правила кода
Правила проверяются автоматически, а не на честном слове. Главный инструмент —
crate `tools/limits` (`fabrilis-limits`). У каждого crate'а есть `build.rs`, который
вызывает его, поэтому **нарушение жёсткого правила ломает любую сборку**
(`cargo build`, `check`, `clippy`, `test`). Весь репозиторий проверяется командой
`cargo run -p fabrilis-limits`; она же стоит в pre-commit (`.githooks/`) и в CI.
Правила касаются только нашего кода. `docs/`, `*.md` и `ref/` (локальные клоны
чужих проектов, см. REFERENCES.md) не проверяются.
## Проверяет `fabrilis-limits` (ошибка сборки)
| Правило | Подробности |
|---|---|
| Размер файла | больше **350** строк — предупреждение, больше **500** — ошибка; на тестовые файлы не распространяется |
| Файлов в директории | не больше **4** файлов кода (`.rs`, `.wgsl`, `.rhai`, `.sh`) в одной директории, и так в каждой директории отдельно, на любой глубине; подпапки в счёт не идут, тестовые файлы не считаются |
| Комментарии на английском | кириллица в `//`, `///`, `//!`, `/* */` запрещена; строки и литералы не проверяются |
| Без маркеров работы | `TODO`, `FIXME`, `HACK`, `XXX` в комментариях запрещены; открытая работа живёт в `TODO.md` |
| Тесты отдельно от кода | см. ниже |
| Без файлов-свалок | имена `utils`, `util`, `helpers`, `helper`, `common`, `misc`, `stuff`, `shared` для файлов и папок запрещены: файл называется по тому, что в нём лежит |
| Слои crate'ов | зависимости идут только вниз; симуляция не зависит от `render`, `ui`, `app`; новый crate нужно внести в таблицу `tools/limits/src/rules/layers.rs`, иначе сборка падает |
### Тесты отдельно от кода
В файле с кодом нет ни одного теста: ни `#[test]`, ни `#[cfg(test)] mod x { ... }`,
ни `#[cfg(test)]`-хелперов. Допустимо только:
- **модульные тесты:** в коде одна строка `#[cfg(test)] mod tests;`, а сами тесты лежат
в `tests.rs` той же директории (`foo/mod.rs` → `foo/tests.rs`, `foo/bar.rs` → тоже
`foo/tests.rs`);
- **интеграционные тесты и бенчи:** папки `tests/` и `benches/` в crate'е;
- общие помощники для тестов лежат в `tests/<имя>/mod.rs` (не `common`).
Тестовые файлы (`tests.rs`, всё в `tests/` и `benches/`) **не считаются** в лимит
четырёх файлов на директорию и **не ограничены** по размеру: один `tests.rs` может
быть длинным. Разносить тесты по подпапкам ради лимитов не нужно — весь модуль
тестируется одним файлом рядом.
## Проверяют rustfmt и clippy (pre-commit и CI с `-D warnings`)
| Правило | Чем задано |
|---|---|
| Отступы только табами | `rustfmt.toml`: `hard_tabs = true` |
| `unsafe` запрещён | `Cargo.toml`: `unsafe_code = "deny"` |
| Детерминизм: нет `sin/cos/exp/pow` из `std`, `HashMap/HashSet`, `Instant::now`, `SystemTime::now` | `clippy.toml`: `disallowed-methods`, `disallowed-types`; `platform` и `app` могут разрешить время точечно |
| Нет `unwrap`, `expect`, `panic!`, `todo!`, `unimplemented!`, `dbg!` в обычном коде | `Cargo.toml`: lints; в тестах разрешено (`clippy.toml`) |
| Индексация только с доказанной границей | см. «Паники и индексация» |
| Функция не длиннее 60 строк, не больше 5 аргументов, сложность ≤ 15 | `clippy.toml`: пороги |
| Каждое `#[allow]` объясняется: `#[allow(lint, reason = "...")]` | `allow_attributes_without_reason` |
Исключения оформляются точечно, с причиной, и не на весь crate без необходимости.
### Паники и индексация
`unwrap`, `expect`, `panic!`, `todo!`, `unimplemented!` и `dbg!` в библиотечном
коде запрещены, в тестах разрешены. Индексация (`v[i]`) паникует сама, и линтер её
не ловит, поэтому: **индексировать можно только там, где граница доказана
структурой** — фиксированный массив, срез, полученный в этой же функции с
проверкой, индекс из конструктора. Иначе — итераторы, `get`, `chunks`.
Паника допустима лишь как утверждение «сюда нельзя попасть» в месте, куда данные
из файла или из сети не доходят; в тестах это проверяется отдельным тестом.
### Лимиты и как их держать
Списка исключений для файлов кода нет: если файл упирается в лимит, он делится на
подмодули по смыслу. Декодер RISC-V, MNA-матрица и FEM собираются из маленьких
модулей (по шагам ISA, по типам элементов, по решателям), а не из одного
«большого» файла. Если подпапки не помогают, это повод пересмотреть структуру,
а не завести исключение.
Лимит четырёх файлов действует на каждую директорию независимо: в `src/` может
лежать 4 файла и 6 подпапок, и в каждой подпапке снова 4 файла и свои подпапки,
без ограничения глубины. Тесты в этот счёт не входят, поэтому `mod.rs`, три
модуля и `tests.rs` — это нормальная директория, а не пять файлов.
### Dev-зависимости
`proptest` и `criterion` разрешены как dev-зависимости (D26): в продуктовую
сборку они не входят. Свои тесты на seeded `core::rng` остаются основой, потому
что тот же генератор нужен Monte Carlo.
## Принципы
- **KISS**: самое простое решение, которое работает; без заглушек «на будущее».
- **DRY**: одно знание — одно место (device tree из карты памяти, единицы в `core`).
- **SOLID**: один модуль — одна причина меняться; зависимости через трейты
(`PhysicsBackend`, `Cpu`, `Device`); зависимости только вниз по слоям.
## Правила проекта (проверяются ревью)
- В движке нет кода под конкретную конструкцию: всё через данные, детали-плагины и
сценарии; конструкции лежат в `examples/`.
- Crate'ы симуляции не зависят от GPU, окна и Bevy.
- Единицы СИ через newtype из `core::units`, без голых `f64` в публичных API физики.
- Новая внешняя зависимость обосновывается записью в `DECISIONS.md` (мы пишем своё,
где это разумно).
- Архитектурное изменение сопровождается записью в `DECISIONS.md`.
## Идеи на потом (пока не включены)
Каждый пункт можно включить отдельным шагом, когда проект дорастёт.
| Идея | Зачем |
|---|---|
| `cargo-deny` (лицензии, уязвимости, дубли версий, запрещённые crate'ы) | гигиена зависимостей |
| `cargo-machete` | неиспользуемые зависимости |
| `missing_docs`, `missing_errors_doc`, `missing_panics_doc` для нижних слоёв | документированный публичный API |
| Касты `cast_possible_truncation`, `cast_precision_loss` в crate'ах симуляции | потеря точности между `u64` нс и `f64` |
| `float_cmp`: сравнение `f64` через допуск, а не `==` | корректная численная логика |
| Фаззинг (`cargo-fuzz`) для импорта мешей, форматов RON, декодера RISC-V | парсеры устойчивы к мусору |
| Мутационное тестирование (`cargo-mutants`) и покрытие (`cargo-llvm-cov`) для `core`, `analog`, `cpu` | тесты реально ловят ошибки |
| Порог регрессии бенчмарков в CI (своя утилита замеров) | скорость не падает незаметно |
| Conventional Commits и `commit-msg` хук | читаемая история |
| Проверка, что каждый crate описан в `ARCHITECTURE.md` | документация не отстаёт |
| Лимит на число `unsafe`-блоков и место (только `cpu`, с обоснованием) | контроль рисков |

37
docs/COORDINATES.md Normal file
View file

@ -0,0 +1,37 @@
# Системы координат и единицы
## Мировая система
Правая, Z вверх, X вперёд, Y влево (как в робототехнике, ROS REP-103). Единицы СИ.
Углы в радианах (`Radians`); градусы только в интерфейсе и при импорте.
## Системы
| Система | Назначение |
|---|---|
| world | неподвижная система мира |
| body | связана с деталью; для инерции начало в центре масс |
| joint | ось шарнира направлена вдоль локальной Z |
| sensor | датчик, задаётся преобразованием от body |
| render | только для рендера, получается в конце цепочки |
Преобразования это `Transform` (кватернион и вектор, f64). Сцена хранит цепочку как
граф; матрицы для рендера собираются в конце.
## Вращения
Единичные кватернионы с контролем дрейфа нормы. Углы Эйлера только для ввода и
вывода. Нормализация около нуля и вырожденные матрицы обрабатываются явно: ошибка,
а не NaN.
## Импорт: единицы и оси
| Формат | Единицы | Оси | Политика |
|---|---|---|---|
| STL | не заданы | не заданы | проект задаёт единицы (по умолчанию мм) |
| OBJ | не заданы | не заданы | проект задаёт единицы |
| glTF | метры | Y вверх, правая | оси пересчитываются в Z вверх |
Материалы: плотность в кг/м³, прочность в Па; в файлах материалов единицы указаны
явно суффиксом и конвертируются при импорте. Единицы источника записываются в
конструкцию.
## Большие миры
Симуляция в f64. Для рендера и f32-компонентов начало координат переносится (origin
rebasing).

46
docs/COUPLING.md Normal file
View file

@ -0,0 +1,46 @@
# Связь подсистем (co-simulation)
Типичная замкнутая цепь: МК выдаёт PWM, драйвер питает мотор, мотор двигает ногу,
нагрузка поднимает ток, ток просаживает питание и греет провод, нагрев меняет
сопротивление, и мотор теряет момент. Подсистемы считаются разными решателями, и
от способа обмена между ними зависит, будет ли поведение верным. Словарь заимствован
из стандарта FMI: master algorithm, communication step, event iteration, rollback.
## Классы связей
| Класс | Пример | Способ обмена |
|---|---|---|
| Односторонняя | физика → рендер; ток → нагрев провода (медленно) | снимок, без итераций |
| Слабая двусторонняя | МК ↔ периферия; температура ↔ сопротивление | обмен в точках синхронизации, запаздывание на шаг допустимо, значение удерживается (zero-order hold) |
| Сильная | мотор: напряжение, ток, обратная ЭДС, момент, скорость; контакт стопы с землёй | один решатель на всю связку или итерации внутри шага (Гаусс-Зейдель с релаксацией) и критерий сходимости |
Каждая связь в коде объявляется с классом. Сильные связи нельзя решать запаздыванием:
модель мотора живёт внутри аналогового решателя, а механическая нагрузка входит в неё
как состояние (момент, скорость) и обновляется на каждом аналоговом шаге.
## Контракт подсистемы
Входы, выходы, период, направление связи, допустимое запаздывание и поддержка отката
(`save` и `restore` состояния). Контракт проверяется при сборке сцены.
## События
Очередь событий с метками времени в нс: фронты PWM, прерывания МК, перегорание
предохранителя, обрыв провода. Событие делит шаг: аналоговый решатель ставит
breakpoint в момент события. Внутри эпохи события обрабатываются в порядке (время,
приоритет, номер подсистемы). Между событиями значения удерживаются; интерполяция
нужна только для вывода.
## Шаг и ошибка
Аналоговый шаг адаптивный и ограничен максимумом режима (Bench: 1 мкс, World: крупный
квант) и ближайшим событием. Если итерации сильной связи не сошлись, шаг делится
пополам и повторяется с отката. Если после N делений сходимости нет, это диагностика
в отчёт (VALIDATION.md), а не тихое продолжение.
## Снимок
Снимок состоит из подснимков подсистем, и каждая подсистема сама сериализует своё
состояние. Это нужно для отката шага, перемотки и сохранения.
## План внедрения
- Срез 1: слабые связи с запаздыванием на шаг и очередь событий.
- Срез 4 (электроника): сильные связи и откат шага.
## Открыто
Выбор коэффициента релаксации и предельного числа делений шага.

51
docs/DECISIONS.md Normal file
View file

@ -0,0 +1,51 @@
# Решения
| # | Решение | Почему |
|---|---|---|
| D1 | Multi-crate workspace, симуляция без GPU/Bevy | тесты без окна, CI, детерминизм |
| D2 | Без Bevy; свой рендер на wgpu (Vulkan); без общего ECS, данные SoA внутри crate'ов | RX 470 слабая, нужен контроль; рендер заменяем |
| D3 | Физика: гибрид. `PhysicsBackend` + `rapier3d-f64` с `enhanced-determinism` на старте, нужное заменяем своим | быстрый старт без потери контроля и без границы f32 |
| D4 | Механика: жёсткие тела + нагрузки на шарниры (World); балки и FEM (Lab); разрушение | точность там, где нужна |
| D5 | ISA: RISC-V первым (RV32IMAC, RV64GC), остальные через трейт `Cpu` | пользователь знает RISC-V, Linux, открытая ISA |
| D6 | Электроника в два слоя: цифровая эмуляция SoC + аналоговый MNA + bridge | запуск реального Linux/прошивок + реальное питание |
| D7 | Один бинарник, режимы Bench/Lab/World — пресеты Fidelity | один паук и детали во всех режимах |
| D8 | Детерминизм: целое время, свой `math`, порядок независим от потоков | воспроизводимость, перемотка, golden-тесты |
| D9 | Управление временем отдельно от Fidelity: dt не меняется | замедление ничего не огрубляет |
| D10 | Адаптация под железо: P/E-ядра, GPU только для неавторитетного | одинаковый результат у всех |
| D11 | Сохранения: папка проекта, RON, снимки отдельно, настройки в XDG | git-friendly, командная работа |
| D12 | Скрипты: Rhai | чистый Rust, песочница, без C-зависимостей |
| D13 | Лимиты: файл >350 строк — предупреждение, >500 — ошибка сборки; ≤4 файла кода в каждой директории (подпапки не считаются, вложенность любая). Тестовые файлы (`tests.rs`, `tests/`, `benches/`) не считаются и по размеру не ограничены | см. CODE_RULES.md |
| D14 | Террейн: высотная карта + clipmap, без вокселей; генерация на CPU | одна карта для рендера и коллайдеров |
| D15 | Деталь = данные + плагин; из конструкции экспортируется BOM | цель: собрать конструкцию в реальности |
| D16 | Цель проекта: универсальная платформа проектирования любых механизмов; паук — эталонный проект в `examples/`, в движке нет кода под него | расширяемость, любые будущие конструкции |
| D17 | Сценарии и анализ — часть ядра платформы: crate `analysis` (развёртки, Monte Carlo, метрики устойчивости, отказы) и `sensors` (IMU, энкодеры, шум) | проверка стабилизации и работы контроллеров |
| D18 | Правила репозитория проверяются кодом (`tools/limits` в `build.rs` каждого crate'а): размеры, комментарии на английском, тесты отдельно, слои crate'ов | нарушение ломает сборку, правила не держатся на дисциплине |
| D19 | Лицензия MIT: код можно брать и менять, но нужно сохранять упоминание авторов; правообладатель и автор: loki | простая разрешающая лицензия с обязательной атрибуцией |
| D20 | UI свой, на нашем рендере (прямоугольники, текст, виджеты, графики); egui и другие готовые UI-библиотеки не берём | пользователь их не любит; мы всё равно владеем рендером |
| D21 | Векторная математика своя в `core` (Vec3, Mat3, Quat, Transform на f64 через `core::math`); `glam` и `nalgebra` в симуляции не используем | детерминизм: их тригонометрия идёт через системный libm |
| D22 | Импорт мешей свой: STL и OBJ пишем сами, glTF сначала минимальным своим читателем | `gltf` тянет 37 crate'ов ради простого формата |
| D23 | Крупные зависимости: `wgpu`, `winit`, `rapier3d-f64`, `rhai` принимаем пока, остальное своё; `proptest` и `criterion` — только dev-зависимости (D26) | см. DEPENDENCIES.md |
| D24 | Рендер на `wgpu`; запасной вариант — `ash` (Vulkan напрямую). Переход, если сборка `wgpu` (61 crate) или размер станут проблемой | рендер скрыт за crate'ом `render`, замена не заденет симуляцию |
| D25 | Название проекта: Fabrilis (лат. fabrilis, «относящийся к мастеру, ремесленнику»); автор: loki; префикс crate'ов `fabrilis-` | свободно на crates.io; латынь по вкусу автора |
| D26 | `proptest` и `criterion` разрешены как dev-зависимости; основные тесты — свои на seeded `core::rng` | в продуктовую сборку dev-зависимости не входят, экономить на них незачем; свой генератор всё равно нужен для Monte Carlo |
| D27 | Этапы — вертикальные срезы с критерием готовности (DoD); каждая веха даёт демонстрируемый результат | горизонтальный план даёт годы без рабочего инструмента |
| D28 | Детерминизм в трёх уровнях: D1 повтор на машине, D2 при любом числе потоков, D3 на разных ОС и архитектурах. Авторитетная сборка — базовый `target-cpu`, SIMD только явными ядрами | честная граница гарантии вместо одного невыполнимого обещания |
| D29 | Шаг физики World — 1 кГц (1 мс); Bench и Lab не огрубляются, а замедляются | 250 Гц разъезжается по фазе с контактом стопы и жёстким шарниром |
| D30 | Проект публичный, но до 0.6.0 API плагинов и форматов нестабилен; обратная совместимость не обещается | ещё рано замораживать интерфейсы, а публичность задаёт планку документации |
| D31 | Углы — newtype `Radians`; градусы только в интерфейсе и при импорте | градусы и радианы иначе путаются молча |
| D32 | Очередь событий с метками в нс в планировщике: событие делит шаг подсистемы | фронты PWM и прерывания нельзя привязывать к эпохам |
| D33 | Версия компилятора зафиксирована `rust-toolchain.toml`; CI собирает базовую и `native` сборки и сверяет хеши | разные LLVM могут разойтись в последних битах |
| D34 | UI — свой immediate-mode слой на нашем `wgpu`-рендере с event-driven redraw; retained-дерево только по профилировке. ShapeUI blueprint — источник контрактов, не фундамент | редактору нужны панели, дерево и графики, а не окна произвольной формы; UI-фреймворк на годы остановил бы проект |
## Открытые вопросы
- FEM: тетраэдры для всей детали или балки + локальные тетраэдры в узлах.
- Модель разрушения: порог по напряжению, трещины, усталость.
- Воздушные потоки: сеть каналов (быстро) или CFD-lite (точно).
- Сходимость MNA: набор приёмов (gmin stepping, source stepping, breakpoints) и
предельное число делений шага.
- Коллизии: `parry` оставляем навсегда или пишем свой узкий слой после своего
физического backend'а.
- Когда переходить с `wgpu` на `ash` (D24): после M4 по времени сборки и RTF.
- Shaping и IME для текстовых полей: `cosmic-text` или `Parley`; решаем на M10.
- Нужен ли retained-слой UI: решаем по профилировке M10.
- Конкретная целевая плата и список реальных компонентов.

56
docs/DEPENDENCIES.md Normal file
View file

@ -0,0 +1,56 @@
# Зависимости
Правило: пишем своё, где это разумно; берём готовое, только когда оно отлично
работает и писать самим слишком дорого. Каждая внешняя зависимость обосновывается
записью в DECISIONS.md.
## Замеры (16.11.2026, версии по умолчанию из crates.io)
«Crate'ов на Linux» — зависимости, которые реально собираются на Linux.
Размер исходников и строки считаны для всех платформ (включая Windows и macOS),
поэтому завышены; для оценки скорости сборки смотри число crate'ов.
| Библиотека | Crate'ов на Linux | Исходники, МБ | Строк Rust | Решение |
|---|---|---|---|---|
| `libm` | 1 | 0.6 | 20 тыс. | берём (детерминированная математика) |
| `serde` | 7 | 4.2 | 119 тыс. | берём (форматы) |
| `ron` | 10 | 5.2 | 149 тыс. | берём (форматы сцен и конструкций) |
| `rayon` | 6 | 1.8 | 53 тыс. | берём позже (развёртки, Monte Carlo) |
| `fontdue` | 8 | 3.2 | 86 тыс. | берём для текста в своём UI; позже можно заменить своим растеризатором |
| `rhai` | 25 | 25.6 | 669 тыс. | берём (скрипты) |
| `rapier3d-f64` | 46 | 55.0 | 1757 тыс. | временно, пока не напишем свой backend (D3); вариант на f64 + `enhanced-determinism` |
| `wgpu` | 61 | 209.1 | 4163 тыс. | берём; самый тяжёлый, см. ниже |
| `winit` | 72 | 234.7 | 4163 тыс. | берём (окна и ввод на трёх ОС писать самим слишком дорого) |
| `gltf` | 37 | 19.3 | 541 тыс. | не берём сейчас: свой минимальный читатель; возьмём, только если glTF станет обязательным |
| `nalgebra` | 19 | 36.4 | 1289 тыс. | не берём в симуляции (свой `core::vec`) |
| `glam` | 1 | 6.4 | 250 тыс. | не берём в симуляции (свой `core::vec`) |
| `egui` | 54 | 35.1 | 944 тыс. | не берём (D20) |
| `proptest` | 26 | 54.5 | 1441 тыс. | dev-зависимость, берём для property-тестов (D26) |
| `criterion` | 51 | 166.7 | 1643 тыс. | dev-зависимость, берём для бенчмарков (D26) |
| `ash` (Vulkan напрямую) | 3 | 5.0 | 131 тыс. | запасной вариант вместо `wgpu` |
## Что пишем сами
Планировщик, единицы, векторная математика, эмулятор CPU и SoC, аналоговый
решатель, балки и FEM, тепло, аэродинамика, мышцы, мир, рендер-слой, UI, импорт
STL/OBJ и минимальный glTF, физический backend (после старта на Rapier).
## Тяжёлые, которые оставляем пока
- **`wgpu`** (61 crate): самый тяжёлый, но скрыт за crate'ом `render`. Если время
сборки или размер начнут мешать, переходим на `ash` (3 crate'а): придётся
написать свой менеджер памяти, swapchain и синхронизацию, а шейдеры
компилировать заранее. Минус `ash`: macOS только через MoltenVK.
- **`winit`** (72 crate'а): окна на Wayland, X11, Windows и macOS вручную — слишком
большая работа без пользы для цели проекта.
- **`rapier3d-f64`**: вариант Rapier на `f64` (тот же набор crate'ов) плюс фича
`enhanced-determinism`; нужен для быстрого старта и не вносит границу `f32`.
Авторитетные результаты со временем считает свой backend.
- **`rhai`**: заменить своим языком возможно, но это отдельный большой проект.
## UI
Свой UI на нашем рендере (D20, D34): immediate-mode список команд, панели, текст,
кнопки, ползунки, графики, дерево деталей, таблица свойств, окно 3D-вида, потом
редактор схем и жгутов. Растеризация шрифта через `fontdue`; shaping/IME для
текстовых полей — кандидаты `cosmic-text`/`Parley`, решение на M10 (UI.md).
Сначала оверлей отладки (M4), полноценный редактор в M10.
Отвергнуты: `egui` (не нравится), `iced` (тяжёлый), `slint` (лицензия GPL/коммерческая
несовместима с MIT), `xilem` (молодой). Blueprint ShapeUI — источник контрактов,
не фундамент (UI.md).

61
docs/DETERMINISM.md Normal file
View file

@ -0,0 +1,61 @@
# Детерминизм
Результат симуляции не зависит от железа, числа потоков и ОС. Без этого нет
воспроизводимых багов, перемотки и golden-тестов.
## Уровни гарантии
| Уровень | Что гарантирует | Где проверяется |
|---|---|---|
| **D1** | Повтор на той же машине, той же сборке, том же числе потоков даёт тот же результат | каждый коммит, golden-хеш |
| **D2** | То же при любом числе потоков | CI, прогон с 1, 2, 8 и 24 потоками |
| **D3** | Разные ОС и архитектуры (Linux x86-64, Windows, macOS ARM) дают одинаковый хеш | матрица CI, один хеш в репозитории |
D1 нужен для отладки, D2 — для параллельных развёрток, D3 — для «у меня не
воспроизводится». Гарантия относится только к авторитетному состоянию симуляции;
рендер, UI и отладочные счётчики в хеш не входят.
## Правила
1. **Время** — `u64` наносекунды, не float.
2. **Математика**: `+ − × ÷` и `sqrt` по IEEE 754 одинаковы везде. `sin`, `cos`,
`exp`, `pow` и т.п. из `std` вызывают системный libm, у которого результаты
различаются в последних битах. Поэтому в crate'ах симуляции они запрещены
(`clippy.toml`, `disallowed_methods`); вместо них `fabrilis_core::math` поверх
чистого Rust-`libm`.
3. **Нет fast-math**; `mul_add` использовать осознанно (результат одинаков, но на
части CPU медленнее).
4. **Потоки**: порядок обхода и редукции фиксированы, результат не зависит от
числа потоков. Разбиение на блоки зависит от данных, а не от числа ядер.
5. **Коллекции**: `HashMap/HashSet` запрещены (порядок обхода), берём `BTreeMap`
или индексированные структуры.
6. **RNG** только seeded, состояние входит в снимок.
7. **GPU** не участвует в авторитетной симуляции, только в рендере и визуальных
расчётах.
8. **Часы**: `Instant::now` и `SystemTime::now` запрещены в симуляции (`clippy.toml`);
время только `SimTime`. Исключения точечные: `platform` (бенчмарки) и `app`
(темп кадров).
9. **Векторы**: свои `Vec3`, `Mat3`, `Quat` в `core::vec` на `f64` через `core::math`
(`glam` и `nalgebra` считают тригонометрию через системный libm).
10. **Инструменты**: версия компилятора зафиксирована `rust-toolchain.toml`;
авторитетная сборка идёт с базовым `target-cpu` (без `native`), CI дополнительно
собирает с `native` и сверяет хеши.
11. **SIMD**: только явные ядра с фиксированным порядком операций. Обычная
автовекторизация допустима: она не меняет порядок сложений и не включает
fast-math. Ручные SIMD-ядра проверяются отдельным golden-тестом.
12. **Rhai** выполняет сценарии через `core::math`: `sin`, `cos`, `exp` и `pow`
движка отключены, иначе скрипт приносит системный libm в симуляцию.
## Rapier
Берём `rapier3d-f64` (вариант на `f64`) с фичей `enhanced-determinism`: границы
`f32` на стыке с нашей математикой нет. Пока Rapier в авторитетном пути, гарантия —
D1 и D2 для конкретной сборки; хеши физических сцен хранятся по платформе. D3 для
физики проверяем отдельно и обещаем только после своего backend'а
(`PhysicsBackend`), остальные подсистемы уже дают D3.
## Проверка
Golden-тест: хеш состояния после N тактов совпадает на Linux/Windows/macOS и при
1, 2, 8 и 24 потоках. Хеш хранится в репозитории. При расхождении CI печатает
первую подсистему, чей подснимок разошёлся (COUPLING.md).
## Адаптация под железо (`platform`)
Разрешено: раскладка потоков (критический путь на P-ядрах, фон на E-ядрах),
качество рендера, место culling. Запрещено: менять модели или шаг от устройства.

34
docs/ELECTRONICS.md Normal file
View file

@ -0,0 +1,34 @@
# Электроника
Цель: те же ELF-файлы, образы и драйверы, что и на реальном железе, без изменений.
## Цифровой слой
- `cpu`: трейт `Cpu` (`step(бюджет_тактов)`, `reset`, линии IRQ). Реализации:
RV32IMAC (микроконтроллеры), RV64GC с режимами M/S/U и MMU Sv39 (Linux).
Позже arm и avr через тот же трейт.
- Два режима выполнения: точный по тактам (Bench) и пачками (World).
- `soc`: шина с трейтом `Device` (чтение/запись по адресу, `tick`, IRQ), карта
памяти как данные, **device tree генерируется из неё**. Периферия: UART, GPIO,
I2C, SPI, PWM, ADC, таймеры, virtio (диск, консоль).
## Аналоговый слой
- `analog`: метод узловых потенциалов. Элемент добавляет «штамп» в матрицу.
Нелинейные элементы решаются Newton; сходимость обеспечивают gmin stepping,
source stepping и breakpoints. Шаг адаптивный, ограничен максимумом режима
(Bench и Lab 1 мкс, World 50 мкс) и ближайшим событием (COUPLING.md).
Если шаг не сходится после N делений, это диагностика в отчёт (VALIDATION.md),
а не тихое продолжение.
- Элементы: R, C, L, источники, диоды, транзисторы, батарея (с внутренним
сопротивлением), драйверы, датчики.
- `wiring` добавляет провода и разъёмы как элементы со связью с `thermal`.
## Мост (`bridge`)
- GPIO — источник напряжения с выходным сопротивлением.
- ADC читает напряжение узла; фронты PWM попадают в аналоговый шаг в точный момент.
- Мотор и мышца — сильная связь: модель мотора с обратной ЭДС живёт внутри
аналогового решателя, механическая нагрузка входит в неё как состояние и
обновляется на каждом аналоговом шаге (COUPLING.md). Слабое запаздывание на шаг
здесь недопустимо.
## Плата как данные
RON описывает SoC и подключённую схему. Образ прошивки хранится по хешу.

43
docs/MODES.md Normal file
View file

@ -0,0 +1,43 @@
# Режимы и Fidelity
Один бинарник, одна конструкция, три пресета. Режим задаёт периоды подсистем и
выбор моделей (`Fidelity`), всё остальное общее.
| Режим | Что это | Точность |
|---|---|---|
| **Bench** | Плата без мира: SoC, периферия, схема, питание | МК по тактам, аналоговый шаг до 1 мкс |
| **Lab** | Одна деталь на стенде: нагрузка, ток, температура | FEM, подробные мышцы, тепло, аналоговый шаг до 1 мкс |
| **World** | Паук в мире: поляна, горы, ветер | физика 1 кГц (1 мс), аналоговый шаг до 50 мкс, МК пачками |
Деталь из World можно «вынуть» в Lab, плату — в Bench, конструкция та же.
Шаг физики 1 кГц выбран под ходьбу: при 250 Гц контакт стопы и жёсткий шарнир
разъезжаются по фазе. 1 мс — целое число наносекунд (1 000 000 нс), поэтому
делится без остатка. Если эталонная сцена не тянет real-time, World замедляется,
а не огрубляется (см. бюджет в ARCHITECTURE.md).
## Fidelity (примеры)
| Подсистема | Высокая | Низкая |
|---|---|---|
| Мышца | модель Хилла + тепло | простой привод |
| Электроника | transient MNA, шаг до 1 мкс | идеальные элементы, шаг до 50 мкс |
| Механика | балки/FEM | жёсткие тела + нагрузки на шарниры |
| Аэродинамика | панельный метод | таблицы коэффициентов |
| МК | по тактам | пачки по 1000 тактов, квантованные прерывания |
Fidelity — набор независимых полей, а не единый переключатель: можно взять точную
механику и простую электронику. Режимы — только пресеты этих полей.
## События
Шаг подсистемы ограничен не только периодом, но и ближайшим событием в очереди:
фронт PWM, прерывание МК, отказ. Событие делит шаг в момент своего наступления
(COUPLING.md). Между событиями входы удерживаются.
## Управление временем (отдельно от Fidelity)
- Масштабируется только показ; шаг симуляции `dt` не меняется.
- Пауза; шаг на такт, квант или (Bench) инструкцию МК.
- Замедление 0.01×–1×; ускорение ограничено real-time factor.
- Перемотка назад: ближайший снимок + досчёт вперёд (возможна из-за детерминизма).
- Рендер интерполирует между снимками.
- Bench и Lab никогда не огрубляются: если железо не тянет, симуляция идёт медленнее
реального времени (показывается RTF). Только World может снижать визуальное качество.

36
docs/PHYSICS_SCOPE.md Normal file
View file

@ -0,0 +1,36 @@
# Физика: объём и цели
Цель — спроектировать любую конструкцию на 100% так, чтобы её можно было собрать
в реальности. Движок универсален; мех-паук — только первый пример.
## Импорт и материалы
Меш (glTF/STL/OBJ) + материал → объём, масса, центр масс, тензор инерции (по
дивергенции), коллайдер. Параметры материала: плотность, модуль Юнга, предел
текучести и прочности, трение, теплопроводность, теплоёмкость, удельное
сопротивление. Заполнение (infill/полость) задаёт эффективную плотность.
## Механика (`physics`, `structure`)
- Жёсткие тела, шарниры, ограничения, контакты (Rapier на старте).
- Трение: статическое и кинетическое, переключаемая модель (Кулон, с вязкой частью).
- Балочные и FEM-элементы для Lab: поле напряжений, деформации, усталость.
- Разрушение: при превышении прочности деталь ломается (разделение по сечению).
## Тепло и вентиляция (`thermal`)
Теплопроводность, конвекция, излучение; источники: мышцы, моторы, провода,
микросхемы. Вентиляция: потоки воздуха через корпус, обдув радиаторов. Метод
(сеть каналов или CFD-lite) решаем перед этим этапом.
## Проводка (`wiring`)
Жгуты: сечение AWG, длина, сопротивление, падение напряжения, нагрев током и его
обратная связь в `thermal`, разъёмы, предохранители.
## Аэродинамика (`aero`)
Панельный метод для Lab, таблицы коэффициентов для World; ветер.
## Режимы вида (`render::views`)
Переключаемые цветовые карты по деталям: напряжение (запас до разрушения),
деформация, температура, ток, давление/поток воздуха, трение/контакт.
## Выход в реальность (`parts::bom`)
Из конструкции экспортируется BOM: детали, материалы, массы, крепёж, провода,
компоненты платы. Допуски и реальные размеры учитываются в сцене.

22
docs/PLUGINS.md Normal file
View file

@ -0,0 +1,22 @@
# Плагины деталей
Деталь это данные (RON) плюс при необходимости плагин (Rust-код).
## Правила до версии 1.0
- Только статическая регистрация через Rust API при сборке. Динамические библиотеки
не поддерживаем.
- Идентификатор `автор.имя` и версия semver. Зависимости от других плагинов и от
версии ядра объявляются явно; несовместимость это ошибка загрузки.
- Плагин получает доступ только к трейтам подсистем (порты: механический,
электрический, тепловой), а не к их внутренним данным.
- Состояние плагина сериализуется через serde и входит в подснимок; после загрузки
снимка плагин восстанавливается из него.
- Плагин детерминирован и подчиняется правилам DETERMINISM.md.
## Жизненный цикл
`register` → `validate` (данные и версии) → `instantiate` (на сцену) → `step` (по
периоду) → `snapshot` и `restore` → `drop`.
## Стабильность
Проект публичный, но до версии 0.6.0 API плагинов может ломаться без предупреждения
(D26). К 0.6.0 API стабилизируется и дальше подчиняется semver.

39
docs/README.md Normal file
View file

@ -0,0 +1,39 @@
# Fabrilis — документация
Платформа полного проектирования механизмов: подробная физика + электроника +
код + управление. Цель — спроектировать любую конструкцию целиком (механика,
материалы, проводка, плата, прошивка), проверить её на сценариях работы,
стабилизацию, отказы, нагрузки, тепло и окружение, а затем собрать в реальности.
Мех-паук — первый эталонный проект (`examples/`), а не часть движка: в движке
нет кода под конкретную конструкцию.
| Документ | О чём |
|---|---|
| [ARCHITECTURE.md](ARCHITECTURE.md) | crate'ы, слои, поток данных, бюджет производительности |
| [DECISIONS.md](DECISIONS.md) | принятые решения и открытые вопросы |
| [MODES.md](MODES.md) | режимы Bench / Lab / World, Fidelity, время, события |
| [UI.md](UI.md) | свой UI: модель, текст, event-driven redraw, что берём из ShapeUI |
| [PHYSICS_SCOPE.md](PHYSICS_SCOPE.md) | механика, FEM, трение, тепло, вентиляция, проводка, виды |
| [SCENARIOS.md](SCENARIOS.md) | сценарии, стабилизация, отказы, развёртки, метрики |
| [ELECTRONICS.md](ELECTRONICS.md) | эмуляция CPU/SoC, аналоговая схема, мост |
| [COUPLING.md](COUPLING.md) | связь подсистем: классы связей, события, откат шага |
| [DETERMINISM.md](DETERMINISM.md) | уровни D1/D2/D3 и правила одинакового результата |
| [COORDINATES.md](COORDINATES.md) | системы координат, единицы, оси |
| [STORAGE.md](STORAGE.md) | проекты, конструкции, снимки, миры |
| [TESTING.md](TESTING.md) | стратегия тестов |
| [VALIDATION.md](VALIDATION.md) | verification, validation, qualification |
| [DEPENDENCIES.md](DEPENDENCIES.md) | библиотеки: что берём, что пишем сами, сколько весят |
| [PLUGINS.md](PLUGINS.md) | деталь как данные и плагин, правила совместимости |
| [REFERENCES.md](REFERENCES.md) | что читать и у кого подсматривать |
| [CODE_RULES.md](CODE_RULES.md) | проверяемые правила кода (лимиты, тесты отдельно, слои) |
Лицензия: [MIT](../LICENSE).
План работ: [../TODO.md](../TODO.md).
Название: Fabrilis (лат. fabrilis, «относящийся к мастеру, ремесленнику»). Автор: loki.
Статус: готовы M0 (скелет, правила, CI) и M1 (ядро: единицы, время, математика,
планировщик, Fidelity, снимки). Дальше M2 — один шарнир: своя векторная
математика, seeded RNG, минимальная физика с мотором и датчиками.

131
docs/REFERENCES.md Normal file
View file

@ -0,0 +1,131 @@
# Что читать
Не копировать целиком и не тянуть в зависимости, а искать конкретные алгоритмы и
решения. Ссылки проверены 16.11.2026.
Ориентиры по режимам: **Renode** ближе всего к Bench, **MuJoCo** — к World,
**SOFA** — к Lab и FEM.
## Локальные клоны
Исходники этих проектов лежат в `ref/` — папка в `.gitignore` и не проверяется
правилами кода. Клоны неполные (история не нужна): читаем код, не собираем.
Создать или дополнить: `tools/fetch_refs.sh`. Обновить один проект:
`git -C ref/<имя> pull`. Удалить: `rm -rf ref/<имя>`.
| Категория | В `ref/` |
|---|---|
| Эмуляция железа | `renode`, `mini-rv32ima` |
| Физика | `mujoco`, `jolt`, `box2d` |
| FEM и прочность | `calculix`, `sofa`, `scikit-fem` |
| Электроника | `ngspice`, `circuitjs` |
| Мир и сенсоры | `gazebo` |
| Робототехника и сценарии | `cheetah`, `opencat`, `carla-scenario-runner` |
| UI и форматы | `imgui`, `egui`, `openscad` |
Библиотеки, которые мы используем (Rapier, wgpu, winit, rhai, fontdue), сюда не
клонируются: их исходники и так лежат в `~/.cargo/registry`.
## Первая очередь
- **Renode** — виртуальное железо, периферия, временная модель, сценарии.
- **MuJoCo** — динамика механизмов, контакты, культура воспроизводимости.
- **SOFA** — FEM и компонентная архитектура.
- **Rapier** — наша текущая физика.
- **QEMU** — CPU, MMU, SoC и устройства.
- **ngspice** — MNA и всё, что вокруг transient-анализа.
## Связь подсистем и эмуляция железа
- [Renode](https://github.com/renode/renode): эмуляция SoC, периферия, временная
модель, сценарии. Ближайший аналог режима Bench.
- [FMI](https://fmi-standard.org/): стандарт co-simulation; словарь для `bridge`
и точек синхронизации.
- [OpenModelica](https://openmodelica.org/): мультидоменная модель уравнениями;
полезно понять, где граница между нами и «системой уравнений».
- [QEMU](https://github.com/qemu/qemu): RISC-V target, MMU, исключения, virtio.
Обязательное чтение перед M8 и M11.
- [TinyEMU](https://bellard.org/tinyemu/): RV32/RV64, Linux и virtio в малом объёме
кода; главный референс для этапов CPU и Linux.
- [mini-rv32ima](https://github.com/cnlohr/mini-rv32ima): крошечный RV32, удобен для
эмуляции МК по тактам.
- [Spike](https://github.com/riscv-software-src/riscv-isa-sim) и
[riscv-tests](https://github.com/riscv-software-src/riscv-tests): эталонная модель
ISA и тесты для дифференциальной проверки.
- [xv6-riscv](https://github.com/mit-pdos/xv6-riscv): простая ОС для интеграционных
тестов до полноценного Linux.
- [Verilator](https://github.com/verilator/verilator): на будущее, если дойдём до
логического уровня.
- [Wokwi](https://wokwi.com/): UX-референс «МК + схема + симуляция в одном месте».
## Физика и детерминизм
- [MuJoCo](https://github.com/google-deepmind/mujoco): динамика механизмов,
articulated bodies, контакты, воспроизводимость.
- [Jolt Physics](https://github.com/jrouwe/JoltPhysics): режим детерминизма и его
тесты в CI — образец оформления golden-тестов физики.
- [Box2D](https://github.com/erincatto/box2d): солвер ограничений, эталон читаемости
перед своим backend'ом.
- [Rapier](https://github.com/dimforge/rapier) и
[руководство по детерминизму](https://rapier.rs/docs/user_guides/rust/determinism):
границы `enhanced-determinism`, поведение f32.
- [Project Chrono](https://github.com/projectchrono/chrono): многотельная механика и
мехатроника.
- [Rigs of Rods](https://github.com/RigsOfRods/rigs-of-rods) и идея BeamNG: модель
«узлы и балки» для разрушения в World.
- [Fix Your Timestep](https://gafferongames.com/post/fix_your_timestep/): фиксированный
шаг и интерполяция рендера.
- Overwatch GDC 2017: ECS, реплей и перемотка — схема, близкая к нашим снимкам.
## FEM и прочность
- [SOFA](https://github.com/sofa-framework/sofa): компонентная архитектура
деформируемых моделей.
- [CalculiX](http://www.dhondt.de/): балки, тетраэдры, контакт; смотреть постановки
и верификационные кейсы.
- [FreeCAD FEM](https://github.com/FreeCAD/FreeCAD): инженерный workflow
«геометрия → сетка → условия → решатель → результат».
- [scikit-fem](https://github.com/kinnala/scikit-fem): маленькая FEM-библиотека,
которую можно прочитать целиком.
- [anastruct](https://github.com/ritchie46/anastruct) и
[PyNite](https://github.com/oliehood/PyNite): рамные и балочные расчёты — масштаб,
который реально осилить.
- [Gmsh](https://gmsh.info/): генерация сеток и форматы.
- [fTetWild](https://github.com/wildmeshing/fTetWild) и
[TetGen](https://wias-berlin.de/software/tetgen/): оценить, сколько стоит
тетраэдризация меша.
- [OpenFOAM](https://www.openfoam.com/): CFD и граничные условия, если дойдём до
честных воздушных потоков.
## Электроника
- [ngspice](https://ngspice.sourceforge.io/): штампы MNA, Newton, контроль шага,
breakpoints, gmin и source stepping.
- [CircuitJS](https://github.com/sharpie7/circuitjs1): читаемая реализация MNA.
- [ahkab](https://github.com/ahkab/ahkab): компактный SPICE на Python.
- [KiCad](https://www.kicad.org/): плата как данные; посмотреть текстовые форматы
до того, как замораживать свои RON-схемы.
## Мир и рендер
- [CDLOD](http://www.cdlod.com/): статья и код Strugar'а; clipmap-террейн проще
понимать через CDLOD.
- [Gazebo](https://gazebosim.org/): как разведены мир, сенсоры и контроллер.
- [Webots](https://cyberbotics.com/): архитектура сенсоров, плагинов и миров.
- [Bevy](https://github.com/bevyengine/bevy): ECS, asset pipeline и организация
рендера; движок не берём, идеи смотрим.
## Робототехника и сценарии
- [Cheetah-Software](https://github.com/mit-biomimetics/Cheetah-Software): открытый
стек походки и стабилизации.
- [Stanford Doggo](https://github.com/stanfordroboticsclub/StanfordDoggoProject):
реальные массы и моменты для приводов.
- [Open Dynamic Robot Initiative](https://github.com/open-dynamic-robot-initiative):
открытые приводы и ноги как источник реалистичных цифр и BOM.
- [Petoi OpenCat](https://github.com/PetoiCamp/OpenCat): «МК + серво + четвероногое»
в масштабе, близком к Bench и World.
- [CARLA scenario_runner](https://github.com/carla-simulator/scenario-runner): DSL
сценариев, метрики и pass/fail — почти наша задача «сценарий как опыт».
## UI и данные
- **ShapeUI blueprint** (локальная копия `ref/shapeui-blueprint_v0.2_revised_ru.md`):
контракты shape-aware UI. Берём только идеи — event-driven redraw, command list,
glyph atlas, capability-модель (см. UI.md), не архитектуру.
- [Dear ImGui](https://github.com/ocornut/imgui): ID-стеки, клиппинг, батчинг —
минимальная архитектура виджетов перед своим UI.
- [egui](https://github.com/emilk/egui): только читать, зависимость не берём (D20).
- [OpenSCAD](https://openscad.org/): конструкция как параметризованные данные —
посмотреть на текстовый формат.

30
docs/SCENARIOS.md Normal file
View file

@ -0,0 +1,30 @@
# Сценарии и анализ
Проектирование не заканчивается сборкой модели: нужно доказать, что она работает
в заданных условиях. Сценарий — воспроизводимый опыт (seed + входы + скрипт).
## Что проверяем
- **Рабочие сценарии**: ходьба, подъём, перенос груза, взлёт, любые задачи конструкции.
- **Стабилизация и управление**: устойчивость контроллера (PID, свой код на МК),
реакция на возмущения (толчок, порыв ветра, неровность), задержки и шум датчиков.
- **Отказы (fault injection)**: обрыв провода, просадка батареи, заклинивание
привода, перегрев, отказ датчика, сбой прошивки, поломка детали.
- **Нагрузки и ресурс**: пики напряжений, запас прочности, усталость, температура.
- **Окружение**: ветер, поверхность, температура воздуха, наклон.
## Инструменты (`analysis`, `sensors`, `scripting`)
- **Сценарии Rhai**: подготовка сцены, подача входов и возмущений, проверки (assert),
запись метрик.
- **Развёртки параметров**: перебор длины, массы, коэффициентов регулятора;
параллельный прогон на ядрах, результат не зависит от числа потоков.
- **Monte Carlo с допусками**: разброс размеров, материалов, номиналов, шума.
- **Метрики устойчивости**: перерегулирование, время установления, запас по углу
опрокидывания, энергопотребление, время до отказа.
- **Датчики** (`sensors`): IMU, энкодеры, токовые датчики; шум, смещение, задержка,
дискретизация; управление видит мир только через них.
- **Позже**: линеаризация и частотный отклик контуров управления, запасы по
амплитуде и фазе.
## Результат
Отчёт по сценарию: графики, метрики, пройдено или нет, ссылка на хеш конструкции и
версию движка. Хранится как сценарий опыта (STORAGE.md).

20
docs/STORAGE.md Normal file
View file

@ -0,0 +1,20 @@
# Сохранения
Программа и данные разделены. Данные лежат в **папке проекта**, которую можно
целиком положить в git. Личные настройки лежат отдельно.
| Что | Формат | Заметка |
|---|---|---|
| Библиотека (меши, материалы, детали) | файлы + RON | переиспользуется между проектами |
| Конструкция (детали, шарниры, проводка, схемы, ссылка на прошивку) | читаемый RON | версия схемы + миграции |
| Прошивки, образы Linux | бинарники, ссылка по хешу | blob-хранилище |
| Мир | seed + параметры + дельта правок | остальное генерируется |
| Снимок симуляции | бинарный, сжатый | привязан к версии движка и хешу конструкции |
| Сценарий опыта | RON + бинарник результатов | режим, конструкция, мир, скрипт, графики |
| Настройки, профиль устройства | XDG (`~/.config`, `~/.local/share`) | у каждого свои |
## Правила
- Каждый файл несёт `format_version`; `storage::migrate` умеет переводить вперёд.
- Снимки не гарантируют совместимость между версиями; для долгого хранения
используем сценарий (seed + входы), он воспроизводится детерминированно.
- Крупные бинарные файлы хранятся один раз по хешу содержимого.

30
docs/TESTING.md Normal file
View file

@ -0,0 +1,30 @@
# Тесты
Тесты лежат отдельно от кода: `tests.rs` рядом с модулем или папка `tests/` (CODE_RULES.md).
1. **Юнит-тесты** в каждом crate.
2. **Валидация по аналитике** (физика должна совпадать с формулами):
- консольная балка: прогиб `δ = PL³ / 3EI`;
- маятник, снаряд с сопротивлением;
- RC-цепь: экспонента заряда;
- одномерная теплопроводность;
- масса и инерция меша: шар, куб, цилиндр.
3. **Property-тесты** на seeded `core::rng` — основа (инварианты массы, инерции,
симметрия тензора). `proptest` разрешён как dev-зависимость (D26) там, где нужен
shrinking, но не заменяет свои тесты.
4. **Детерминизм**: golden-хеши состояния на уровнях D1/D2/D3 (DETERMINISM.md):
своя машина, 1/2/8/24 потока, три ОС. Хеш хранится в репозитории.
5. **RISC-V**: официальные `riscv-tests` (rv32ui/rv64ui и др.) и дифференциальное
тестирование против QEMU или Spike на случайных программах; загрузка Linux как
медленный интеграционный тест.
6. **Форматы**: snapshot-тесты сцены и миграции версий; проверка меша до расчёта
массы (замкнутость, ориентация нормалей, единицы).
7. **Производительность**: бенчмарки горячих путей в `benches/` (`criterion` как
dev-зависимость, D26) плюс бюджет эталонной сцены в CI; регрессия видна как
падение RTF.
8. **Правила репозитория**: `fabrilis-limits` (в `build.rs` каждого crate'а,
pre-commit и CI); тесты лежат в отдельных файлах (CODE_RULES.md).
9. **Сценарии Rhai** служат функциональными тестами («подними паука, замерь нагрузку»).
Verification (правильность реализации) и validation (совпадение с реальной
сборкой) — разные вещи, см. VALIDATION.md.

88
docs/UI.md Normal file
View file

@ -0,0 +1,88 @@
# UI
UI Fabrilis — это редактор и отладочный оверлей внутри приложения, а не отдельный
UI-фреймворк и не библиотека для чужих программ. Окно обычное прямоугольное,
управление окном и вводом — на `winit` (D24), рисование — на нашем `wgpu`-рендере,
готовые UI-библиотеки не берём (D20).
## Модель
- **Immediate-mode на старте.** UI каждый кадр строит список команд рисования
(прямоугольник, скруглённый прямоугольник, линия, текст, картинка, клип), рендер
батчит их. Состояние виджетов живёт в приложении, а не в дереве UI.
- **Retained-дерево только по доказанной нужде.** Если профилирование покажет, что
пересборка команд дорога, вводим стабильные `NodeId`, dirty-флаги и кеш ресурсов.
Reconciliation и анимационный граф заранее не пишем.
- **Event-driven redraw.** Нет изменений — нет кадра. Каждый кадр имеет причину
(`Input`, `Animation`, `Resize`, `SimulationTick`, `Debug`), счётчик причин виден
в оверлее; в простое — 0 кадров/с.
- **Кеш ресурсов.** Пайплайны кешируются по `shader + layout + format + blend`;
текст — через общий glyph atlas, а не текстуру на надпись. Offscreen-проходы
только там, где эффект этого требует.
- **Capability-модель.** Вместо `bool` — `Available | Unavailable { reason } |
Conditional { reason }`: «нет прозрачности», «fractional scale не поддержан»,
«эффект недоступен на этом backend'е». Не выполнять молча.
## Что есть в M4 и M10
| Этап | UI |
|---|---|
| M4 | оверлей отладки: FPS/RTF, число тел, причины кадров, время подсистем; прямоугольники, текст, линии, клип |
| M10 | панели и сплиттеры, дерево конструкции, таблица свойств, графики, 3D-вид, диалоги, текстовые поля |
Виджеты вводятся по одному и только под конкретную задачу редактора. Зоопарк
«на будущее» запрещён (KISS).
## Текст
- Сейчас: `fontdue` только растеризует глифы, раскладку строк и переносы делаем сами.
Для латиницы и кириллицы этого достаточно.
- Текстовые поля требуют shaping и IME. Решение отложено до M10: кандидаты —
`cosmic-text` или `Parley` (+ `glyphon` для wgpu). Берём только когда появляется
настоящее поле ввода, с записью в DECISIONS.md.
- Курсор, выделение, копирование и IME не эмулируем частично: либо полноценно, либо
поле ввода не выпускаем.
## Что взято из ShapeUI blueprint
Локальная копия: `ref/shapeui-blueprint_v0.2_revised_ru.md` (в git не входит).
Из него берём идеи, не архитектуру:
- event-driven redraw и счётчик причины кадра;
- render command list и батчинг вместо draw call на виджет;
- общий glyph atlas;
- раздельные dirty-флаги (стиль, layout, текст, геометрия);
- capability-модель вместо обещаний `bool`;
- оверлей диагностики: PSS/RSS, draw calls, offscreen passes, кеши, причина кадра;
- дисциплину «сначала панели/текст/ввод, потом виджеты».
## Что из ShapeUI не берём
- Окна произвольной формы, click-through, `wl_region`, `set_input_region`: у нас
обычное окно, этим занимается `winit`.
- Свой Wayland-backend и raw `wl_surface`: дублирует `winit`.
- CPU-рендерер, Vello, несколько backend'ов, morphing, shader marketplace.
- Собственный scene graph с реконсиляцией до доказанной необходимости.
- Доступность (AccessKit) с первого дня; вернёмся к ней перед публичным релизом.
## Диагностика
Оверлей показывает то, что можно проверить:
```
PSS / RSS 38.4 / 51.1 MiB (estimated)
draw calls 6
offscreen 1
pipelines 5
glyph atlas 2.1 MiB
frames last 10s 0
last frame Idle
```
Числа не выдаются за «всю VRAM процесса»; приблизительные помечаются `estimated`.
## Открыто
- Shaping и IME для текстовых полей: `cosmic-text` или `Parley`, решаем на M10.
- Нужен ли retained-слой: решаем по профилировке M10, не заранее.
- Графики: своя простая отрисовка линий и областей; библиотеку не берём.

47
docs/VALIDATION.md Normal file
View file

@ -0,0 +1,47 @@
# Проверка достоверности
Результат, который красиво выглядит, не обязательно верен. Здесь три разных вопроса.
| Понятие | Вопрос | Чем отвечаем |
|---|---|---|
| Verification | правильно ли реализованы алгоритмы | аналитические задачи, golden-хеши, дифференциальные тесты CPU |
| Validation | описывает ли модель реальный механизм | сравнение с измерениями реальной сборки |
| Qualification | достаточно ли проверена модель для конкретного применения | область применимости каждой модели, записанная в её описании |
## Verification
Консольная балка, маятник, RC-цепь, теплопроводность, масса и инерция простых тел
(TESTING.md). Для CPU: `riscv-tests` и сравнение со Spike или QEMU. Для детерминизма:
golden-хеши (DETERMINISM.md).
## Validation и калибровка
1. Собрать реальный механизм или узел.
2. Измерить массу, момент инерции, токи, напряжения, температуры, траектории.
3. Прогнать то же самое в Fabrilis.
4. Сравнить и записать расхождения.
5. Подправить параметры модели (трение, КПД, сопротивления) и записать допуски.
Калибровка не заменяет Monte Carlo: Monte Carlo показывает разброс, а калибровка
находит систематическое смещение.
## Неопределённость
Допуски размеров, материалов, номиналов, шумов датчиков. Результат несёт оценку
чувствительности к параметрам и оценку доверия, а не только число.
## Диагностика достоверности
Движок сообщает, когда результату нельзя верить:
- решатель не сошёлся;
- меш не замкнут или не ориентирован;
- модель работает вне области применимости (скорость, температура, деформация);
- шаг был уменьшен откатом;
- эффективный шаг больше допустимого.
Диагностика попадает в отчёт сценария, а не только в лог.
## Проверка меша перед расчётом массы
Каждое ребро принадлежит двум треугольникам, ориентация согласована, вырожденных
треугольников нет, объём положителен. Единицы заданы явно (COORDINATES.md). Иначе
импорт возвращает ошибку: масса по теореме Гаусса на дырявой сетке бессмысленна.
## Версионирование
Сценарий хранит хеш конструкции, версию движка и версии моделей. Результаты с
несовпадающими версиями помечаются как несравнимые.