<!-- reviewed: 2026-07-14 | v0.23.0 current-truth pass | canonical facts: docs/VERIFICATION-ANALYTICAL-DATA.md -->

# THE BOOK — the Cosmogonic Quantum Mechalogodrom, end to end

_The master index for the whole repository: a human- **and** AI-readable map of every document, every
module, and how it all fits. If you read one file to understand this project, read this one — then
follow the links. This is the **RAG book** (V37): a navigable table of contents over the living `docs/`
corpus, the auto-generated [file map](./FILE-MAP.md) (**325 source TypeScript modules**
— re-run `bun scripts/gen-filemap.ts` after adding modules), plus the build/run, data-flow,
troubleshooting and roadmap sections inline below._

> The same knowledge, in-world: open **❓ HELP ME NOW** (bottom-right dock) for grounded answers, or the
> **✦ AI** for freeform questions. The help corpus lives in [`src/ui/help-knowledge.ts`](../src/ui/help-knowledge.ts).

> **Canonical capability standard (adopted 2026-10-22):** [CQM-25](./alife/cqm-capability-profile.md),
> framework version 1.0.0, governs capability assessment and relevant feature plans across 25 stable
> axes. Use [the interactive profile](./alife/cqm-capability-profile.html) for scope, measurements,
> controls, falsifiers and pinned evidence. The nine-axis figures below are historical comparison
> context; they do not substitute for CQM-25 or imply a 25-axis ranking.
> Separate [provisional author estimates](./alife/cqm-capability-estimates.json) retain a declared
> heuristic rubric and submitted rationale; they are not calibrated benchmark results.

> **Current evidence boundary (2026-07-14):** the Tsotchke public census contains `23` repositories
> (`16` user + `7` organization), while the causal/runtime ledger contains `22` entries classified as
> `8 deep / 7 wired / 2 harvest / 4 fenced / 1 meta`, with `17/21` non-meta integrated.
> `homebrew-moonlab` is census-only deployment metadata; the shared
> organism-intelligence field passed goal-only, corpus-conditioned, fixed-family adaptation, repository
> causality, exclusion, numerical safety, three-process performance stability, and every named
> consumer-class counterfactual on a fresh disjoint 30-seed family. Uniform random-action baseline separation and
> aggregate-mapping specificity remain open. Separate gate-backed A-Life mechanisms underlie the historical
> 9-axis vector to `[4.0, 2.0, 3.4, 3.8, 4.5, 4.6, 4.4, 3.5, 4.0]`: breadth `3.8`, rank `#1/155`,
> population z `+3.236`, and peer z `+3.362`. The finite 26-form birth catalog plus differential
> selection demonstrates bounded active novelty against a frozen control, not unbounded open-ended
> evolution. The verified V4 Phase-A descendant publishes 1,152 rows over 64 frozen seeds: ordinary and
> Petri effects miss the fixed magnitude floor, the adaptive predictor loses to both controls, and Titans
> alone pass. It authorizes only bounded Titan game-policy semantic causality—no neural scaling, pooled
> result, numeric score, consciousness, or sentience uplift. See the
> [V4 report](./reports/ORGANISM-INTELLIGENCE-V4-RESULTS-2026-07-11.md) and preserved
> [V3 predecessor](./reports/2026-07-10-OPERATIONAL-ORGANISM-INTELLIGENCE-CAUSAL-AUDIT.md).

---

## 0. Quick start

```bash
bun install              # deps
bun dev                  # dev server → http://localhost:3000  (diagrams at /docs)
bun run check            # the FULL gate: prettier → tsc → oxlint → bun test → build
bun run bench            # microbenchmarks (record hot paths in docs/BENCHMARKS-2026-06-26.md)
bun scripts/gen-filemap.ts   # regenerate docs/FILE-MAP.md from module headers
```

