# Mad Programmer Manual — Beast

Руководство для того, кто **всерьёз** решил разобраться в коде **Beast** («Существо Beast, пульт связи») и продолжить его развитие. Это не замена исходников и не дублирование каждого модуля — это **карта мышления**, принципы и **где искать правду** (в коде и в `about_*.md`).

---

## 1. Зачем этот документ

- Проект **большой**, связи **неочевидны**, порядок загрузки скриптов **критичен**.
- Много состояния живёт в **`window` / глобальных переменных** — без ментальной модели легко сломать то, что «случайно работало».
- Документ **`PROJECT_STATE_FOR_NEW_CHAT.md`** в корне — **сжатый снимок** для ИИ и людей; **этот мануал** шире: философия, слои, типичные ловушки, как растить фичи.

Если правите архитектуру — обновляйте **`PROJECT_STATE_FOR_NEW_CHAT.md`** и соответствующие **`beast/**/about_*.md`** (в т.ч. **`beast/_12_Sleep/about_sleep.md`** при изменениях режима сна).

---

## 2. Что такое Beast концептуально

**Beast** — браузерное приложение, моделирующее связку **организм ↔ стимулы ↔ ориентировочный рефлекс (ОР) ↔ процесс осмысления (ФО) ↔ эпизодическая память (ЭП)**.

Принципы:

1. **Время дискретно** — «пульс» (`global.cpuls`, `Cur_puls_val`). Почти всё важное привязано к пульсу или к событию UI между пульсами.
2. **Состояние тела** — виталы, выход из нормы, интегральная значимость, базовое состояние **Плохо / Норма / Хорошо** (`BadNormWell`).
3. **Контексты** — сокращённая эмоционально-поведенческая разметка (базовые контексты), из них строится «эмоция» и ветка дерева.
4. **Стимулы** — типизированы (мотивация, позитив, негатив, нейтрал); у глобальных id **нет коллизий** между массивами (см. `StimulusGlobalId_*`).
5. **ОР** — конкуренция стимулов по актуальности, порог «зрелости» семантики (`OR_well_known`), исключения для отдельных сценариев (см. код ОР).
6. **ФО** — не один вызов, а **реестр циклов** (`ConsciousnessCycles`), диспетчер шагов, главный vs фоновые циклы, `expired`, лог цикла.
7. **Память** — семантика (значимость по условиям), эпизоды (кадры с `effect`, стимул, действие, ответ оператора), абстракции и правила для высоких уровней.

Реализация этой схемы **распределена** по папкам `beast/_1_` … `beast/_12_` — номер — ориентир по слою (от «тела» к «сознанию, памяти и режиму сна»).

---

## 3. Карта каталогов `beast/` (слои)

| Папка | Роль |
|--------|------|
| `_1_Genetic_vitals` | Виталы, шкалы, шок, смерть, подготовка к расчётам |
| `_2_Genetic_basic_styles` | Базовые контексты, стили, **`prepare.js`**: `BadNormWell`, `GetBadNormWell`, `SetWellForHolding`, удержания, `getDiffImportance` |
| `_3_perception` | Списки стимулов, UI стимулов, активация, связь с ОР |
| `_4_actions` | `BasicActions`, эффекторы, зеркальные действия |
| `_5_Genetic__reflexes` | Таблицы рефлексов, **`genetic_reflexes_engine.js`**: `processGeneticReflexes`, `runActionImage`, `startAction` |
| `_5_2_synonyms_reflexes` | Условные (синонимические) рефлексы |
| `_6_semantic_memory` | FinalImage, семантический индекс, регистрация опыта |
| `_7_perception_tree` | Дерево восприятия, терминальный узел = «ветка» для ЭП и автоматизмов |
| `_8_Hippocampus` | Гиппокамп, **`orientation_reflex.js`** — ОР |
| `_9_Conscience` | Инфокартина, детекторы, **уровни сознания 2–4**, гештальт, абстракции, канал внимания |
| `_10_Episodic_memory` | Кадры ЭП, ожидание ответа, закрытие кадра, `effect` |
| `_10_actions_image` | Образы действия (ОД), связь с целями |
| `_11_Automatizms` | Автоматизмы по веткам, привязка к ОД |
| `_12_Sleep` | Режим сна (контекст «Сон», ограничение стимулов, авто-сон по счётчику финовых циклов), сновидения по пустым кадрам ЭП |

Плюс: **`beast/puls.js`** — сердце тика; **`beast/docs/`** — проектные заметки и анализ.

---

## 4. Точка входа и священный порядок скриптов

- Вход: **`index.html`** в корне репозитория.
- В конце **`body`** порядок подключения **`index.html`** — **контракт**. Если переставить файлы, часть глобалов будет `undefined` в момент инициализации.

Правило: **кто от кого зависит, тот ниже**. Примеры:

