timmy-home/GENOME.md

GENOME.md — the-nexus

Project Overview

the-nexus is a hybrid repo that combines three layers in one codebase:

1. A browser-facing world shell rooted in index.html, boot.js, bootstrap.mjs, app.js, style.css, portals.json, vision.json, manifest.json, and gofai_worker.js
2. A Python realtime bridge centered on server.py plus harness code under nexus/
3. A memory / fleet / operator layer spanning mempalace/, mcp_servers/, multi_user_bridge.py, and supporting scripts

The repo is not a clean single-purpose frontend and not just a backend harness. It is a mixed world/runtime/ops repository where browser rendering, WebSocket telemetry, MCP-driven game harnesses, and fleet memory tooling coexist.

Grounded repo facts from this checkout:

• Browser shell files exist at repo root: index.html, app.js, style.css, manifest.json, gofai_worker.js
• Data/config files also live at repo root: portals.json, vision.json
• Realtime bridge exists in server.py
• Game harnesses exist in nexus/morrowind_harness.py and nexus/bannerlord_harness.py
• Memory/fleet sync exists in mempalace/tunnel_sync.py
• Desktop/game automation MCP servers exist in mcp_servers/desktop_control_server.py and mcp_servers/steam_info_server.py
• Validation exists in tests/test_browser_smoke.py, tests/test_portals_json.py, tests/test_index_html_integrity.py, and tests/test_repo_truth.py

The current architecture is best understood as a sovereign world shell plus operator/game harness backend, with accumulated documentation drift from multiple restoration and migration efforts.

Architecture Diagram

graph TD
    browser[Index HTML Shell\nindex.html -> boot.js -> bootstrap.mjs -> app.js]
    assets[Root Assets\nstyle.css\nmanifest.json\ngofai_worker.js]
    data[World Data\nportals.json\nvision.json]
    ws[Realtime Bridge\nserver.py\nWebSocket broadcast hub]
    gofai[In-browser GOFAI\nSymbolicEngine\nNeuroSymbolicBridge\nsetupGOFAI/updateGOFAI]
    harnesses[Python Harnesses\nnexus/morrowind_harness.py\nnexus/bannerlord_harness.py]
    mcp[MCP Adapters\nmcp_servers/desktop_control_server.py\nmcp_servers/steam_info_server.py]
    memory[Memory + Fleet\nmempalace/tunnel_sync.py\nmempalace.js]
    bridge[Operator / MUD Bridge\nmulti_user_bridge.py\ncommands/timmy_commands.py]
    tests[Verification\ntests/test_browser_smoke.py\ntests/test_portals_json.py\ntests/test_repo_truth.py]
    docs[Contracts + Drift Docs\nBROWSER_CONTRACT.md\nREADME.md\nCLAUDE.md\nINVESTIGATION_ISSUE_1145.md]

    browser --> assets
    browser --> data
    browser --> gofai
    browser --> ws
    harnesses --> mcp
    harnesses --> ws
    bridge --> ws
    memory --> ws
    tests --> browser
    tests --> data
    tests --> docs
    docs --> browser

Entry Points and Data Flow

Primary entry points

• index.html — root browser entry point
• boot.js — startup selector; tests/boot.test.js shows it chooses file-mode vs HTTP/module-mode and injects bootstrap.mjs when served over HTTP
• bootstrap.mjs — module bootstrap for the browser shell
• app.js — main browser runtime; owns world state, GOFAI wiring, metrics polling, and portal/UI logic
• server.py — WebSocket broadcast bridge on ws://0.0.0.0:8765
• nexus/morrowind_harness.py — GamePortal/MCP harness for OpenMW Morrowind
• nexus/bannerlord_harness.py — GamePortal/MCP harness for Bannerlord
• mempalace/tunnel_sync.py — pulls remote fleet closets into the local palace over HTTP
• multi_user_bridge.py — HTTP bridge for multi-user chat/session integration
• mcp_servers/desktop_control_server.py — stdio MCP server exposing screenshots/mouse/keyboard control

