# 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`.