timmy-home/research/big-brain/the-nexus-deep-audit.md

The Nexus Deep Audit

Date: 2026-04-14 Target repo: Timmy_Foundation/the-nexus Audited commit: dfbd96f7927a377c40ccb488238f5e2b69b033ba Audit artifact issue: timmy-home#575 Follow-on issue filed: the-nexus#1423 Supporting artifacts:

• research/big-brain/the-nexus-context-bundle.md
• research/big-brain/the-nexus-audit-model.md
• scripts/big_brain_repo_audit.py

Method

• Cloned Timmy_Foundation/the-nexus at clean main.
• Indexed 403 text files and ~38.2k LOC (Python-heavy backend plus a substantial browser shell).
• Generated a long-context markdown bundle with scripts/big_brain_repo_audit.py.
• Ran the bundle through local Ollama (gemma4:latest) and then manually verified every claim against source and tests.
• Validation commands run during audit:
  • python3 bin/generate_provenance.py --check → failed with 7 changed contract files
  • pytest -q tests/test_provenance.py → 1 failed / 5 passed

Architecture summary

The repo is no longer a narrow "Python cognition only" shell. Current main is a mixed system with four active layers:

1. Browser world / operator shell at repo root

   • index.html, app.js, style.css, boot.js, gofai_worker.js, portals.json, vision.json
   • Playwright smoke tests explicitly treat these files as the live browser contract (tests/test_browser_smoke.py:70-88).

2. Local bridge / runtime surface

   • server.py runs the WebSocket gateway for the browser shell (server.py:1-123).
   • electron-main.js adds a desktop shell / IPC path (electron-main.js:1-12).

3. Python cognition + world adapters under nexus/

   • Mnemosyne archive, A2A card/server/client, Evennia bridge, Morrowind/Bannerlord harnesses.
   • The archive alone is a significant subsystem (nexus/mnemosyne/archive.py:21-220).

4. Separate intelligence / ops stacks

   • intelligence/deepdive/ claims a complete sovereign briefing pipeline (intelligence/deepdive/README.md:30-43).
   • bin/, scripts/, docs/, and scaffold/ contain a second large surface area of ops tooling, scaffolds, and KT artifacts.

Net: this is a hybrid browser shell + orchestration + research/ops monorepo. The biggest architectural problem is not missing capability. It is unclear canonical ownership.

Top 5 structural issues / code smells

1. Repo truth is internally contradictory

README.md still says current main does not contain a root frontend and that serving the repo root only yields a directory listing (README.md:42-57, README.md:118-143). That is directly contradicted by:

• the actual root files present in the checkout (index.html, app.js, style.css, gofai_worker.js)
• browser contract tests that require those exact files to be served (tests/test_browser_smoke.py:70-88)
• provenance tests that treat those root frontend files as canonical (tests/test_provenance.py:54-65)

Impact: contributors cannot trust the repo's own description of what is canonical. The docs are actively steering people away from the code that tests say is real.

2. The provenance contract is stale and currently broken on main

The provenance system is supposed to prove the browser surface came from a clean checkout (bin/generate_provenance.py:19-39, tests/test_provenance.py:39-51). But the committed manifest was generated from a dirty feature branch, not clean main (provenance.json:2-8). On current main, the contract is already invalid:

• python3 bin/generate_provenance.py --check fails on 7 files
• pytest -q tests/test_provenance.py fails on test_provenance_hashes_match

Impact: the repo's own anti-ghost-world safety mechanism no longer signals truth. That weakens every future visual validation claim.

3. app.js is a 4k-line god object with duplicate module ownership

app.js imports the symbolic engine module (app.js:105-109) and then immediately redefines the same classes inline (app.js:111-652). The duplicated classes also exist in nexus/symbolic-engine.js:2-386.

This means the symbolic layer has at least two owners:

• canonical-looking module: nexus/symbolic-engine.js
• actual inlined implementation: app.js:111-652

Impact: changes can drift silently, code review becomes deceptive, and the frontend boundary is fake. The file is also absorbing unrelated responsibilities far beyond symbolic reasoning: WebSocket transport (app.js:2165-2232), Evennia panels (app.js:2291-2458), MemPalace UI (app.js:2764-2875), rendering, controls, and ops dashboards.

4. The frontend contains shadowed handlers and duplicated DOM state

There are multiple signs of merge-by-accretion rather than clean composition:

• connectHermes() initializes MemPalace twice (app.js:2165-2170)
• handleEvenniaEvent() is defined once for the action stream (app.js:2326-2340) and then redefined again for room snapshots (app.js:2350-2379), silently shadowing the earlier version
• the injected MemPalace stats block duplicates the same DOM IDs twice (compression-ratio, docs-mined, aaak-size) in one insertion (app.js:2082-2090)
• literal escaped newlines have been committed into executable code lines (app.js:1, app.js:637, app.js:709)

