🤓 Nerd Mode · Engineering Deep Dive

v25.7.57 · Sprint 5 — 🜂 Council Chamber + 🎮 Game Studio + Async-Task Pattern + ES-Modules Phase 2

backend AI Directors — Council Chamber

• routes/ai_directors.py · POST /api/ai-directors/council/discuss → spawns asyncio.create_task(_run_council), returns {session_id, status:'running'} in 152ms.
• 4-turn sequence: whca_director_business (Ops) → product_dev_manager (Schematic) → app_janitor (Risk) → whca_director_health (Human-Impact). Each turn ends with → DELEGATE / → APPROVE / → ESCALATE.
• Per-turn progress persisted to db.ai_council_sessions so polling shows live state.
• GET /api/ai-directors/council/job/{session_id} returns the running row + transcript array. Frontend /ai/council.html polls every 4s.

backend Game Studio (full creator pipeline)

• New router routes/game_studio.py (~530 LOC). Pipeline: draft → upload-bundle (SHA-256) → submit (council review async) → approve (Merkle proof registered) → published → play (sandboxed iframe).
• Mongo: db.games, db.tcl_game_proofs. Status state machine: draft | reviewing | submitted | published | rejected.
• Bundle constraints: 25 MB cap, .html-only (single-file games), filename sanitised to alphanumerics+dot+dash, content-filter scan for banned phrases.
• Revenue models: sovereign 95/5 vs spotlight 80/20. starter_qn capped 0-10 on the server.
• Play endpoint: returns the bundle with strict CSP (frame-ancestors * intentional for embedding; SA can lock down later).

infra The asyncio.to_thread fix

• iter-127 finding: 4× sequential Claude calls (~20s each) inside one HTTP handler exceeded the K8s ingress ~100s read timeout, causing 502s while backend silently completed.
• iter-127 first refactor: moved work into asyncio.create_task — but convene latency was still 23s. Root cause: emergentintegrations.llm.chat uses sync HTTP under the hood, so await chat.send_message() blocks the asyncio loop.
• iter-128 fix verified: wrap each LLM call in asyncio.to_thread(lambda: asyncio.run(...)) — spins up a worker thread + nested event loop per call. Convene/submit now return in 152ms; concurrent calls verified non-blocking.

reply = await asyncio.wait_for(
    asyncio.to_thread(lambda: asyncio.run(chat_obj.send_message(UserMessage(text=user_msg)))),
    timeout=45,
)

security Anonymous IP rate-limit

• ai_directors.py · _rate_limit_anon(ip) uses a per-IP collections.deque with rolling 1-hour window. ANON_PER_HOUR = 8.
• Returns 429 with friendly L1 signup CTA in detail. Per-process only — multi-replica deploys will have per-replica counters (acceptable for current scale).

frontend ES-Modules Phase 2

• js/dashboard.js (2042 LOC) relocated to js/features/dashboard.js. Loaded BEFORE main-app.js so all dashboard globals (loadMemberDashboard, executeHashNavigation, goHome, goToDashboard) are present at SPA boot.
• Phase 3 plan: extract features/qinote.js, features/messaging.js, features/admin.js from main-app.js (now ~8990 LOC, down from a high of ~9100).
• Phase 4 plan: switch index.html to <script type="module"> and drop the window.* compat shim.

backend NuWallet bridge wired

• js/wallet-live-update.js:50 — every refreshWallet() call now also fires NuWallet.localUpdate({delta}) so subscribers (chip, dashboard pill, wallet widget) repaint sub-second.
• js/learning-tasks.js:219 + js/fba-phase2.js:244 — optimistic localUpdate the moment the server confirms a credit.

db New collections / fields this sprint

db.ai_council_sessions  { id, session_id, status, convened_by, question, context, transcript[], turn_completed, created_at, completed_at }
db.games                { id, title, pitch, format, revenue_model, creator_id, creator_email, status, bundle_path, bundle_sha256, bundle_size, council_review{transcript[], overall_verdict}, merkle_proof, plays, is_deleted, ... }
db.tcl_game_proofs      { game_id, asset_sha256, registered_at, registered_by }
db.ai_dept_trainers     { agent_key, department_id, name, title, system_prompt, min_tier, active, created_at, created_by }

v25.7.57 · Sprint 4 — 🜂 AI Directors Framework

• routes/ai_directors.py built — AGENT_REGISTRY with 4 in-house agents (Dr. Sekhmet/whca_director_health, Director Het-Heru/whca_director_business, Imhotep/product_dev_manager, Watcher Nun/app_janitor). Each has tuned system prompt with _BASE_TERMINOLOGY ("the NuBein ePronomy", "Wholistic HealthCare", capitalised We/Us/Our).
• RBAC by min_tier: 0/1/2/5 — anonymous gets only Dr. Sekhmet (rudimentary), L2+ unlocks Business + Product Dev, Steward+ unlocks App Janitor.
• WHCA Health is tier-aware: same agent_key but the user-message has an appended VIEWER-TIER block that swaps between the short-rudimentary CTA and the full HealthCare protocol response.
• _resolve_agent() also pulls SA-managed dept trainers from db.ai_dept_trainers (created via POST /trainers, listed/deleted at GET/DELETE /trainers).
• Frontend: /ai-directors.html (tier-aware grid) + per-agent themed pages /ai/{whca-health,whca-business,product-dev,app-janitor}.html using shared js/ai-directors-chat.js mount helper.

