Mad Programmer Manual — Beast

A guide for anyone who has seriously decided to understand the Beast codebase (“Beast creature, comms console”) and keep evolving it. This is not a substitute for sources or a dump of every module — it is a mental map, principles, and where truth lives (in code and about_*.md).

1. Why this document

• The project is large, links are non-obvious, script load order is critical.
• Much state lives in window / globals — without a mental model you can break what “happened to work”.
• PROJECT_STATE_FOR_NEW_CHAT.md at the repo root is a compressed snapshot for AI and humans; this manual is broader: philosophy, layers, common pitfalls, how to grow features.

If you change architecture, update PROJECT_STATE_FOR_NEW_CHAT.md and the relevant beast/**/about_*.md (including beast/_12_Sleep/about_sleep.md when sleep mode changes).

2. What Beast is, conceptually

Beast is a browser app modeling organism ↔ stimuli ↔ orientation reflex (OR) ↔ comprehension process (consciousness cycles) ↔ episodic memory (EM).

Principles:

1. Time is discrete — the “pulse” (global.cpuls, Cur_puls_val). Almost everything important ties to a pulse or a UI event between pulses.
2. Body state — vitals, deviation from norm, integral importance, base state Bad / Normal / Well (BadNormWell).
3. Contexts — compact emotional-behavioral tags (basic contexts); “emotion” and tree branch are built from them.
4. Stimuli — typed (motivation, positive, negative, neutral); global ids do not collide across arrays (see StimulusGlobalId_*).
5. OR — stimulus competition by salience, semantics “maturity” threshold (OR_well_known), exceptions for some scenarios (see OR code).
6. Consciousness — not one call but a cycle registry (ConsciousnessCycles), step dispatcher, main vs background cycles, expired, cycle log.
7. Memory — semantics (importance by condition), episodes (frames with effect, stimulus, action, operator answer), abstractions and rules for higher levels.

This layout is spread across beast/_1_ … beast/_12_ — the number hints at the layer (from “body” toward “consciousness, memory, and sleep”).

3. beast/ directory map (layers)

Also: beast/puls.js — tick heart; beast/docs/ — project notes and analysis.

4. Entry point and sacred script order

• Entry: repo root index.html.
• At end of body, index.html script order is a contract. Reorder files and some globals are undefined at init.

Rule: dependents load below dependents-on. Examples:

• consciousness_dispatcher.js defines the cycle registry and dispatch.
• gestalt.js must be before episodic_memory.js (hook Gestalt_onEpisodeFeedbackClosed in closeLastFrame).
• Consciousness “level” modules depend on info picture and EM.

Practice: before a big refactor, export the <script src=...> list from index.html and verify the chain by hand.

5. Pulse: what happens each tick

beast/puls.js (and related calls) drives:

• pulse counter increment;
• vitals/context updates (getActiveBasicContexts, etc.);
• when sleep is active — stimulus visuals and SleepDreams_onPulse (dream machine before consciousness dispatcher so the same tick can run sleep main cycle info_fantasizming);
• genetic and conditioned reflexes;
• consciousness dispatcher (Consciousness_runOneStep, etc.);
• episodic memory (wait ticks, frame closure by scenario).

Principle: if logic “belongs in the pulse”, do not duplicate it only in UI — UI and pulse must agree or you get races (e.g. info picture vs reflex).

6. Global state: discipline

1. beast/about_global_variables.md — key window.* reference. Before adding a global, ask: does it need window, or is a module closure enough.
2. Naming — the project mixes Russian comments and English identifiers; new code should match the file you edit.
3. Serialization — vitals, tree, semantics, EM, goals, AI, automatisms partly go to IndexedDB / files. Any new window entity must either enter save/load or be explicitly “session-only” (document that).

7. Data flow “textbook style”

Simplified (reality always branches):

Vitals → BadVitalsValue / contexts → BasicContextsActived
       → BadNormWell, emotion (Emotions_*)
       → perception tree path → terminal node (branchId)
Stimuli (UI) → global stimulus ids → FinalImage
       → OR (competition, thresholds) → actual_stimul_ID
       → stimuls_consciousness → consciousness cycles / automatisms
       → EM frame, effect, frame close → semantics / abstractions / gestalt

