Документация проекта AtlasOS

2026-06-14 01:17:37 +03:00
parent db99f47077
commit 66d9f8037c
8 changed files with 588 additions and 0 deletions
--- a/atlas_os/docs/01-hardware.md
+++ b/atlas_os/docs/01-hardware.md
@@ -0,0 +1,83 @@
+# 01 — Аппаратный слой (Hardware)
+
+## 1. Физические компоненты
+
+AtlasOS использует следующие компоненты Barotrauma + MicroLua:
+
+| Компонент | Кол-во | Назначение | Ёмкость / пины | Примечание |
+|---|---|---|---|---|
+| **MicroLua** | 3 (+5 резерв) | **IOC, CMC, MMC** | 32 in / 32 out | контроллеры блоков |
+| **Memory** | n (≥2) | сегменты **SEG0..SEGn** | 4096 символов UTF-8 | хранилище |
+| **Terminal / Display** | n | экраны | — | по одному IOC на терминал, login/logout per-terminal |
+
+Дополнительно:
+
+- Кнопки / переключатели — источники ввода команд.
+- Memory-компоненты подключаются к MMC по **WE- и RD-линиям** (подробно ниже).
+
+## 2. Распределение контроллеров
+
+| Контроллер | Роль | Входы (примеры) | Выходы (примеры) |
+|---|---|---|---|
+| **IOC** (n шт.) | терминал + login | in1 = ввод строки | out1 = текст, out2 = clear, out3 = цвет |
+| **CMC** (1) | центральный CPU, shell | сообщения от IOC | команды к IOC и MMC (однонаправленно) |
+| **MMC** (1) | MMU + inode-ФС | ответы от SEG | WE/RD/DATA к сегментам |
+
+Оставшиеся до 5 контроллеров:
+
+- копроцессоры тяжёлых команд (поиск, архивирование);
+- параллельные сессии;
+- внешние устройства (радио, датчики, логи).
+
+## 3. Пины и типы сигналов (MicroLua)
+
+| Тип на пине | Формат | Пример | Использование |
+|---|---|---|---|
+| integer | `0`, `1`, `-100` | `out[2] = 1` (clear) | флаги, адреса, коды |
+| string | UTF-8 | `out[1] = "ls -l"` | тексты, имена файлов, JSON-подобные сообщения шины |
+| color | `"R,G,B"` | `"255,0,128"` | цвет текста на терминале |
+
+**Важно:** строковые сигналы **неэкранированы** по умолчанию. При передаче по шине специализированные символы (`|`, `\n`, `,`) экранируются внутри протокола (см. `02-bus-protocol.md`).
+
+## 4. Физическая топология (схема пинов)
+
+```
+          Терминал 1          IOC1          Терминал 2          IOC2
+          ┌────────┐       ┌────────┐      ┌────────┐       ┌────────┐
+          │экран   │◀──────│out1-3  │      │экран   │◀──────│out1-3  │
+          │ввод    │──────▶│in1     │      │ввод    │──────▶│in1     │
+          └────────┘       └────▲───┘      └────────┘       └────▲───┘
+                                 │                                │
+                                 └──────────────┬─────────────────┘
+                                                │ (однонаправленно)
+                              ┌─────────────────▼─────────────────┐
+                              │              CMC (1)              │
+                              │        центральный CPU            │
+                              └─────────────────▲─────────────────┘
+                                                │ (однонаправленно)
+                              ┌─────────────────▼─────────────────┐
+                              │              MMC (1)              │
+                              │         память + inode-ФС         │
+                              └─────────────────▲─────────────────┘
+                    WE/RD/DATA (однонаправленно)
+               ┌──────────────┬──────────┬─────────────┐
+           ┌───┴───┐      ┌───┴───┐   ┌───┴───┐     ┌───┴───┐
+           │ SEG0  │ ...  │ SEGk  │   │SEG n-1│     │ SEGn  │
+           └───────┘      └───────┘   └───────┘     └───────┘
+```
+
+- Сигналы **только** `in → out` (никаких bidirectional пинов между контроллерами).
+- Каждый терминал имеет свой IOC — отдельная сессия + login/logout.
+- CMC — единственный исполнитель команд (центральный CPU).
+- MMC — единственный доступ к памяти.
+
+См. детальную организацию пинов и протокол в `02-bus-protocol.md`.
+
+## 5. Ограничения и рекомендации по экономии
+
+- Каждый SEG несёт ** overhead сериализации** (`|`, `\n`). Минимизируйте мелкие записи.
+- Храните **метаданные только в SEG0** (системная область).
+- Используйте **агрегированные сообщения шины** (batch) вместо множества мелких пинов.
+- Резервные контроллеры подключайте только когда нужно вынести тяжёлые вычисления.
+
+См. следующие документы для деталей протокола, памяти и ФС.
--- a/atlas_os/docs/02-bus-protocol.md
+++ b/atlas_os/docs/02-bus-protocol.md
@@ -0,0 +1,70 @@
+# 02 — Протокол шины (Bus Protocol)
+
+Между **IOC ↔ CMC ↔ MMC** обмен идёт по **сигнальным проводам** (пины MicroLua).
+Сообщения — короткие UTF-8 строки в формате:
+
+```
+OP|ARG1|ARG2|...|ARGn
+```
+
+Где:
+
+- `OP` — опкод (ASCII, регистрозависимый).
+- `ARG*` — аргументы, экранированные по правилу ниже.
+- Разделитель — `|` (pipe). Внутри аргументов `|` и `\` экранируются как `\|` и `\\`.
+- Строка не должна превышать разумный лимит; контроллеры сами усекают при ошибках.
+
+## 1. Направления и пины шины
+
+| Шина | Контроллеры | Выделенные пины CMC | Назначение |
+|---|---|---|---|
+| **CMD** | IOC ↔ CMC | `in_cmd`, `out_cmd` | ввод команд и вывод текста |
+| **MEM** | CMC ↔ MMC | `in_mem`, `out_mem` | запросы ФС и ответы |
+| **SEG** | MMC ↔ SEG* | `WE[i]`, `RD[i]`, `DATA` | прямой доступ к сегментам |
+
+## 2. Опкоды CMD (терминал)
+
+| Опкод | Направление | Аргументы | Описание |
+|---|---|---|---|
+| `OUT` | CMC → IOC | `text` | вывести текст на терминал |
+| `CLR` | CMC → IOC | — | очистить экран (`out[2]=1`) |
+| `COL` | CMC → IOC | `R,G,B` | установить текущий цвет |
+| `IN`  | IOC → CMC | `line` | пользователь ввёл строку |
+
+## 3. Опкоды MEM (файловая система)
+
+| Опкод | Направление | Аргументы | Ответ | Описание |
+|---|---|---|---|---|
+| `STAT` | CMC → MMC | `path` | `inode\|mode\|uid\|gid\|size` | метаданные файла |
+| `READ` | CMC → MMC | `path\|offset\|len` | `data` (Base64) | чтение фрагмента |
+| `WRITE` | CMC → MMC | `path\|offset\|data` | `OK\|bytes` или `ERR\|code` | запись |
+| `LS`   | CMC → MMC | `dir` | `name1\|inode1\|...` | список записей каталога |
+| `CHDIR` | CMC → MMC | `path` | `OK\|newcwd` или `ERR` | смена cwd (проверка прав) |
+
+Коды ошибок: `EACCES`, `ENOENT`, `EEXIST`, `ENOSPC`, `EINVAL`.
+
+## 4. Прямой доступ SEG (MMC ↔ SEG)
+
+MMC управляет сегментами напрямую по линиям `WE[i]`, `RD[i]`, `DATA`.
+Формат сообщений SEG-уровня — внутренний (не по шине), но общий принцип:
+
+```
+write_enable(i):   DATA <- encoded_block; pulse WE[i]
+read(i):           pulse RD[i]; receive DATA
+```
+
+CMC никогда не касается SEG напрямую — только через MMC.
+
+## 5. Тайминги и подтверждения
+
+- Каждый запрос шины требует **подтверждения** (ответ `OK`/`ERR`) в течение разумного числа кадров.
+- CMC может выполнять до **одного активного запроса** на шину одновременно (сериализация).
+- При отсутствии ответа — таймаут и ошибка `ETIMEDOUT`.
+
+## 6. Сериализация и безопасность
+
+- Все строковые данные экранируются: `|` → `\|`, `\` → `\\`.
+- Base64 (или BMP-упаковка) гарантирует, что сжатые данные не содержат управляющих символов.
+- Проверяйте длину: при превышении 4096 символов — ошибка.
+
+Подробности форматов inode, блоков и сжатия — в `03-memory-model.md` и `04-filesystem.md`.
--- a/atlas_os/docs/03-memory-model.md
+++ b/atlas_os/docs/03-memory-model.md
@@ -0,0 +1,62 @@
+# 03 — Модель памяти (Memory Model)
+
+## 1. Адресное пространство
+
+```
+0x0000          СИСТЕМНАЯ ОБЛАСТЬ (kernel space)
+  ├─ SEG0       суперблок + inode table + free list + passwd
+  └─ (опц.) SEG1  (расширение метаданных)
+
+0x1000+         ПОЛЬЗОВАТЕЛЬСКОЕ ПРОСТРАНСТВО (user space)
+  ├─ SEG2..SEGk блоки файлов (сжатые LZ4)
+  └─ ...        до SEGn (ограничено 8 контроллерами, n ~ десятки)
+```
+
+- **SEG0** обязателен и содержит **все указатели**.
+- Пользовательские данные (файлы) — **только** в user-сегментах.
+- Каждый сегмент — независимый компонент Memory (4096 символов UTF-8).
+
+## 2. Сегмент (SEG)
+
+| Поле | Размер | Описание |
+|---|---|---|
+| `SEG_SIZE` | 4096 | максимум символов UTF-8 |
+| `BLOCK_SIZE` | 512 | логический блок внутри сегмента (рекомендация) |
+| `BLOCKS_PER_SEG` | 8 | 512 × 8 = 4096 |
+
+> Можно использовать переменный размер блоков; главное — детерминированная адресация.
+
+**Адрес блока** кодируется как `uint32 = (seg_idx << 16) | block_idx`.
+
+## 3. Указатели и сериализация
+
+Все указатели (номера inode, номера блоков, смещения) хранятся в **SEG0** в компактном ASCII-формате:
+
+```
+SUPER|version|seg_size|inode_count|root_inode|free_head
+INODE|ino|type|mode|uid|gid|size|block0,block1,...
+DIR|ino|name→ino|name→ino|...
+PASSWD|uid|name|gid|home|hash
+```
+
+Контроллеры (CMC/MMC) держат в Lua-памяти только **индексы и кэши**, а не целые файлы.
+
+## 4. Сжатие и кодирование
+
+| Способ | Плотность | Безопасность | Примечание |
+|---|---|---|---|
+| **LZ4 + Base64** (по умолчанию) | ~3/4 | 100 % ASCII safe | 4096 симв. → ~3 КБ сжатых данных |
+| **LZ4 + BMP-упаковка** (опция) | ~2× | нужно экранирование управляющих | 2 байта → 1 символ |
+
+- Сжатие применяется **поблочно** (каждый блок файла сжимается отдельно).
+- При Base64 длина сжатого блока должна быть кратна 3 байтам.
+- Декодирование и распаковка — задача MMC при чтении/записи.
+
+## 5. Экономия памяти (рекомендации)
+
+- Храните **только метаданные** в SEG0; содержимое файлов — в user-сегментах.
+- Используйте **агрегированные free-list** вместо bitmap (экономит поле на сегмент).
+- Избегайте мелких файлов — они дают overhead inode + минимум 1 блок.
+- При чтении подгружайте **только нужные блоки**, не весь файл целиком.
+
+Следующий документ: `04-filesystem.md` — точные форматы inode, каталогов и free-list.
--- a/atlas_os/docs/04-filesystem.md
+++ b/atlas_os/docs/04-filesystem.md
@@ -0,0 +1,71 @@
+# 04 — Файловая система (inode-based FS)
+
+## 1. Суперблок (SEG0, первая строка)
+
+```
+SUPER|v1|4096|256|1|free_head
+```
+
+Поля:
+
+- `version` — строка формата.
+- `seg_size` — 4096.
+- `inode_count` — максимум inode.
+- `root_inode` — обычно 1 (`/`).
+- `free_head` — первый свободный блок (или 0 если нет).
+
+## 2. Формат inode
+
+```
+INODE|ino|type|mode|uid|gid|size|mtime|block0,block1,...|next_ino
+```
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `ino` | int | номер inode (1..inode_count) |
+| `type` | `f`/`d`/`l` | файл / каталог / симлинк |
+| `mode` | octal | 12-бит rwxrwxrwx + suid/sgid |
+| `uid`/`gid` | int | владелец и группа |
+| `size` | int | размер в байтах (несжатый) |
+| `mtime` | int | unix-time последнего изменения |
+| `block*` | list | список адресов блоков (см. 03) |
+| `next_ino` | int | цепочка свободных inode (0 = конец) |
+
+> inode сериализуется в одну строку; длина ограничена 4096.
+
+## 3. Каталоги
+
+Каталог — inode типа `d`. Содержимое — пары `name→ino`, сериализуются как:
+
+```
+DIR|ino|name1→ino1|name2→ino2|...
+```
+
+- Имена не содержат `/` и `|`.
+- `.` и `..` хранятся явно.
+
+## 4. Блоки и free list
+
+- Каждый блок адресуется как `(seg_idx<<16)|block_idx`.
+- Free list — односвязный список: `free_head → block → ... → 0`.
+- `free_head` хранится в суперблоке.
+- При выделении/освобождении MMC обновляет `next_block` указатель внутри строки блока (первые 8 символов — `"NEXT|xxxx"`).
+
+## 5. Операции ФС (минимум)
+
+| Операция | Действие MMC |
+|---|---|
+| `STAT path` | найти inode, вернуть поля |
+| `READ path off len` | найти блоки, склеить, Base64-декодировать, LZ4-распаковать, вернуть фрагмент |
+| `WRITE path off data` | найти/выделить блоки, сжать, записать, обновить size/mtime |
+| `LS dir` | прочитать DIR-запись, вернуть список |
+| `CHDIR path` | проверить `x` право, обновить cwd сессии |
+
+## 6. Ограничения и экономия
+
+- inode_count ≤ 256 (чтобы таблица влезала в SEG0).
+- BLOCK_SIZE = 512 → 8 блоков на сегмент.
+- Маленькие файлы (< 1 блока) упаковываются в один блок; остаток — slack.
+- Метаданные (inode, DIR, free list) — **только** в SEG0.
+
+См. `05-users-permissions.md` для формата passwd и проверок прав.
--- a/atlas_os/docs/05-users-permissions.md
+++ b/atlas_os/docs/05-users-permissions.md
@@ -0,0 +1,60 @@
+# 05 — Пользователи и права (Users & Permissions)
+
+## 1. Хранилище пользователей (SEG0)
+
+```
+PASSWD|uid|name|gid|home|hash
+```
+
+Пример:
+
+```
+PASSWD|0|root|0|/|-
+PASSWD|100|captain|10|/home/captain|abc123hash
+PASSWD|101|engineer|20|/home/engineer|def456hash
+```
+
+- `uid` / `gid` — положительные целые.
+- `hash` — простой хеш пароля (не криптографический, только для игровых целей).
+- Минимальный набор: `root` (uid=0) и хотя бы один пользователь.
+
+## 2. Права доступа (mode bits)
+
+```
+rwxrwxrwx  (9 бит) + suid/sgid (2 бита) = 12-бит octal
+```
+
+| Бит | Название | Проверка |
+|---|---|---|
+| `0400` | `r` owner | uid == file.uid |
+| `0200` | `w` owner | uid == file.uid |
+| `0100` | `x` owner | uid == file.uid |
+| `0040..0010` | `rwx` group | gid == file.gid |
+| `0004..0001` | `rwx` other | всегда |
+| `4000` | suid | (не используется в командах ls/cat) |
+| `2000` | sgid | (не используется) |
+
+## 3. Проверка прав (MMC)
+
+При каждом `STAT/READ/WRITE/LS/CHDIR` MMC:
+
+1. Получает `uid/gid` из сессии CMC.
+2. Загружает inode файла/каталога.
+3. Вычисляет effective mode:
+   - если uid == 0 (root) — полный доступ;
+   - иначе комбинирует owner/group/other биты.
+4. Возвращает `EACCES` при отказе.
+
+## 4. Аутентификация
+
+- Простейшая: `login name pass` сравнивает хеш.
+- Сессия CMC хранит текущие `uid/gid`.
+- `su` / `logout` — опциональные команды (см. `07-command-set.md`).
+
+## 5. Экономия
+
+- Таблица `PASSWD` ≤ 32 записи (чтобы влезала в SEG0).
+- Хеш — короткая строка (8–16 символов).
+- Права проверяются **только** при операциях ФС; CMC не дублирует проверки.
+
+См. `06-execution-model.md` — как сессия хранит uid/gid и cwd.
--- a/atlas_os/docs/06-execution-model.md
+++ b/atlas_os/docs/06-execution-model.md
@@ -0,0 +1,55 @@
+# 06 — Модель выполнения (Execution Model)
+
+## 1. Роли контроллеров
+
+| Контроллер | Что хранит в Lua | Что делает |
+|---|---|---|
+| **IOC** (n шт.) | цвет, буфер вывода, текущий пользователь | вывод на терминал, clear, приём ввода, login/logout |
+| **CMC** (1) | таблица предопределённых команд, сессии | парсинг, выполнение только встроенных команд, вызовы MMC |
+| **MMC** (1) | кэш inode (опц.), free list head | операции ФС, сжатие/распаковка, проверка прав |
+
+## 2. Сессия (в CMC)
+
+```
+session = {
+    uid = 100,
+    gid = 10,
+    cwd = "/home/captain",
+    env = { PATH = "/bin:/usr/bin" }
+}
+```
+
+- Сессия создаётся при `login`.
+- `cwd` обновляется командой `cd` (MMC проверяет `x`).
+- uid/gid передаются в каждый MEM-запрос.
+
+## 3. Модель команд
+
+- Контроллеры выполняют **только предопределённые команды**, зашитые в прошивку (Lua-код контроллера).
+- Пользователь **не может** выполнять произвольный Lua-код.
+- Доступные команды: `ls`, `ls -l`, `ls -la`, `cat`, `cd`, `login`, `logout` и другие, зарегистрированные в CMC.
+- Каждая команда — жёстко заданная функция в firmware CMC.
+
+## 4. Копроцессоры (опционально)
+
+Оставшиеся 5 контроллеров могут выполнять:
+
+- тяжёлые команды (`find`, `grep`, архивация);
+- фоновые задачи (логи, мониторинг);
+- параллельные сессии нескольких пользователей.
+
+Связь — по той же шине MEM/CMD.
+
+## 5. Очередь и сериализация
+
+- CMC допускает **только один активный MEM-запрос** одновременно.
+- Следующая команда ждёт ответа `OK`/`ERR`.
+- При отсутствии ответа — таймаут и ошибка.
+
+## 6. Экономия памяти Lua
+
+- Храните в сессии только **скаляры** (cwd — строка пути, uid/gid — числа).
+- Буферы файлов и большие таблицы — **только** в SEG (MMC).
+- Избегайте рекурсии и больших локальных таблиц в командах.
+
+См. `07-command-set.md` — конкретные команды и их аргументы.
--- a/atlas_os/docs/07-command-set.md
+++ b/atlas_os/docs/07-command-set.md
@@ -0,0 +1,71 @@
+# 07 — Набор команд (Command Set)
+
+## 1. Базовые правила
+
+- Команды регистрируются в CMC через `register(name, func, desc)`.
+- Аргументы — таблица строк после парсинга `gmatch("%S+")`.
+- Вывод — через `print(text)` (цвет текущий) или `printerror(text)`.
+- Ошибки возвращаются как `error("msg")` — перехватываются `pcall`.
+
+## 2. Обязательные команды (минимум v2.0)
+
+### `ls [path]`
+
+- Выводит список имён в cwd (или `path`).
+- Без `-l` — только имена, по одному на строку.
+
+### `ls -l [path]`
+
+- Длинный формат: `type mode uid gid size mtime name`.
+- Пример: `d rwxr-xr-x 0 0 4096 1712345678 bin`
+
+### `ls -la [path]`
+
+- То же, что `-l`, плюс скрытые файлы (начинающиеся с `.`).
+
+### `cat path`
+
+- Выводит содержимое файла (распакованное).
+- При ошибке (нет прав, нет файла) — `printerror`.
+
+### `cd [path]`
+
+- Меняет cwd сессии.
+- MMC проверяет право `x` на каталоге.
+- `cd` без аргумента → `$HOME` пользователя.
+
+## 3. Выходной формат `ls -l`
+
+```
+type perms uid gid size mtime name
+f rw-r--r-- 100 10 1234 1712345678 readme.txt
+d rwxr-xr-x 0 0 0 1712345678 bin
+```
+
+## 4. Расширяемость
+
+- Новые команды добавляются регистрацией в `commands`.
+- Имя — одно слово, без пробелов.
+- Описание — краткая строка для `help`.
+- Примеры: `login`, `su`, `logout`, `echo`, `clear`, `color`, `help`, `status`.
+
+## 5. Примеры ошибок
+
+| Ситуация | Сообщение |
+|---|---|
+| Нет файла | `cat: /foo: No such file or directory` |
+| Нет прав | `ls: /secret: Permission denied` |
+| Неизвестная команда | `Error: Unknown command. Type 'help' for list.` |
+
+## 6. Совместимость с прототипом
+
+Текущий `AtlasOS.lua` уже реализует `help`, `echo`, `clear`, `color`, `status`.
+Новые команды (`ls*`, `cat`, `cd`) добавляются по той же схеме:
+
+```lua
+register_command("ls", function(args) ... end, "List directory")
+```
+
+---
+
+**Конец комплекта документации v2.0**
--- a/atlas_os/docs/README.md
+++ b/atlas_os/docs/README.md
@@ -0,0 +1,116 @@
+# 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), окружение. |