Mechalogodrom Docs — Report

cosmogonic-quantum-mechalogodrom/
├─ server.ts            Bun.serve fullstack host: bundles /, /docs, serves /lab + /api/{health,audit}
├─ index.html           the dome (/) — app shell, panels, observatory DOM, touch controls
├─ docs.html            this report (/docs) — architecture, ERD/ERM/ERP, eras (mermaid inline)
├─ lab/
│   └─ quantum-wildbeyond.html  self-contained p5.js lab, 4 pages of 3D data-visuals (CDN-only, not bundled)
├─ src/
│   ├─ main.ts           browser entry: boots the World from index.html
│   ├─ world.ts          composition root: owns SimState, builds SimContext, ticks every system per frame
│   ├─ types.ts          the type hub — SimState, SimContext, TelemetrySnapshot, MorphType
│   ├─ docs-page.ts      this page's entry: initializes mermaid (dark theme) and renders the diagrams
│   ├─ core/
│   │   ├─ engine.ts      three.js renderer, scene, camera, lighting rig
│   │   └─ quality.ts     detectQuality — device tier ladder (phone..ultra), entity caps, throttles
│   ├─ sim/              the simulation systems (V1 core + V2 wildbeyond + V3 pantheon + V4 atmosphere)
│   │   ├─ constants.ts   leaf — arena scale, behavior names, morph count, tuning tuples
│   │   ├─ geometry-cache.ts 41 shared geometries reused across all meshes
│   │   ├─ morphotypes.ts deterministic creature templates (100 legacy / 250 phylum-mode)
│   │   ├─ phyla.ts       10 phyla — hue bands, geometry families, behavior pools, home sectors
│   │   ├─ behaviors.ts   26 behavioral fields driving per-entity motion
│   │   ├─ algorithms.ts  25 visible sorting-field algorithms, each a distinct spatial signature
│   │   ├─ entities.ts    EntityManager — births, deaths, behavior dispatch, RD scars on death
│   │   ├─ instanced-entities.ts instanced PBR pools (per-instance color + emissive vec4)
│   │   ├─ shoggoths.ts   drifting Lorenz-ish predators with tendrils
│   │   ├─ puppet-masters.ts 3 NPC intelligences gating quantum circuit sequences
│   │   ├─ titans.ts      10 colossal economies waging an iterated prisoner's dilemma
│   │   ├─ weather.ts     weather state machine (CLEAR..FOG..STORM..VOID..AURORA)
│   │   ├─ quantum.ts     QuantumCloud — point cloud that implodes on register collapse
│   │   ├─ qcircuit.ts    QuantumCircuitSystem — gate sequences, bands to the cloud
│   │   ├─ reaction-diffusion.ts Gray-Scott 128x128 field, ground emissiveMap
│   │   ├─ graph-mind.ts  graphology Louvain communities + PageRank over the connectome
│   │   ├─ connectome.ts  neural link graph between nearby entities
│   │   ├─ constellations.ts d3-delaunay Voronoi sectors over fixed monolith sites
│   │   ├─ lore.ts        sha256-seeded name generator (sectors, tribes, stars, omens)
│   │   ├─ analytics.ts   simple-statistics windows — trend, z-omens
│   │   ├─ atmosphere.ts  alien sky dome, haze bands, particulate layer, aurora curtain
│   │   ├─ viz3d.ts       in-scene holographic data sculptures (phylum towers, titan obelisks)
│   │   └─ environment.ts ground, light rig, audio-reactive shimmer
│   ├─ math/            pure deterministic leaves (no three.js, fully bun-testable)
│   │   ├─ rng.ts        mulberry32 seeded Rng — the single source of all sim randomness
│   │   ├─ scalar.ts     clamp, lerp, TAU, dist2XZ and friends
│   │   ├─ spatial-hash.ts uniform grid for neighbor queries
│   │   ├─ quantum.ts    QuantumRegister — 2^n complex amplitudes, gates, measurement
│   │   └─ games.ts      prisoner's-dilemma payoff + replicator-dynamics helpers
│   ├─ audio/
│   │   ├─ songs.ts      leaf — 6 dramatic songs (chords, melodies, character)
│   │   ├─ engine.ts     AudioEngine — WebAudio synthesis, sub-bass, arpeggios, LFO swells
│   │   └─ analysis.ts   AudioBands — AnalyserNode tap to bass/mid/treble/level
│   ├─ ui/
│   │   ├─ input.ts      keys, mouse look, zoom, touch joystick + radial wheel accumulators
│   │   ├─ hud.ts        heads-up readouts (sector, weather, algorithm, lore)
│   │   ├─ panels.ts    collapsible glass panels (telemetry, control, audit)
│   │   ├─ graphs.ts     Sparkline — small canvas time-series
│   │   └─ observatory.ts 4-page, 16-canvas live data observatory
│   ├─ logging/
│   │   ├─ logger.ts     leaf ring logger (client + server)
│   │   └─ audit.ts      AuditTrail — fire-and-forget POST /api/audit
│   ├─ memory/
│   │   └─ store.ts      MemoryStore — persisted seed/song/sessions across reloads
│   └─ styles/
│       └─ app.css      responsive system — phone sheets, foldable, tablet, TV 10-foot
├─ docs/
│   ├─ ARCHITECTURE.md  module graph + composition narrative (mirrors this page)
│   ├─ ERD.md           entity-relationship source for the diagram below
│   ├─ MODULE-CONTRACTS.md binding per-module spec (V1..V6) — contract wins over vibes
│   ├─ PHILOSOPHY.md     aesthetic constitution — real math under every effect
│   ├─ DESIGN-SYSTEM.md  color, type, panel + wireframe conventions
│   ├─ WIREFRAMES.md     layout sketches for the dome + observatory
│   ├─ COMPLEXITY.md     per-system complexity budgets
│   ├─ BENCHMARKS.md     recorded hot-path measurements + ultra-tier calibration
│   ├─ adr/             architecture decision records (Bun, three.js, HTMX, seeded rng, math stack)
│   ├─ reference/       domain library catalog + math-libs survey
│   └─ diagrams/        exported diagram assets
├─ tests/             24 bun test suites — determinism, NaN-stability, per-system invariants
├─ bench/             7 mitata micro-benchmarks for the hot paths
├─ masters/           3 master persona XML files — Executor, Architect, Physicist (the discipline)
├─ legacy/            the original single-file artifact, preserved verbatim — never edited
├─ scripts/
│   └─ build.ts        Bun build pipeline (HTML bundling + Tailwind)
├─ public/            static assets served as-is
├─ .github/workflows/  CI — the full check gate on push
├─ package.json         deps + scripts (dev, check, bench)
├─ tsconfig.json        strict TypeScript configuration
├─ bunfig.toml          Bun config — Tailwind plugin wiring
├─ .prettierrc          prettier — 100 cols, single quotes, semicolons
├─ CHANGELOG.md         version history V1..V6
└─ README.md            project overview + quickstart