Native C++ engine (optional, Windows + MinGW): `pwsh native/build.ps1 -Shot` → renders 4K specimen
plates. See [ADR-0007](./adr/0007-native-cpp-engine-and-live-physics-2026-06-26.md).

**Laws** (non-negotiable, enforced by the gate): one seed → one cosmos (determinism), full gate before
every commit, contracts over vibes. See [CLAUDE.md](../CLAUDE.md) and the three master files in `masters/`.

---

## 1. Orientation — what is this?

| Doc                                                                                                                           | What you'll learn                                                                                                                   |
| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [AUDIT-LOG.md](AUDIT-LOG.md)                                                                                                  | Centralized audit history (newest-first).                                                                                           |
| [PHILOSOPHY-2026-06-26.md](./PHILOSOPHY-2026-06-26.md)                                                                        | The aesthetic constitution: real math under every effect; every system reads AND writes another. **+ Tsotchke biologics paradigm.** |
| [CONTROLS-2026-06-26.md](./CONTROLS-2026-06-26.md)                                                                            | Every key, button, and gesture.                                                                                                     |
| [TECHNICAL-SPECIFICATION-2026-06-26.md](./TECHNICAL-SPECIFICATION-2026-06-26.md)                                              | The full technical spec sheet (also at `/spec`). **Updated with Tsotchke corpus, soup, sentience metrics.**                         |
| [reports/README.md](./reports/README.md) + [TSOTCHKE-INTEGRATION-MAP-2026-06-26.md](./TSOTCHKE-INTEGRATION-MAP-2026-06-26.md) | Historical report index plus the current Tsotchke wiring ledger and causal receipts.                                                |

## 2. Architecture & code

| Doc                                                                | What you'll learn                                                                |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| [ARCHITECTURE-2026-06-26.md](./ARCHITECTURE-2026-06-26.md)         | The layered system architecture + frame pipeline.                                |
| [MODULE-CONTRACTS-2026-06-26.md](./MODULE-CONTRACTS-2026-06-26.md) | The binding per-module spec (V1 + V2) — contract wins over any writer.           |
| [**FILE-MAP.md**](./FILE-MAP.md)                                   | **Auto-generated** map of all TypeScript modules (see header for current count). |
| [COMPLEXITY-2026-06-26.md](./COMPLEXITY-2026-06-26.md)             | Big-O of the hot paths.                                                          |
| §A below                                                           | The frame data-flow, inline.                                                     |

## 3. The world & its inhabitants

| Doc                                                          | What you'll learn                                                                                                                                                                                                                                      |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [ENTITY-SHEETS-2026-06-26.md](./ENTITY-SHEETS-2026-06-26.md) | The bestiary: biology / behaviour / silhouette / material / animation / world-meaning / economic-role for every class — entities, Shoggoths, Puppeteers, Titans, NHIs, the **SUPER CREATURE** (§5★), Leviathans, singularities, tribes, market agents. |
| Code: [`src/sim/`](./FILE-MAP.md)                            | entities · phyla · morphotypes · behaviors · shoggoths · puppet-masters · titans · nhi · leviathans · singularities · super-creature · super-body.                                                                                                     |

## 4. Living systems

| System                  | Doc / code                                                                                           | Summary                                                                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Economy + game theory   | [`src/sim/economy.ts`](../src/sim/economy.ts), [ENTITY-SHEETS §9](./ENTITY-SHEETS-2026-06-26.md)     | 2 currencies + 2 commodities; tâtonnement pricing, currency-adoption game, cartel, arbitrage, sanctions, black market, Vickrey auctions. |
| Cognition               | [`src/sim/cognition.ts`](../src/sim/cognition.ts), [`src/sim/ai/brains.ts`](../src/sim/ai/brains.ts) | The pure perceive→drive kernel; TinyMLP / MemoryRing / MarkovChain.                                                                      |
| Super creatures (GOAL5) | [ADR-0008](./adr/0008-super-creature-deep-mind-2026-06-26.md) + MODULE-CONTRACTS GOAL5               | 5 Archons (ORACLE-Σ etc): ~10k-param composite minds + Clifford/AST-1/HOT-1/HOT-4/narrative memory + wild bodies.                        |
| NHI Observatory         | [`src/ui/nhi-observatory.ts`](../src/ui/nhi-observatory.ts)                                          | The 9-view scientific window into a launched NHI's mind.                                                                                 |