Data flow

1. Browser startup begins at index.html
2. boot.js decides whether the page is being served correctly; in HTTP mode it injects bootstrap.mjs
3. bootstrap.mjs hands off to app.js
4. app.js loads world configuration from portals.json and vision.json
5. app.js constructs the Three.js scene and in-browser reasoning components, including SymbolicEngine, NeuroSymbolicBridge, setupGOFAI(), and updateGOFAI()
6. Browser state and external runtimes connect through server.py, which broadcasts messages between connected clients
7. Python harnesses (nexus/morrowind_harness.py, nexus/bannerlord_harness.py) spawn MCP subprocesses for desktop control / Steam metadata, capture state, execute actions, and feed telemetry into the Nexus bridge
8. Memory/fleet tools like mempalace/tunnel_sync.py import remote palace data into local closets, extending what the operator/runtime layers can inspect
9. Tests validate both the static browser contract and the higher-level repo-truth/memory contracts

Important repo-specific runtime facts

• portals.json is a JSON array of portal/world/operator entries; examples in this checkout include morrowind, bannerlord, workshop, archive, chapel, and courtyard
• server.py is a plain broadcast hub: clients send messages, the server forwards them to other connected clients
• nexus/morrowind_harness.py and nexus/bannerlord_harness.py both implement a GamePortal pattern with MCP subprocess clients over stdio and WebSocket telemetry uplink
• mempalace/tunnel_sync.py is not speculative; it is a real client that discovers remote wings, searches remote rooms, and writes .closet.json payloads locally

Key Abstractions

Browser runtime

• app.js
  • Defines in-browser reasoning/state machinery, including class SymbolicEngine, class NeuroSymbolicBridge, setupGOFAI(), and updateGOFAI()
  • Couples rendering, local symbolic reasoning, metrics polling, and portal/UI logic in one very large root module
• BROWSER_CONTRACT.md
  • Acts like an executable architecture contract for the browser surface
  • Declares required files, DOM IDs, Three.js expectations, provenance rules, and WebSocket expectations

Realtime bridge

• server.py
  • Single hub abstraction: a WebSocket broadcast server maintaining a clients set and forwarding messages from one client to the others
  • This is the seam between browser shell, harnesses, and external telemetry producers

GamePortal harness layer

• nexus/morrowind_harness.py
• nexus/bannerlord_harness.py
  • Both define MCP client wrappers, GameState / ActionResult-style data classes, and an Observe-Decide-Act telemetry loop
  • The harnesses are symmetric enough to be understood as reusable portal adapters with game-specific context injected on top

Memory / fleet layer

• mempalace/tunnel_sync.py
  • Encodes the fleet-memory sync client contract: discover wings, pull broad room queries, write closet files, support dry-run
• mempalace.js
  • Minimal browser/Electron bridge to MemPalace commands via window.electronAPI.execPython(...)
  • Important because it shows a second memory integration surface distinct from the Python fleet sync path

Operator / interaction bridge

• multi_user_bridge.py
• commands/timmy_commands.py
  • These bridge user-facing conversations or MUD/Evennia interactions back into Timmy/Nexus services

API Surface

Browser / static surface

• index.html served over HTTP
• boot.js exports bootPage(); verified by node --test tests/boot.test.js
• Data APIs are file-based inside the repo: portals.json, vision.json, manifest.json

Network/runtime surface

• python3 server.py
  • Starts the WebSocket bridge on port 8765
• python3 l402_server.py
  • Local HTTP microservice for cost-estimate style responses
• python3 multi_user_bridge.py
  • Multi-user HTTP/chat bridge

Harness / operator CLI surfaces

• python3 nexus/morrowind_harness.py
• python3 nexus/bannerlord_harness.py
• python3 mempalace/tunnel_sync.py --peer <url> [--dry-run] [--n N]
• python3 mcp_servers/desktop_control_server.py
• python3 mcp_servers/steam_info_server.py

Validation surface

