# AtlasOS — Архитектура

AtlasOS — миниатюрная UNIX-подобная операционная система для бортовых компьютеров
игры **Barotrauma**, построенная на MicroLua-контроллерах. Документ описывает
полную архитектуру: аппаратный слой, шину, модель памяти, файловую систему,
систему прав и модель выполнения программ.

> Версия архитектуры: **2.0** (inode-ФС). Прототип CLI: `atlas_os/AtlasOS.lua`.

---

## 1. Цели проекта

- Дать **командную оболочку** (shell) на терминале внутри игры.
- Реализовать **постоянное хранилище** (файловую систему) поверх компонентов памяти.
- Поддержать **многопользовательность** в духе Linux: пользователи, группы, права `rwx`.
- Работать в условиях **жёсткого лимита памяти** компонентов Barotrauma.
- Оставаться **компактным**: система не должна разрастаться и съедать память,
  предназначенную для пользовательских данных.

## 2. Ключевые ограничения (платформа Barotrauma + MicroLua)

| Ограничение | Значение | Источник |
|---|---|---|
| Контроллеров в системе | до **8** | требование |
| Пинов на контроллер | **32 входа / 32 выхода** | MicroLua |
| Ёмкость компонента памяти | **4096 символов UTF-8** | компонент Memory |
| Типы сигналов на пинах | `integer`, `string`, `color` (`"R,G,B"`) | MicroLua |
| Модель исполнения | `upd(dt)` каждый кадр **или** событие `inp(pin,val)` | MicroLua |
| Состояние Lua | **не сохраняется** между раундами | MicroLua |

Из последнего пункта следует фундаментальный принцип: **всё, что должно пережить
раунд, обязано лежать в компонентах памяти**, а не в Lua-переменных контроллера.
Lua-состояние используется только как **кэш и регистры** (см. `03-memory-model.md`).

## 3. Декомпозиция на блоки

Система разделена на три функциональных блока. Каждый блок — отдельный физический
MicroLua-контроллер; блоки общаются по **сигнальной шине** (проводам между пинами).

```
                         ┌──────────────────────────────┐
                         │        ТЕРМИНАЛ (экран)       │
                         │  текст · цвет · ввод · clear  │
                         └───────────────▲──────────────┘
                                         │ I/O-провода
                         ┌───────────────┴──────────────┐
   ввод пользователя ──▶ │   IOC — I/O Controller        │
                         │   (блок ввода/вывода)         │
                         └───────────────▲──────────────┘
                                         │ шина CMD
                         ┌───────────────┴──────────────┐
                         │   CMC — Command Controller    │  ◀── shell, разбор
                         │   (контроллер команд, «CPU»)  │      команд, сессия
                         └───────────────▲──────────────┘
                                         │ шина MEM
                         ┌───────────────┴──────────────┐
                         │   MMC — Memory/FS Controller  │  ◀── inode-ФС, MMU,
                         │   (блок памяти и ФС)          │      LZ4, права
                         └───────────────▲──────────────┘
                                         │ линии сегментов
            ┌────────────┬───────────────┼───────────────┬────────────┐
        ┌───┴───┐    ┌───┴───┐       ┌───┴───┐        ┌───┴───┐    ┌───┴───┐
        │ SEG0  │    │ SEG1  │  ...  │ SEGk  │   ...  │ SEGn-1│    │ SEGn  │
        │система│    │ user  │       │ user  │        │ user  │    │ user  │
        └───────┘    └───────┘       └───────┘        └───────┘    └───────┘
                          компоненты памяти (по 4096 симв.)
```

| Блок | Контроллер | Роль |
|---|---|---|
| Ввод/вывод | **IOC** | Терминал: вывод текста, цвет, очистка, чтение строки ввода. |
| Контроллер команд | **CMC** | Shell: парсинг, диспетчеризация команд, сессия пользователя, права на уровне вызовов. |
| Память и ФС | **MMC** | MMU + файловая система (inode), сжатие LZ4, выделение блоков, проверка прав на уровне ФС. |

Оставшиеся до 5 контроллеров — **резерв/копроцессоры** (тяжёлые команды,
параллельные сессии). См. `01-hardware.md`.

## 4. Разделение памяти: система ⇄ пользователь

Адресное пространство хранилища делится на две области (подробно — `03-memory-model.md`):

- **Системная область (kernel space).** Метаданные: суперблок, таблица inode,
  список свободных блоков, таблица пользователей. Указатели хранятся здесь.
  Компактна, фиксированного объёма.
- **Пользовательское пространство (user space).** Содержимое файлов, сжатое **LZ4**
  и закодированное в безопасный текст (Base64 по умолчанию, BMP-упаковка как опция).

Принцип: **«указатели — в системе, данные — у пользователя»**. Контроллеры держат
в Lua только указатели/индексы и небольшие кэши, а объёмные строки живут в
сегментах пользовательского пространства и подгружаются по требованию.

## 5. Карта документов

| Файл | Содержание |
|---|---|
| [`01-hardware.md`](01-hardware.md) | Компоненты, пины, типы сигналов, распределение контроллеров, физическая топология. |
| [`02-bus-protocol.md`](02-bus-protocol.md) | Протокол обмена между IOC↔CMC↔MMC по пинам: кадры, опкоды, коды ошибок. |
| [`03-memory-model.md`](03-memory-model.md) | Адресное пространство, сегменты, указатели, блочное выделение, LZ4 и кодирование. |
| [`04-filesystem.md`](04-filesystem.md) | inode-ФС: суперблок, формат inode, каталоги, аллокатор блоков, сериализация. |
| [`05-users-permissions.md`](05-users-permissions.md) | Пользователи, группы, режим `rwx`, аутентификация, проверка прав. |
| [`06-execution-model.md`](06-execution-model.md) | Контроллер команд, оболочка, модель программы и процесса, копроцессоры. |
| [`07-command-set.md`](07-command-set.md) | Спецификация команд `ls`, `ls -l`, `ls -la`, `cat`, `cd` и правила расширения. |

## 6. Глоссарий

| Термин | Значение |
|---|---|
| **IOC / MMC / CMC** | Три блочных контроллера (I/O, Память/ФС, Команды). |
| **Сегмент (SEG)** | Один компонент памяти Barotrauma, ёмкость `SEG_SIZE = 4096` символов. |
| **Блок (block)** | Логическая единица хранения данных файла внутри сегмента (`BLOCK_SIZE` символов). |
| **inode** | Запись метаданных одного объекта ФС (тип, права, владелец, размер, список блоков). |
| **Системная область** | Сегменты/поля с метаданными ФС и указателями. |
| **Пользовательское пространство** | Сегменты с содержимым файлов (сжатым LZ4). |
| **Шина (bus)** | Набор пинов-проводов между контроллерами для обмена сообщениями. |
| **Сессия** | Текущий контекст shell в CMC: uid/gid, рабочий каталог (cwd), окружение. |