## 5. Math & science

| Doc                                                                  | What you'll learn                                                    |
| -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| [ADR-0005 math stack](./adr/0005-math-stack-selection-2026-06-26.md) | Why these math libraries / techniques.                               |
| [AI-SUBSYSTEM-2026-06-26.md](./AI-SUBSYSTEM-2026-06-26.md)           | Pre-transformer technique index + live Copilot wiring.               |
| [BENCHMARKS-2026-06-26.md](./BENCHMARKS-2026-06-26.md)               | Measured hot-path costs (the PHYSICIST's law: measure, don't guess). |

## 6. AI & RAG (in-world helper)

| Doc / code                                                                                                     | What you'll learn                                                                           |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [AI-SUBSYSTEM-2026-06-26.md](./AI-SUBSYSTEM-2026-06-26.md)                                                     | The Copilot architecture + safety posture.                                                  |
| [COPILOT-PROVIDERS-2026-06-26.md](./COPILOT-PROVIDERS-2026-06-26.md)                                           | The failover provider chain + the offline 🩺 diagnostics.                                   |
| [`src/ui/help-knowledge.ts`](../src/ui/help-knowledge.ts)                                                      | The repo-grounded HELP corpus + retriever (the in-world RAG; safety constitution baked in). |
| [`src/server/copilot.ts`](../src/server/copilot.ts), [`src/server/ai-sandbox.ts`](../src/server/ai-sandbox.ts) | The server-side read-only AI + its sandbox.                                                 |

## 7. UI & design

| Doc                                                          | What you'll learn                                         |
| ------------------------------------------------------------ | --------------------------------------------------------- |
| [DESIGN-SYSTEM-2026-06-26.md](./DESIGN-SYSTEM-2026-06-26.md) | Tokens, typography, the glass aesthetic.                  |
| [DESIGN-SYSTEM-2026-06-26.md](./DESIGN-SYSTEM-2026-06-26.md) | Panel layouts, dock intent, tokens, and glass aesthetic.  |
| Code: [`src/ui/panel-dock.ts`](../src/ui/panel-dock.ts)      | The single bottom menu bar all inspector toggles live in. |

## 8. Data model (ERD / ERM / ERP)

| Doc                                                                                    | What you'll learn                             |
| -------------------------------------------------------------------------------------- | --------------------------------------------- |
| [ENTITY-SCHEMA-AND-MAPPINGS-2026-06-26.md](./ENTITY-SCHEMA-AND-MAPPINGS-2026-06-26.md) | Consolidated ERD / ERM / ERP source of truth. |
| [AUDIT-LOG.md](AUDIT-LOG.md)                                                           | The consolidated domain model from the audit. |

## 9. Decisions (ADRs)

[0001 Bun](./adr/0001-bun-runtime-2026-06-26.md) ·
[0002 three.js](./adr/0002-threejs-rendering-2026-06-26.md) ·
[0003 HTMX + Tailwind](./adr/0003-htmx-tailwind-ui-2026-06-26.md) ·
[0004 deterministic RNG](./adr/0004-deterministic-rng-2026-06-26.md) ·
[0005 math stack](./adr/0005-math-stack-selection-2026-06-26.md) ·
[0006 ASI graphics + language](./adr/0006-asi-graphics-and-language-stack-2026-06-26.md) ·
[0007 native C++ engine + physics](./adr/0007-native-cpp-engine-and-live-physics-2026-06-26.md) ·
[0008 super-creature deep mind](./adr/0008-super-creature-deep-mind-2026-06-26.md)