graph TD
  subgraph SERVERL["Server"]
    SRV["server.ts (Bun.serve)"]
    IDX["index.html (/)"]
    DOC["docs.html (/docs)"]
    LAB["lab/quantum-wildbeyond.html (/lab, static p5.js)"]
    RING["in-memory audit ring (200)"]
  end
  subgraph ENTRY["Entry and composition"]
    MAIN["src/main.ts"]
    WORLD["src/world.ts (composition root)"]
  end
  subgraph COREL["src/core"]
    QUAL["quality.ts (detectQuality)"]
    ENG["engine.ts (renderer, scene, camera)"]
  end
  subgraph SIML["src/sim (V1)"]
    CONST["constants.ts (leaf)"]
    GEO["geometry-cache.ts (41 shared geometries)"]
    MORPH["morphotypes.ts (100 morphotypes)"]
    ALG["algorithms.ts (25 sort fields)"]
    BEH["behaviors.ts (26 fields)"]
    ENT["entities.ts (EntityManager)"]
    SHOG["shoggoths.ts"]
    PUP["puppet-masters.ts"]
    WEA["weather.ts"]
    QUA["quantum.ts (QuantumCloud)"]
    CONN["connectome.ts"]
    ENV["environment.ts"]
  end
  subgraph SIMV2["src/sim (Wildbeyond V2)"]
    QC["qcircuit.ts (QuantumCircuitSystem)"]
    RD["reaction-diffusion.ts (Gray-Scott 128x128)"]
    GM["graph-mind.ts (graphology louvain + pagerank)"]
    CONS["constellations.ts (d3-delaunay)"]
    LORE["lore.ts (sha256 lore)"]
    ANA["analytics.ts (simple-statistics)"]
  end
  subgraph MATHL["src/math (leaves)"]
    SCAL["scalar.ts"]
    RNG["rng.ts (mulberry32)"]
    GRID["spatial-hash.ts"]
    QREG["quantum.ts (QuantumRegister)"]
  end
  subgraph AUDIOL["src/audio"]
    SONGS["songs.ts (leaf)"]
    AUD["engine.ts (AudioEngine)"]
    BANDS["analysis.ts (AudioBands)"]
  end
  subgraph UIL["src/ui"]
    INPUT["input.ts (keys, look, zoom)"]
    HUD["hud.ts"]
    PANELS["panels.ts"]
    GRAPHS["graphs.ts (Sparkline)"]
  end
  subgraph PERSIST["src/logging + src/memory"]
    LOGGER["logger.ts (leaf ring)"]
    TRAIL["audit.ts (AuditTrail)"]
    MEM["store.ts (MemoryStore)"]
  end

  SRV --> IDX
  SRV --> DOC
  SRV --> LAB
  SRV --> RING
  IDX --> MAIN
  MAIN --> WORLD
  WORLD --> QUAL
  WORLD --> ENG
  WORLD --> GEO
  WORLD --> MORPH
  WORLD --> ALG
  WORLD --> ENT
  WORLD --> SHOG
  WORLD --> PUP
  WORLD --> WEA
  WORLD --> QUA
  WORLD --> CONN
  WORLD --> ENV
  WORLD --> QC
  WORLD --> RD
  WORLD --> GM
  WORLD --> CONS
  WORLD --> ANA
  WORLD --> AUD
  WORLD --> BANDS
  WORLD --> INPUT
  WORLD --> HUD
  WORLD --> PANELS
  WORLD --> MEM
  WORLD --> TRAIL
  WORLD --> GRID
  WORLD --> RNG
  ENT --> BEH
  BEH --> SCAL
  BEH --> CONST
  MORPH --> CONST
  ENV --> CONST
  PANELS --> GRAPHS
  AUD --> SONGS
  QC --> QREG
  GM --> CONN
  GM --> ENT
  CONS --> LORE
  BANDS --> AUD

  QC -. "bands every 6f, collapse implodeAt" .-> QUA
  RD -. "DataTexture as ground emissiveMap" .-> ENV
  ANA -. "lore-named omens, abs(z) > 2.5" .-> TRAIL
  PUP -. "PuppetEvent gate sequences" .-> QC
  ENT -. "onDeath: rd.perturb at ground UV" .-> RD
  GM -. "setCommunityOf tribe palette" .-> CONN
  BANDS -. "bass: setAudioBass rig shimmer" .-> ENV
  BANDS -. "treble: cell pulse" .-> CONS
  BANDS -. "level: setBreath point size" .-> QUA
  TRAIL -. "fire-and-forget POST /api/audit" .-> RING
  IDX -. "HTMX GET /api/audit every 5s" .-> SRV
        