• python3 -m pytest tests/test_portals_json.py tests/test_index_html_integrity.py tests/test_repo_truth.py -q
• node --test tests/boot.test.js
• python3 -m py_compile server.py nexus/morrowind_harness.py nexus/bannerlord_harness.py mempalace/tunnel_sync.py mcp_servers/desktop_control_server.py
• tests/test_browser_smoke.py defines the higher-cost Playwright smoke contract for the world shell

Test Coverage Gaps

Strongly covered in this checkout:

• tests/test_portals_json.py validates portals.json
• tests/test_index_html_integrity.py checks merge-marker/DOM-integrity regressions in index.html
• tests/boot.test.js verifies boot.js startup behavior
• tests/test_repo_truth.py validates the repo-truth documents
• Multiple tests/test_mempalace_*.py files cover the palace layer
• tests/test_bannerlord_harness.py exists for the Bannerlord harness

Notable gaps or weak seams:

• nexus/morrowind_harness.py is large and operationally critical, but the generated baseline still flags it as a gap relative to its size/complexity
• mcp_servers/desktop_control_server.py exposes high-power automation but has no obvious dedicated test file in the root tests/ suite
• app.js is the dominant browser runtime file and mixes rendering, GOFAI, metrics, and integration logic in one place; browser smoke exists, but there is limited unit-level decomposition around those subsystems
• mempalace.js appears minimally bridged and stale relative to the richer Python MemPalace layer
• multi_user_bridge.py is a large integration surface and should be treated as high regression risk even though it is central to operator/chat flow

Security Considerations

• server.py binds HOST = "0.0.0.0", exposing the broadcast bridge beyond localhost unless network controls limit it
• The WebSocket bridge is a broadcast hub without visible authentication in server.py; connected clients are trusted to send messages into the bus
• mcp_servers/desktop_control_server.py exposes mouse/keyboard/screenshot control through a stdio MCP server. In any non-local or poorly isolated runtime, this is a privileged automation surface
• app.js contains hardcoded local/network endpoints such as http://localhost:${L402_PORT}/api/cost-estimate and http://localhost:8082/metrics; these are convenient for local development but create environment drift and deployment assumptions
• app.js also embeds explicit endpoint/status references like ws://143.198.27.163:8765, which is operationally brittle and the kind of hardcoded location data that drifts across environments
• mempalace.js shells out through window.electronAPI.execPython(...); this is powerful and useful, but it is a clear trust boundary between UI and host execution
• INVESTIGATION_ISSUE_1145.md documents an earlier integrity hazard: agents writing to public/nexus/ instead of canonical root paths. That path confusion is both an operational and security concern because it makes provenance harder to reason about

Runtime Truth and Docs Drift

The most important architecture finding in this repo is not a class or subsystem. It is a truth mismatch.

• README.md says current main does not ship a browser 3D world
• CLAUDE.md declares root app.js and index.html as canonical frontend paths
• tests and browser contract now assume the root frontend exists

All three statements are simultaneously present in this checkout.

Grounded evidence:

• README.md still says the repo does not contain an active root frontend such as index.html, app.js, or style.css
• the current checkout does contain index.html, app.js, style.css, manifest.json, and gofai_worker.js
• BROWSER_CONTRACT.md explicitly treats those root files as required browser assets
• tests/test_browser_smoke.py serves those exact files and validates DOM/WebGL contracts against them
• tests/test_index_html_integrity.py assumes index.html is canonical and production-relevant
• CLAUDE.md says frontend code lives at repo root and explicitly warns against public/nexus/
• INVESTIGATION_ISSUE_1145.md explains why public/nexus/ is a bad/corrupt duplicate path and confirms the real classical AI code lives in root app.js

The honest conclusion:

• The repo contains a partially restored or actively re-materialized browser surface
• The docs are preserving an older migration truth while the runtime files and smoke contracts describe a newer present-tense truth
• Any future work in the-nexus must choose one truth and align README.md, CLAUDE.md, smoke tests, and file layout around it

That drift is itself a critical architectural fact and should be treated as first-order design debt, not a side note.