## 10. Project management & history

| Doc                                                                          | What you'll learn                                                            |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [KANBAN-2026-06-26.md](./KANBAN-2026-06-26.md)                               | The live board — done / in-progress / backlog.                               |
| [../ROADMAP-2026-06-26.md](../ROADMAP-2026-06-26.md)                         | Product direction — shipped / now / next horizons.                           |
| [RISK-REGISTER-2026-07-02.md](./RISK-REGISTER-2026-07-02.md)                 | Consolidated threat table (likelihood × impact, mitigation, residual).       |
| [VERIFICATION-ANALYTICAL-DATA.md](./VERIFICATION-ANALYTICAL-DATA.md)         | Test taxonomy, receipts law, coverage goals, known edges.                    |
| [BENCHMARKS-2026-06-26.md](./BENCHMARKS-2026-06-26.md)                       | Frame-budget measurements and hot-path performance truth.                    |
| [SECURITY-ARCHITECTURE-2026-07-02.md](./SECURITY-ARCHITECTURE-2026-07-02.md) | Threat model + hardening posture for a static, no-backend artifact.          |
| [../THIRD-PARTY-NOTICES.md](../THIRD-PARTY-NOTICES.md)                       | Dependency notices and supply-chain attribution.                             |
| [`scripts/reproduce.ts`](../scripts/reproduce.ts)                            | One-command third-party replication (determinism fingerprint + coupling).    |
| [../CHANGELOG.md](../CHANGELOG.md)                                           | Every increment, V1 → today, with verification receipts.                     |
| [500-POINT-INSPECTION-2026-06-26.md](./500-POINT-INSPECTION-2026-06-26.md)   | The deep inspection checklist.                                               |
| [AUDIT-LOG.md](./AUDIT-LOG.md)                                               | The centralized audit history (newest-first): reviews, fix-passes, findings. |

## 11. Brain, neurology, consciousness & sentience

| Doc                                                                                                                                        | What you'll learn                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CONSOLIDATED-22-MASTER-ASSESSMENT-CURRENT-2026-07-07.md](./CONSOLIDATED-22-MASTER-ASSESSMENT-CURRENT-2026-07-07.md)                       | **Consolidated 22-report master assessment:** comprehensive synthesis of all brain systems, consciousness theories, living entities, reasoning systems, scoring systems, and academic assessment. Explicitly `indicatorOnly` — computational proxies, never phenomenal sentience. |
| [CONSOLIDATED-22-FILE-AUDIT-CURRENT-2026-07-07.md](./CONSOLIDATED-22-FILE-AUDIT-CURRENT-2026-07-07.md)                                     | 22-file audit ledger: file-by-file audit of the 22 report artifacts and publication-surface gaps.                                                                                                                                                                                 |
| [BRAIN-NEUROLOGY-CONSCIOUSNESS-ENGINEERING-ASSESSMENT-2026-07-06.md](./BRAIN-NEUROLOGY-CONSCIOUSNESS-ENGINEERING-ASSESSMENT-2026-07-06.md) | Deep canonical brain/neuro/consciousness assessment: 4 AI reports merged, SSOT reconciliation, Butlin indicators, Thaler markers, academic scrutiny.                                                                                                                              |
| [NHSI-PROGRESS-DASHBOARD-2026-06-26.md](./NHSI-PROGRESS-DASHBOARD-2026-06-26.md)                                                           | Canonical NHSI scorecard: 100-faculty design, 25 Archons, 25 ToM organs, 10 emergence angles, Tsotchke depth, Butlin 8/14 met + 6/14 partial.                                                                                                                                     |
| [CONSOLIDATED-22-FILE-AUDIT-CURRENT-2026-07-07.md](./CONSOLIDATED-22-FILE-AUDIT-CURRENT-2026-07-07.md)                                     | Current report trust ledger; local-only archived drafts stay out of the public Pages artifact.                                                                                                                                                                                    |