Impact: parts of the UI can go dead without obvious failures, DOM queries become ambiguous, and the file is carrying artifacts of prior AI patching rather than coherent ownership.

5. DeepDive is split across two contradictory implementations

intelligence/deepdive/README.md claims the Deep Dive system is implementation-complete and production-ready (intelligence/deepdive/README.md:30-43). In the same repo, scaffold/deepdive/phase2/relevance_engine.py, phase4/tts_pipeline.py, and phase5/telegram_delivery.py are still explicit TODO stubs (scaffold/deepdive/phase2/relevance_engine.py:10-18, scaffold/deepdive/phase4/tts_pipeline.py:9-17, scaffold/deepdive/phase5/telegram_delivery.py:9-16).

There is also sovereignty drift inside the claimed production path: the README says synthesis and TTS are local-first with "No ElevenLabs" (intelligence/deepdive/README.md:49-57), while tts_engine.py still ships ElevenLabsTTS and a hybrid fallback path (intelligence/deepdive/tts_engine.py:120-209).

Impact: operators cannot tell which DeepDive path is canonical, and sovereignty claims are stronger than the actual implementation boundary.

Top 3 recommended refactors

1. Re-establish a single source of truth for the browser contract

Files / refs:

• README.md:42-57, README.md:118-143
• tests/test_browser_smoke.py:70-88
• tests/test_provenance.py:39-51
• bin/generate_provenance.py:69-101

Refactor:

• Rewrite README/CLAUDE/current-truth docs to match the live root contract.
• Regenerate provenance.json from clean main and make bin/generate_provenance.py --check mandatory in CI.
• Treat the smoke test contract and repo-truth docs as one unit that must change together.

Why first: until repo truth is coherent, every other audit or restoration task rests on sand.

2. Split app.js into owned modules and delete the duplicate symbolic engine copy

Files / refs:

• app.js:105-652
• nexus/symbolic-engine.js:2-386
• app.js:2165-2458

Refactor:

• Make nexus/symbolic-engine.js the only symbolic-engine implementation.
• Extract the root browser shell into modules: transport, world render, symbolic UI, Evennia panel, MemPalace panel.
• Add a thin composition root in app.js instead of keeping behavior inline.

Why second: this is the main complexity sink in the repo. Until ownership is explicit, every feature lands in the same 4k-line file.

3. Replace the raw Electron command bridge with typed IPC actions

Files / refs:

• electron-main.js:1-12
• mempalace.js:18-35
• app.js:2139-2141
• filed issue: the-nexus#1423

Refactor:

• Remove exec(command) from the main process.
• Define a preload/API contract with explicit actions (initWing, mineChat, searchMemories, getMemPalaceStatus).
• Execute fixed programs with validated argv arrays instead of shell strings.
• Add regression tests for command-injection payloads.

Why third: this is the highest-severity boundary flaw in the repo.

Security concerns

Critical: renderer-to-shell arbitrary command execution

electron-main.js:5-10 exposes a generic exec(command) sink. Renderer code builds command strings with interpolated values:

• mempalace.js:19-20, mempalace.js:25, mempalace.js:30, mempalace.js:35
• app.js:2140-2141

This is a classic command-injection surface. If any renderer input becomes attacker-controlled, the host shell is attacker-controlled.

Status: follow-on issue filed as the-nexus#1423.

Medium: repeated innerHTML writes against dynamic values

The browser shell repeatedly writes HTML fragments with interpolated values in both the inline symbolic engine and the extracted one:

• app.js:157, app.js:232, app.js:317, app.js:410-413, app.js:445, app.js:474-477
• nexus/symbolic-engine.js:48, nexus/symbolic-engine.js:132, nexus/symbolic-engine.js:217, nexus/symbolic-engine.js:310-312, nexus/symbolic-engine.js:344, nexus/symbolic-engine.js:373-375

Not every one of these is exploitable in practice, but the pattern is broad enough that an eventual untrusted data path could become an XSS sink.

Medium: broken provenance reduces trust in validation results

Because the provenance manifest is stale (provenance.json:2-8) and the verification test is failing (tests/test_provenance.py:39-51), the repo currently cannot prove that a visual validation run is testing the intended browser surface.

Filed follow-on issue(s)

• the-nexus#1423 — [SECURITY] Electron MemPalace bridge allows arbitrary command execution from renderer

Additional issue candidates worth filing next

1. [ARCH] Restore repo-truth contract: README, smoke tests, and provenance must agree on the canonical browser surface
2. [REFACTOR] Decompose app.js and make nexus/symbolic-engine.js the single symbolic engine owner
3. [DEEPDIVE] Collapse scaffold/deepdive vs intelligence/deepdive into one canonical pipeline

Bottom line

The Nexus is not missing ambition. It is missing boundary discipline.

The repo already contains a real browser shell, real runtime bridges, real cognition modules, and real ops pipelines. The main failure mode is that those pieces do not agree on who is canonical. Fix the truth contract first, then the app.js ownership boundary, then the Electron security boundary.