- `consciousness_dispatcher.js` задаёт реестр циклов и диспетчеризацию.
- `gestalt.js` должен быть **до** `episodic_memory.js` (хук `Gestalt_onEpisodeFeedbackClosed` в `closeLastFrame`).
- Модули «уровней» сознания зависят от инфокартины и ЭП.

**Практика:** перед крупным рефакторингом — экспорт списка `<script src=...>` в `index.html` и проверка цепочки вручную.

---

## 5. Пульс: что происходит «каждый такт»

Файл **`beast/puls.js`** (и связанные вызовы) задаёт:

- инкремент счётчика пульса;
- обновление виталов/контекстов (`getActiveBasicContexts` и др.);
- при активном сне — визуал стимулов и **`SleepDreams_onPulse`** (машина сновидений **до** диспетчера ФО, чтобы в том же такте отработал `info_fantasizming` сонового главного цикла);
- генетические и условные рефлексы;
- **диспетчер сознания** (`Consciousness_runOneStep` и т.п.);
- эпизодическую память (тики ожидания, закрытие кадров по сценарию).

**Принцип:** если логика «должна жить в пульсе», не дублируйте её только в UI — UI и пульс должны согласоваться, иначе гонки (например, инфокартина vs рефлекс).

---

## 6. Глобальное состояние: дисциплина

1. **`beast/about_global_variables.md`** — справочник по ключевым `window.*`. Перед добавлением нового глобала подумайте: **нужен ли он в `window`**, или достаточно замыкания в модуле.
2. **Именование** — в проекте уже есть смесь русских комментариев и английских идентификаторов; новый код лучше **вписывать в существующий стиль** файла, который вы правите.
3. **Сериализация** — виталы, дерево, семантика, ЭП, цели, ОД, автоматизмы частично уходят в **IndexedDB** / файлы. Любая новая сущность в `window` должна либо **попадать в save/load**, либо явно быть «чисто сессионной» (и это задокументировать).

---

## 7. Поток данных «как в учебнике»

Упрощённо (реальность всегда с ветвлениями):

```
Виталы → BadVitalsValue / контексты → BasicContextsActived
       → BadNormWell, эмоция (Emotions_*)
       → путь дерева восприятия → terminal node (branchId)
Стимулы (UI) → глобальные id стимулов → FinalImage
       → ОР (конкуренция, пороги) → actual_stimul_ID
       → stimuls_consciousness → циклы ФО / автоматизмы
       → кадр ЭП, effect, закрытие кадра → семантика / абстракции / гештальт
```

**Ориентировочный рефлекс** (`orientation_reflex.js`) — не «украшение», а **центральный узел**: от него зависят запуск ФО, блокировка рефлекса на пару пульсов, очередь отложенных рефлексов, второй проход после ответа в ожидании (см. `about_episodic_memory_rules.md`).

---

## 8. Инфокартина и детекторы

- **`informing.js`** — структура `InfoPicture`, обновление представления.
- **`info_detectors.js`** — вычисляемые поля: `criticalVital`, `badState`, режимы игры/обучения и т.д. Ситуации в **`situatioms_tree.js`** собираются из **компонентов детекторов**.

**Принцип:** детекторы должны быть **идемпотентны относительно своих входов** (виталы, `BadNormWell`, флаги). Если вводите «перекрытие» смысла (например, еда гасит индикатор критичности при Хорошо), документируйте в коде **кратко**, почему так.

---

## 9. Уровни сознания (ур.2–4) — куда смотреть

| Уровень | Файл | Заметка |
|---------|------|---------|
| Диспетчер, реестр циклов, лог | `consciousness_dispatcher.js` | `Consciousness_cycleAppendLog`, `expired`, `force` |
| Канал внимания, вход ФО | `conscious_attention_channel.js` | прерывания, «тишина мысли» |
| Ур.2 | `conscience_level_2.js` | выживание, цели, ответ оператора, связка с ЭП |
| Ур.3 | `conscience_level_3.js` | пайплайн правил, ожидание ЭП, гейты мотора |
| Ур.4 / гештальт | `conscience_level_4.js`, `gestalt.js` | см. `about_gestalt.md` |
| Общие хелперы | `infofunctions.js` | `info_automatismWithEpisodeFeedbackAndExpireCycle`, поиск правил ЭП |

Подробности и актуальные соглашения — **`beast/_9_Conscience/about_conscience.md`**, **`about_adaptivity_levels_2_4.md`**.

---

## 10. Эпизодическая память и образы действия

- **`episodic_memory.js`** — кадры, ожидание, `effect`, связь с оператором.
- **`actions_image.js`** — ОД (массив `actionIds`, `finalImageId`). Цели жизненного опыта в **`goals.js`** ссылаются на ОД; при загрузке состояния из IndexedDB **нельзя** терять согласованность id.

**Принцип:** если добавляете новую «точку правды», определите её **один раз** (как в случае умолчательной цели «Плачь» и ОД с `actionIds: [1]`).

---

## 11. Как отлаживать «без сумасшествия»