Orientation reflex (orientation_reflex.js) is not trim — it is the hub: consciousness start, reflex block for a couple of pulses, delayed reflex queue, second pass after answer during waiting (see about_episodic_memory_rules.md).

8. Info picture and detectors

• informing.js — InfoPicture structure, view updates.
• info_detectors.js — computed fields: criticalVital, badState, play/learn modes, etc. Situations in situatioms_tree.js are built from detector components.

Principle: detectors should be idempotent in their inputs (vitals, BadNormWell, flags). If you layer meaning (e.g. food clears critical under Well), document briefly in code why.

9. Consciousness levels (2–4) — where to look

Details and current conventions — beast/_9_Conscience/about_conscience.md, about_adaptivity_levels_2_4.md.

10. Episodic memory and action images

• episodic_memory.js — frames, waiting, effect, operator link.
• actions_image.js — AI (actionIds, finalImageId). Life-experience goals in goals.js reference AI; when loading state from IndexedDB do not break id consistency.

Principle: if you add a new “single source of truth”, define it once (as with default goal “Cry” and AI with actionIds: [1]).

11. Debugging without going mad

1. global.cpuls / Cur_puls_val — pulse number in logs.
2. Consciousness_cycleAppendLog — human-readable main cycle log; remember expired and { force: true }.
3. EM test mode (EpisodicMemory_testMode) — OR alerts (see orientation_reflex.js).
4. “Beast activity” block — text from genetic/conditioned reflexes and automatisms (setBeastActivityText).

12. Common pitfalls (Madness Checklist)

13. How to grow the system safely

New stimulus

1. Add to the right array in stimuls.js.
2. Wire effects in genetic_reflexes.js (internal and/or motor tables).
3. Ensure global id is built via StimulusGlobalId_toGlobal.
4. If needed — UI rules (stimuls_ui.js).

New action

1. BasicActions in effectors.js (if not mirror).
2. Link to AI via ActionImages_registerReaction / getOrCreateActionImageId.

New consciousness logic branch

1. First — where in the pipeline (lv.2 vs 3, before or after EM wait).
2. Do not break gate awaitingAutomatismEpisodeFeedback without reading conscience_level_3.js and about_conscience.md.

Persistence

1. Find a similar module with serialize/apply and IndexedDB.
2. Remember load order — after restoring AI, update dependents (e.g. goals and AI).

14. Sleep mode (beast/_12_Sleep)

• Purpose: when Beast “sleeps”, only basic context “Sleep” is active, almost all stimuli blocked (exceptions — Punishment, Howl, Siren, Growl, Fire); auto-sleep when ConsciousnessFinCyclesTotal > 100 (even with critical vitals — contexts overridden in prepare.js).
• Dreams: iterate empty EM frames (stimulus and AI present, no response stimulus and no numeric effect), new → old; per frame — main cycle in passive and the same info_fantasizming / PassiveMode_processUnderstandingModels as normal passive; then frame realization and reconstruction limit; SleepMode_exit(true) removes background consciousness cycles (Consciousness_deleteAllBackgroundCycles). Manual wake does not touch background.
• Docs: beast/_12_Sleep/about_sleep.md; globals — section in beast/about_global_variables.md; script order — comment in index.html (sleep_dream_process.js after fantasizming.js).

15. What to read next (order)

1. PROJECT_STATE_FOR_NEW_CHAT.md — architecture snapshot.
2. beast/about_global_variables.md — globals glossary.
3. beast/_10_Episodic_memory/about_episodic_memory_rules.md — OR, waiting, chains.
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 — if you touch sleep, sleep stimuli, or dreams.
9. Other about_*.md as needed for the task.

16. “Mad programmer” ethics

• Code is truth — comments and about_* can lag; on conflict trust code and fix docs.
• Small steps — one scenario, one mental test, one commit in spirit.
• Do not multiply globals without need.
• Respect the pulse — if behavior “must be right after click”, check order: UI → vitals/contexts → OR → pulse.

Manual version: 2026-03-21 (sleep mode _12_Sleep section). Beast is a living project; on major architecture changes update this file and PROJECT_STATE_FOR_NEW_CHAT.md.