v25.7.57 · Sprints 1-3 — What's New Card + ES-Modules Phase 1 + Test-Credentials Migration

• Sprint 1: js/whatsnew-card.js — one-time release-notes modal keyed on seen_whatsnew_V25.7.57* LS flag.
• Sprint 2: state/auth.js + state/config.js (and now state/wallet.js) — formal Phase-1 boundary. Loaded BEFORE all other JS. Mirrors to window.* for compat.
• Sprint 3: backend/tests/_migrate_credentials.py migrated 148 hardcoded test credentials across 64 files to os.environ.get(...). tests/_credentials.py is now the canonical source.

v25.7.54–56 · Code-Review Triage + Streak Multiplier + Final Scaffold Delete

• Auto-rotating promo videos with editable/approvable list (routes/videos.py · 4 endpoints + 6h background loop).
• Streak Multiplier in Sovereign Arcade — 10+ steward actions = 1.5×, 30+ = 2.0×. Compounds with growth-path multiplier (routes/arcade.py).
• Permanent delete of frontend/src/_archived_react_scaffold_v25_7_54/ (37 files). random → secrets in tcl_common.py + challenges.py. memory/CODE_REVIEW_NOTES.md documents resolved false positives.

v25.7.47–53 · NuBrowser + Auto-Polls + UX Modes + Sprint C Videos + Spotlight + Steward Queue

• routes/feature_gates.py with 35 seeded block-gates + 6 global flags. SA-configurable via /sa-feature-gates.html.
• routes/auto_polls.py · Civic Pulse Agent generates 2-3 polls/3-days via Claude (Emergent LLM key), curated fallback. Per-poll doughnut stats, reminder bulk-insert.
• routes/steward_queue.py unified L4 approval queue (glossary + lessons + jobs). Streak: every 10 actions = +50 QN to db.wallets.balance_qinote.
• Sprint C: routes/videos.py 7 endpoints with 600 MB cap + Emergent object storage. Landing banner + announcement system.
• Sovereign Spotlight 1-screen signup CTA (js/sovereign-spotlight-cta.js) for anonymous visitors.

v25.7.42–46 · PaC Birth Registry + WHCA Foundations + Login Dead-Click Fix

• routes/nubein_registry.py · field-level Fernet AES encryption (BIRTH_REGISTRY_FERNET_KEY in .env). Tiered permissions L1-L5+. Co-parent flow via POST /{id}/co-sign.
• WHCA mission seeded: 6 glossary terms, 3 lessons, 4 recruiting reqs (pending SA approval).
• Login modal simplified to email+password (role auto-defaults to member). Brute-force _login_attempts.clear() on boot. SA reset-password endpoint added.
• Version badge converted to <a href> (popup-blocker safe). Button + overlay audit module with bubble exemptions.

v25.7.37–41 · Earning while Learning + Active QN + Learning Tasks + Engagement

• routes/arcade_engagement.py — POST /api/arcade/engagement/ping awards QN per category (SA-adjustable rate + daily cap).
• routes/learning_tasks.py — Claude-generated tasks behind admin approval; curated fallback seeded on first boot.
• SA Arcade Editor extended with engagement_rates + engagement_daily_qn_cap.
• Frontend: js/active-qn.js heartbeat + corner chip; js/learning-tasks.js Job-Board injection + replayable intro.

v7.0 → v25.7.36 · Legacy (high-level)

• v25.7.27–35: Sovereign Arcade (5 retro games), Avatars (chat/RPG/leaderboards), Files Vault (Trash/Restore), EmperiaL Music 5-stage AI pipeline, universal "What's Next" CTAs.
• v25.7.24: Terminology pivot to "the NuBein ePronomy" (replaces Nu-Conomy everywhere). FBA Phase 2 Stripe Checkout + Plaid ACH stubs. Anu Guide nudges + Department group To-Dos.
• v25.7.x RPG Revamp: XP bar, level-up cutscenes, Quest Arc skin on 9-Day-Strong calendar, Pillar Guild Hall themes, Tribal Treasury Living Map, Oracle Crystal help bubble.
• v23 tCL Sovereignty: per-entry public Merkle inclusion-proof endpoints (routes/tcl_audit.py), plain-talk help guide.
• v19–22: The AnkhCestral Codex + 9 Enlightenment Lessons + Group Chat + Job Board.
• v7–v18: Membership Levels (L1–L5), QiNote Treasury + Tribal Treasury, EmperiaL Music Industry v1, Pillar Journey + Focus, Notifications stack (in-app/email/SMS/push), Delivery + Rideshare scaffolding, Department managers + AI persona stubs, QiNote Pay P2P, TNSE marketplace, Daily Anu Guide Nudge v1, Admin Asset Manager, Free-trial allowance.