1. **`global.cpuls` / `Cur_puls_val`** — номер пульса в логах.
2. **`Consciousness_cycleAppendLog`** — человекочитаемый лог главного цикла; помните про **`expired`** и **`{ force: true }`**.
3. **Тестовый режим ЭП** (`EpisodicMemory_testMode`) — алерты ОР (см. `orientation_reflex.js`).
4. Блок **«Активность Beast»** — текст из генетических/условных рефлексов и автоматизмов (`setBeastActivityText`).

---

## 12. Типичные ловушки (Madness Checklist)

| Симптом | Возможная причина |
|---------|-------------------|
| «Ничего не происходит» при стимуле | ОР не прошёл порог `OR_well_known`, нет терминального узла дерева, пустые кандидаты |
| Дублирующиеся объекты в `window` | второй `window.StimulMotivarion_GeneticReflexes = {...}` перезаписал первый |
| Цель «Плачь», а действие другое | **рассинхрон ОД** после загрузки IndexedDB и `actionImageId` цели |
| Генетический рефлекс не срабатывает | `automatismRanForBranchIds`, блокировка ОР, очередь отложенных рефлексов |
| Лог цикла пустой в начале | `OrientationReflex_anyStimulusReadyForOr` и условия авто-лога в диспетчере |

---

## 13. Как безопасно развивать систему

### Новый стимул

1. Добавить в `stimuls.js` в нужный массив.
2. Прописать эффекты в **`genetic_reflexes.js`** (внутренние и/или моторные таблицы).
3. Убедиться, что **глобальный id** строится через `StimulusGlobalId_toGlobal`.
4. При необходимости — правила в UI (`stimuls_ui.js`).

### Новое действие

1. `BasicActions` в **`effectors.js`** (если не зеркальное).
2. Связь с ОД — через `ActionImages_registerReaction` / `getOrCreateActionImageId`.

### Новая ветка логики ФО

1. Сначала — **где в пайплайне** (ур.2 vs 3, до или после ожидания ЭП).
2. Не ломать **гейт** `awaitingAutomatismEpisodeFeedback` без чтения `conscience_level_3.js` и `about_conscience.md`.

### Персистентность

1. Найти аналогичный модуль с `serialize/apply` и IndexedDB.
2. Не забыть **порядок загрузки** — после восстановления ОД обновить зависимые сущности (пример: цели и ОД).

---

## 14. Режим сна (`beast/_12_Sleep`)

- **Назначение:** при «спящем» Beast активен только базовый контекст «Сон», почти все стимулы заблокированы (исключения — Наказание, Вопль, Сирена, Рычание, Огонь); **авто-сон** при `ConsciousnessFinCyclesTotal > 100` (даже при критических виталах — контексты переопределяются в `prepare.js`).
- **Сновидения:** перебор **пустых** кадров ЭП (есть стимул и ОД, нет ответного стимула и числового `effect`), новые → старые; на кадр — главный цикл в **`passive`** и те же **`info_fantasizming`** / **`PassiveMode_processUnderstandingModels`**, что в обычном пассиве; затем реализация кадра и лимит реконструкций; **`SleepMode_exit(true)`** удаляет **фоновые** циклы ФО (`Consciousness_deleteAllBackgroundCycles`). Ручной выход из сна фон не трогает.
- **Документация:** **`beast/_12_Sleep/about_sleep.md`**; глобалы — раздел в **`beast/about_global_variables.md`**; порядок скриптов — комментарий в **`index.html`** (`sleep_dream_process.js` после `fantasizming.js`).

---

## 15. Что читать дальше (порядок)

1. **`PROJECT_STATE_FOR_NEW_CHAT.md`** — снимок архитектуры.
2. **`beast/about_global_variables.md`** — словарь глобалов.
3. **`beast/_10_Episodic_memory/about_episodic_memory_rules.md`** — ОР, ожидание, цепочки.
4. **`beast/_8_Hippocampus/about_hippocampus.md`**
5. **`beast/_9_Conscience/about_conscience.md`**
6. **`beast/_6_semantic_memory/about_semantic_memory.md`**
7. **`beast/_11_Automatizms/about_automatizms.md`**
8. **`beast/_12_Sleep/about_sleep.md`** — если трогаете сон, стимулы в сне или сновидения.
9. Остальные `about_*.md` по задаче.

---

## 16. Этика «сумасшедшего программиста»

- **Code is truth** — комментарий и `about_*` могут отстать; при противоречии **верьте коду** и исправляйте документацию.
- **Маленькие шаги** — один сценарий, один тест в голове, один коммит в душе.
- **Не размножайте глобалы** без нужды.
- **Уважайте пульс** — если поведение «должно быть сразу после клика», проверьте порядок: UI → виталы/контексты → ОР → пульс.

---

*Версия мануала: 2026-03-21 (раздел о режиме сна `_12_Sleep`). Проект Beast — живой; при существенных изменениях архитектуры обновите этот файл и `PROJECT_STATE_FOR_NEW_CHAT.md`.*