---

## §A. Frame data-flow — how one tick happens

`World.step(dt)` (the composition root, [`src/world.ts`](../src/world.ts)) runs the pipeline each frame.
Heavy work is **cadenced** (runs on slow frames that scale with population) so the budget holds at scale:

```
input → audio analysis → weather → puppeteers → baseline grid rebuild (every 2f)
  → shoggoths → titans → leviathans → super-creature body → singularities
  → entities.update (births/deaths/behaviour/motion)
  → live-NHI exact grid + minds (every frame while present) · super-creature mind (every 4f)
  → connectome (cadence by population)
  → quantum circuit (30f) · economy clear (30f, after war→sanctions) · reaction-diffusion
  → graph communities (240f) / rank (600f) · atmosphere · environment · artifacts
  → telemetry panel (8f) · Observatory + Market + ARCHITECT + Superhero HUD (18f)
  → instanced pool sync (LAST, after every visual mutation) → render
```

Every randomness draw flows through a seeded `Rng` ([`src/math/rng.ts`](../src/math/rng.ts)); the economy
and super-creature use **isolated sub-streams** so they never perturb the core golden. See
[ARCHITECTURE-2026-06-26.md](./ARCHITECTURE-2026-06-26.md) for the full pipeline.

## §B. Build, run & verify

- **Dev**: `bun dev` (cwd MUST be the repo root — the Bun HTML-import bundler fails elsewhere). App at
  `:3000`, diagrams at `/docs`, spec at `/spec`, lab at `/lab`.
- **Gate** (before every commit): `bun run check` — prettier → `tsc` strict → oxlint → `bun test` → build.
- **Bench**: `bun run bench`; record new hot paths in [BENCHMARKS-2026-06-26.md](./BENCHMARKS-2026-06-26.md).
- **File map**: `bun scripts/gen-filemap.ts` regenerates [FILE-MAP.md](./FILE-MAP.md).
- **Native**: `pwsh native/build.ps1 -Shot` (MinGW + CMake; renders 4K plates).

## §C. Troubleshooting

| Symptom                               | Cause → fix                                                                                                                                                                                                   |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Blank app / nothing renders           | Bundler run from the wrong cwd — run `bun dev` from the repo root.                                                                                                                                            |
| Determinism test fails after a change | A new `Math.random`/`Date.now` in sim logic, or a stray `Rng` draw shifting the order — route randomness through `src/math/rng.ts` and keep new systems on a sub-stream.                                      |
| The ✦ AI is silent                    | It's offline/rate-limited — open its 🩺 diagnostics for the per-provider reason + restart; or use ❓ HELP (offline, repo-grounded). See [COPILOT-PROVIDERS-2026-06-26.md](./COPILOT-PROVIDERS-2026-06-26.md). |
| Native build segfaults                | See ADR-0007 — Jolt callbacks + member-init order; build with MinGW UCRT.                                                                                                                                     |
| Path errors on Windows                | This repo's path contains `[ ]` — use `-LiteralPath` in PowerShell, or the dedicated file tools.                                                                                                              |

## §D. Roadmap

Live in [KANBAN-2026-06-26.md](./KANBAN-2026-06-26.md). Open headline items: the **50,000-entity / 100-archetype** chaos-biome
scale-up (LOD · instancing · GPU-friendly neural controllers), the **Sorting meter-clock** UI relocation,
**superhero-mode deepening** (combat / camera-follow), **super-creature visual polish** (bloom), and
growing this book + the in-world RAG as new systems land.

---

_This book is generated-where-it-can-be and curated where it must be. The [file map](./FILE-MAP.md) is
machine-generated from the source; everything else is kept in lockstep with the code each increment —
that is the standing `DOCS-SYNC` discipline. Nothing here is secret, private, or sensitive._