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 79928b645b
Signed by: boba
GPG key ID: 6CDE87BC9A778D97
222 changed files with 5335 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
нужно внести туда, иначе сборка падает.