erDiagram
  MORPHOTYPE ||--o{ ENTITY : "stamps"
  BEHAVIOR ||--o{ MORPHOTYPE : "drives"
  PHYLUM ||--o{ MORPHOTYPE : "templates"
  SHOGGOTH }o--o{ ENTITY : "consumes / corrupts"
  PUPPET_MASTER }o--o{ ENTITY : "commands"
  TITAN }o--o{ ENTITY : "harvests / conscripts"
  WEATHER ||--o{ ENTITY : "perturbs"
  PERSISTED_STATE ||--o| SONG : "selects"
  PERSISTED_STATE ||--o{ AUDIT_EVENT : "chronicled by"

  PUPPET_MASTER }o--|| QUANTUM_REGISTER : "gate signatures (rx / h+cz / x+swap)"
  ENTITY }o--|| RD_FIELD : "deaths perturb at ground UV (onDeath)"
  WEATHER ||--o{ RD_FIELD : "tunes feed / kill / diffusion"
  TITAN }o--o{ TITAN : "iterated prisoners dilemma (45 pairs)"
  TITAN ||--o{ AUDIT_EVENT : "war strikes chronicled"
  GRAPH_TRIBE ||--o{ ENTITY : "members (setGroup write-back)"
  GRAPH_TRIBE ||--|| LORE_NAME : "named (kind = tribe)"
  CONSTELLATION_CELL ||--|| LORE_NAME : "named (kind = sector)"
  PERSISTED_STATE ||--o{ LORE_NAME : "seed derives via sha256"
  PUPPET_MASTER ||--o{ LORE_NAME : "epithets in toasts"
  SONG ||--o{ AUDIO_BANDS : "spectrum via AnalyserNode tap"
  AUDIO_BANDS }o--o{ CONSTELLATION_CELL : "treble pulses cell edges"
  ENTITY }o--|| ANALYTICS_WINDOW : "population sampled every 8th frame"
  ANALYTICS_WINDOW ||--o{ AUDIT_EVENT : "omens when abs(z) > 2.5"
  ANALYTICS_WINDOW }o--o{ LORE_NAME : "omens named via nameOmen"

  ENTITY {
    int mi "morphotype index 0..99"
    vec3 vel
    float age
    float life
    float sortVal "sorting-field value"
    float nW "neural weight"
    float energy "market wealth 0..100"
    int setGroup "set-theory group, tribe-rewritten"
  }
  MORPHOTYPE {
    int id "0..99 legacy, 0..249 phylum"
    int gi "geometry cache index"
    color col
    color em
    string beh "one of 26 behaviors"
  }
  PHYLUM {
    int index "0..9"
    float hueBand "slice of the hue wheel"
    string homeSector "preferred constellation cell"
  }
  BEHAVIOR {
    string name "26 fields, legacy order"
  }
  SHOGGOTH {
    vec3 drift "lorenz-ish"
    int tendrils
  }
  PUPPET_MASTER {
    string name "AETHON or SELENE or KRONOS"
    string action
  }
  TITAN {
    string name "lore-named colossus 0..9"
    float energy "economy wealth"
    float matter "harvested mass"
    float entropy "waste, vented as ground scars"
    string strategy "one of 5 dilemma strategies"
  }
  WEATHER {
    string kind "CLEAR..FOG"
    float wind
    float temperature
  }
  SONG {
    string name
    int bpm
    string wave
  }
  AUDIT_EVENT {
    float ts
    string action
    json detail
  }
  PERSISTED_STATE {
    int version
    int seed "mulberry32 seed, key to the mythology"
    int songIdx
    int sessions
  }
  QUANTUM_REGISTER {
    int qubits "5 in the sim (1..8 enforced)"
    float64array amps "2^n complex amplitudes"
    float entropy "normalized Shannon, telemetry v11"
    int lastCollapse "last measured basis, -1 if none"
  }
  RD_FIELD {
    int size "128 (Gray-Scott grid side)"
    float32array u "activator, ground emissiveMap"
    float32array v "inhibitor (ping-pong)"
    float feed "raised by STORM"
    float kill "raised by VOID"
    float diffusion "boosted by AURORA"
  }
  GRAPH_TRIBE {
    int index "seeded louvain community (240f)"
    int memberCount "entities carrying it in setGroup"
    float hue "slot in the 8-hue link palette"
    float pagerank "600f offset 300, top-20 emissive floor"
  }
  CONSTELLATION_CELL {
    vec2 site "monolith/diorama XZ (24 fixed sites)"
    polygon region "voronoi cell, edges at y about 55"
    string loreName "sub-sector shown in the lore line"
  }
  LORE_NAME {
    string kind "sector, tribe, star, omen"
    int index "digest input, memoized"
    string name "syllables from sha256(seed,kind,index)"
  }
  AUDIO_BANDS {
    float bass "0..1 setAudioBass rig shimmer"
    float mid "0..1"
    float treble "0..1 constellation pulse"
    float level "0..1 setBreath cloud point size"
  }
  ANALYTICS_WINDOW {
    ring population "120 samples, every 8th frame"
    ring energy "120 samples"
    ring links "120 samples"
    float trendPerMin "regression slope, telemetry v10"
    float zThreshold "2.5, one omen per 30 s max"
  }
        

sequenceDiagram
  participant RAF as rAF
  participant W as world.ts
  participant SYS as sim systems
  participant V2 as wildbeyond V2
  participant G as SpatialHash
  participant UI as ui/*
  participant R as Engine

  RAF->>W: tick (dt = min(delta, 0.05) * timeScale)
  W->>W: camera (free/orbit/fly/top), consume look/zoom
  W->>V2: audio bands poll (every frame, O(128))
  W->>SYS: weather.apply / puppetMasters.update
  W->>G: clear + insert all entities (every 2nd frame)
  W->>SYS: shoggoths.update
  W->>SYS: sort step ALGOS[algoIdx], swaps feed qcircuit.onSortSwap
  W->>SYS: entities.update — 26 behaviors, deaths scar the RD field
  W->>SYS: titans.update — economy ticks, diplomacy slot, war strikes
  W->>SYS: connectome.update (every 1/2/3 frames by n)
  W->>V2: qcircuit.update (every 30th, bands to cloud every 6th)
  W->>SYS: quantum.update (cloud, implodeAt on collapse)
  W->>V2: rd.step (every 2nd frame, offset 1)
  W->>V2: graphMind communities (every 240th) / rank (every 600th, offset 300)
  W->>V2: constellations.update (every frame, O(1) pulse)
  W->>SYS: atmosphere.update + viz3d.update (cadenced)
  W->>SYS: environment.update (setAudioBass rig shimmer)
  W->>UI: telemetry snapshot + analytics.push (every 8th frame)
  W->>V2: analytics.analyze (every 60th frame)
  W->>R: render(scene, camera)