Compare commits
1 Commits
burn/672-1
...
fix/547
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
5d49b38ce3 |
125
configs/fleet_progression.json
Normal file
125
configs/fleet_progression.json
Normal file
@@ -0,0 +1,125 @@
|
||||
{
|
||||
"epic_issue": 547,
|
||||
"epic_title": "Fleet Progression - Paperclips-Inspired Infrastructure Evolution",
|
||||
"phases": [
|
||||
{
|
||||
"number": 1,
|
||||
"issue_number": 548,
|
||||
"key": "survival",
|
||||
"name": "SURVIVAL",
|
||||
"summary": "Keep the lights on.",
|
||||
"unlock_rules": [
|
||||
{
|
||||
"id": "fleet_operational_baseline",
|
||||
"type": "always"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"number": 2,
|
||||
"issue_number": 549,
|
||||
"key": "automation",
|
||||
"name": "AUTOMATION",
|
||||
"summary": "Self-healing infrastructure.",
|
||||
"unlock_rules": [
|
||||
{
|
||||
"id": "uptime_percent_30d_gte_95",
|
||||
"type": "resource_gte",
|
||||
"resource": "uptime_percent_30d",
|
||||
"value": 95
|
||||
},
|
||||
{
|
||||
"id": "capacity_utilization_gt_60",
|
||||
"type": "resource_gt",
|
||||
"resource": "capacity_utilization",
|
||||
"value": 60
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"number": 3,
|
||||
"issue_number": 550,
|
||||
"key": "orchestration",
|
||||
"name": "ORCHESTRATION",
|
||||
"summary": "Agents coordinate and models route.",
|
||||
"unlock_rules": [
|
||||
{
|
||||
"id": "phase_2_issue_closed",
|
||||
"type": "issue_closed",
|
||||
"issue": 549
|
||||
},
|
||||
{
|
||||
"id": "innovation_gt_100",
|
||||
"type": "resource_gt",
|
||||
"resource": "innovation",
|
||||
"value": 100
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"number": 4,
|
||||
"issue_number": 551,
|
||||
"key": "sovereignty",
|
||||
"name": "SOVEREIGNTY",
|
||||
"summary": "Zero cloud dependencies.",
|
||||
"unlock_rules": [
|
||||
{
|
||||
"id": "phase_3_issue_closed",
|
||||
"type": "issue_closed",
|
||||
"issue": 550
|
||||
},
|
||||
{
|
||||
"id": "all_models_local_true",
|
||||
"type": "resource_true",
|
||||
"resource": "all_models_local"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"number": 5,
|
||||
"issue_number": 552,
|
||||
"key": "scale",
|
||||
"name": "SCALE",
|
||||
"summary": "Fleet-wide coordination and auto-scaling.",
|
||||
"unlock_rules": [
|
||||
{
|
||||
"id": "phase_4_issue_closed",
|
||||
"type": "issue_closed",
|
||||
"issue": 551
|
||||
},
|
||||
{
|
||||
"id": "sovereign_stable_days_gte_30",
|
||||
"type": "resource_gte",
|
||||
"resource": "sovereign_stable_days",
|
||||
"value": 30
|
||||
},
|
||||
{
|
||||
"id": "innovation_gt_500",
|
||||
"type": "resource_gt",
|
||||
"resource": "innovation",
|
||||
"value": 500
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"number": 6,
|
||||
"issue_number": 553,
|
||||
"key": "the-network",
|
||||
"name": "THE NETWORK",
|
||||
"summary": "Autonomous, self-improving infrastructure.",
|
||||
"unlock_rules": [
|
||||
{
|
||||
"id": "phase_5_issue_closed",
|
||||
"type": "issue_closed",
|
||||
"issue": 552
|
||||
},
|
||||
{
|
||||
"id": "human_free_days_gte_7",
|
||||
"type": "resource_gte",
|
||||
"resource": "human_free_days",
|
||||
"value": 7
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
234
scripts/fleet_progression.py
Normal file
234
scripts/fleet_progression.py
Normal file
@@ -0,0 +1,234 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Fleet progression evaluator for the Paperclips-inspired infrastructure epic.
|
||||
|
||||
Refs: timmy-home #547
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
from pathlib import Path
|
||||
from urllib import request
|
||||
from typing import Any
|
||||
|
||||
DEFAULT_BASE_URL = "https://forge.alexanderwhitestone.com/api/v1"
|
||||
DEFAULT_OWNER = "Timmy_Foundation"
|
||||
DEFAULT_REPO = "timmy-home"
|
||||
DEFAULT_TOKEN_FILE = Path.home() / ".config" / "gitea" / "token"
|
||||
DEFAULT_SPEC_FILE = Path(__file__).resolve().parent.parent / "configs" / "fleet_progression.json"
|
||||
|
||||
DEFAULT_RESOURCES = {
|
||||
"uptime_percent_30d": 0.0,
|
||||
"capacity_utilization": 0.0,
|
||||
"innovation": 0.0,
|
||||
"all_models_local": False,
|
||||
"sovereign_stable_days": 0,
|
||||
"human_free_days": 0,
|
||||
}
|
||||
|
||||
|
||||
class GiteaClient:
|
||||
def __init__(self, token: str, owner: str = DEFAULT_OWNER, repo: str = DEFAULT_REPO, base_url: str = DEFAULT_BASE_URL):
|
||||
self.token = token
|
||||
self.owner = owner
|
||||
self.repo = repo
|
||||
self.base_url = base_url.rstrip("/")
|
||||
|
||||
def get_issue(self, issue_number: int):
|
||||
headers = {"Authorization": f"token {self.token}"}
|
||||
req = request.Request(
|
||||
f"{self.base_url}/repos/{self.owner}/{self.repo}/issues/{issue_number}",
|
||||
headers=headers,
|
||||
)
|
||||
with request.urlopen(req, timeout=30) as resp:
|
||||
return json.loads(resp.read().decode())
|
||||
|
||||
|
||||
def load_spec(path: Path | None = None):
|
||||
target = path or DEFAULT_SPEC_FILE
|
||||
return json.loads(target.read_text())
|
||||
|
||||
|
||||
def load_issue_states(spec: dict[str, Any], token_file: Path = DEFAULT_TOKEN_FILE):
|
||||
if not token_file.exists():
|
||||
raise FileNotFoundError(f"Token file not found: {token_file}")
|
||||
|
||||
token = token_file.read_text().strip()
|
||||
client = GiteaClient(token=token)
|
||||
issue_states = {}
|
||||
for phase in spec["phases"]:
|
||||
issue = client.get_issue(phase["issue_number"])
|
||||
issue_states[phase["issue_number"]] = issue["state"]
|
||||
return issue_states
|
||||
|
||||
|
||||
def _evaluate_rule(rule: dict[str, Any], issue_states: dict[int, str], resources: dict[str, Any]):
|
||||
rule_type = rule["type"]
|
||||
rule_id = rule["id"]
|
||||
|
||||
if rule_type == "always":
|
||||
return {"rule": rule_id, "passed": True, "actual": True, "expected": True}
|
||||
|
||||
if rule_type == "issue_closed":
|
||||
issue_number = int(rule["issue"])
|
||||
actual = str(issue_states.get(issue_number, "open"))
|
||||
return {
|
||||
"rule": rule_id,
|
||||
"passed": actual == "closed",
|
||||
"actual": actual,
|
||||
"expected": "closed",
|
||||
}
|
||||
|
||||
if rule_type == "resource_gte":
|
||||
resource = rule["resource"]
|
||||
actual = resources.get(resource, 0)
|
||||
expected = rule["value"]
|
||||
return {
|
||||
"rule": rule_id,
|
||||
"passed": actual >= expected,
|
||||
"actual": actual,
|
||||
"expected": f">={expected}",
|
||||
}
|
||||
|
||||
if rule_type == "resource_gt":
|
||||
resource = rule["resource"]
|
||||
actual = resources.get(resource, 0)
|
||||
expected = rule["value"]
|
||||
return {
|
||||
"rule": rule_id,
|
||||
"passed": actual > expected,
|
||||
"actual": actual,
|
||||
"expected": f">{expected}",
|
||||
}
|
||||
|
||||
if rule_type == "resource_true":
|
||||
resource = rule["resource"]
|
||||
actual = bool(resources.get(resource, False))
|
||||
return {
|
||||
"rule": rule_id,
|
||||
"passed": actual is True,
|
||||
"actual": actual,
|
||||
"expected": True,
|
||||
}
|
||||
|
||||
raise ValueError(f"Unsupported rule type: {rule_type}")
|
||||
|
||||
|
||||
def evaluate_progression(spec: dict[str, Any], issue_states: dict[int, str], resources: dict[str, Any] | None = None):
|
||||
merged_resources = {**DEFAULT_RESOURCES, **(resources or {})}
|
||||
phase_results = []
|
||||
|
||||
for phase in spec["phases"]:
|
||||
issue_number = phase["issue_number"]
|
||||
completed = str(issue_states.get(issue_number, "open")) == "closed"
|
||||
rule_results = [
|
||||
_evaluate_rule(rule, issue_states, merged_resources)
|
||||
for rule in phase.get("unlock_rules", [])
|
||||
]
|
||||
blocking = [item for item in rule_results if not item["passed"]]
|
||||
unlocked = not blocking
|
||||
phase_results.append(
|
||||
{
|
||||
"number": phase["number"],
|
||||
"issue_number": issue_number,
|
||||
"key": phase["key"],
|
||||
"name": phase["name"],
|
||||
"summary": phase["summary"],
|
||||
"completed": completed,
|
||||
"unlocked": unlocked,
|
||||
"available_to_work": unlocked and not completed,
|
||||
"passed_requirements": [item for item in rule_results if item["passed"]],
|
||||
"blocking_requirements": blocking,
|
||||
}
|
||||
)
|
||||
|
||||
unlocked_phases = [phase for phase in phase_results if phase["unlocked"]]
|
||||
current_phase = unlocked_phases[-1] if unlocked_phases else phase_results[0]
|
||||
next_locked_phase = next((phase for phase in phase_results if not phase["unlocked"]), None)
|
||||
epic_complete = all(phase["completed"] for phase in phase_results) and phase_results[-1]["unlocked"]
|
||||
|
||||
return {
|
||||
"epic_issue": spec["epic_issue"],
|
||||
"epic_title": spec["epic_title"],
|
||||
"resources": merged_resources,
|
||||
"issue_states": {str(k): v for k, v in issue_states.items()},
|
||||
"phases": phase_results,
|
||||
"current_phase": current_phase,
|
||||
"next_locked_phase": next_locked_phase,
|
||||
"epic_complete": epic_complete,
|
||||
}
|
||||
|
||||
|
||||
def parse_args():
|
||||
parser = argparse.ArgumentParser(description="Evaluate current fleet progression against the Paperclips-inspired epic.")
|
||||
parser.add_argument("--spec-file", type=Path, default=DEFAULT_SPEC_FILE)
|
||||
parser.add_argument("--token-file", type=Path, default=DEFAULT_TOKEN_FILE)
|
||||
parser.add_argument("--issue-state-file", type=Path, help="Optional JSON file of issue_number -> state overrides")
|
||||
parser.add_argument("--resource-file", type=Path, help="Optional JSON file with resource values")
|
||||
parser.add_argument("--uptime-percent-30d", type=float)
|
||||
parser.add_argument("--capacity-utilization", type=float)
|
||||
parser.add_argument("--innovation", type=float)
|
||||
parser.add_argument("--all-models-local", action="store_true")
|
||||
parser.add_argument("--sovereign-stable-days", type=int)
|
||||
parser.add_argument("--human-free-days", type=int)
|
||||
parser.add_argument("--json", action="store_true")
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
def _load_resources(args):
|
||||
resources = dict(DEFAULT_RESOURCES)
|
||||
if args.resource_file:
|
||||
resources.update(json.loads(args.resource_file.read_text()))
|
||||
|
||||
overrides = {
|
||||
"uptime_percent_30d": args.uptime_percent_30d,
|
||||
"capacity_utilization": args.capacity_utilization,
|
||||
"innovation": args.innovation,
|
||||
"sovereign_stable_days": args.sovereign_stable_days,
|
||||
"human_free_days": args.human_free_days,
|
||||
}
|
||||
for key, value in overrides.items():
|
||||
if value is not None:
|
||||
resources[key] = value
|
||||
if args.all_models_local:
|
||||
resources["all_models_local"] = True
|
||||
return resources
|
||||
|
||||
|
||||
def _load_issue_states(args, spec):
|
||||
if args.issue_state_file:
|
||||
raw = json.loads(args.issue_state_file.read_text())
|
||||
return {int(k): v for k, v in raw.items()}
|
||||
return load_issue_states(spec, token_file=args.token_file)
|
||||
|
||||
|
||||
def main():
|
||||
args = parse_args()
|
||||
spec = load_spec(args.spec_file)
|
||||
issue_states = _load_issue_states(args, spec)
|
||||
resources = _load_resources(args)
|
||||
result = evaluate_progression(spec, issue_states, resources)
|
||||
|
||||
if args.json:
|
||||
print(json.dumps(result, indent=2))
|
||||
return
|
||||
|
||||
print("--- Fleet Progression Evaluator ---")
|
||||
print(f"Epic #{result['epic_issue']}: {result['epic_title']}")
|
||||
print(f"Current phase: {result['current_phase']['number']} — {result['current_phase']['name']}")
|
||||
if result["next_locked_phase"]:
|
||||
print(f"Next locked phase: {result['next_locked_phase']['number']} — {result['next_locked_phase']['name']}")
|
||||
print(f"Epic complete: {result['epic_complete']}")
|
||||
print()
|
||||
for phase in result["phases"]:
|
||||
state = "COMPLETE" if phase["completed"] else "ACTIVE" if phase["available_to_work"] else "LOCKED"
|
||||
print(f"Phase {phase['number']} [{state}] {phase['name']}")
|
||||
if phase["blocking_requirements"]:
|
||||
for blocker in phase["blocking_requirements"]:
|
||||
print(f" - blocked by {blocker['rule']}: actual={blocker['actual']} expected={blocker['expected']}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
92
tests/test_fleet_progression.py
Normal file
92
tests/test_fleet_progression.py
Normal file
@@ -0,0 +1,92 @@
|
||||
from scripts.fleet_progression import evaluate_progression, load_spec
|
||||
|
||||
|
||||
def test_load_spec_contains_epic_and_all_six_phases():
|
||||
spec = load_spec()
|
||||
|
||||
assert spec["epic_issue"] == 547
|
||||
assert [phase["number"] for phase in spec["phases"]] == [1, 2, 3, 4, 5, 6]
|
||||
assert [phase["issue_number"] for phase in spec["phases"]] == [548, 549, 550, 551, 552, 553]
|
||||
|
||||
|
||||
def test_phase_two_unlocks_when_uptime_and_capacity_thresholds_are_met():
|
||||
spec = load_spec()
|
||||
result = evaluate_progression(
|
||||
spec,
|
||||
issue_states={548: "open", 549: "open", 550: "open", 551: "open", 552: "open", 553: "open"},
|
||||
resources={
|
||||
"uptime_percent_30d": 95.0,
|
||||
"capacity_utilization": 61.0,
|
||||
"innovation": 0,
|
||||
"all_models_local": False,
|
||||
"sovereign_stable_days": 0,
|
||||
"human_free_days": 0,
|
||||
},
|
||||
)
|
||||
|
||||
phase2 = result["phases"][1]
|
||||
assert phase2["unlocked"] is True
|
||||
assert result["current_phase"]["number"] == 2
|
||||
assert result["next_locked_phase"]["number"] == 3
|
||||
|
||||
|
||||
def test_phase_three_stays_locked_until_phase_two_issue_is_closed():
|
||||
spec = load_spec()
|
||||
result = evaluate_progression(
|
||||
spec,
|
||||
issue_states={548: "open", 549: "open", 550: "open", 551: "open", 552: "open", 553: "open"},
|
||||
resources={
|
||||
"uptime_percent_30d": 99.0,
|
||||
"capacity_utilization": 90.0,
|
||||
"innovation": 250,
|
||||
"all_models_local": False,
|
||||
"sovereign_stable_days": 0,
|
||||
"human_free_days": 0,
|
||||
},
|
||||
)
|
||||
|
||||
phase3 = result["phases"][2]
|
||||
assert phase3["unlocked"] is False
|
||||
blockers = {item["rule"] for item in phase3["blocking_requirements"]}
|
||||
assert blockers == {"phase_2_issue_closed"}
|
||||
|
||||
|
||||
def test_phase_five_requires_sovereign_stability_and_innovation():
|
||||
spec = load_spec()
|
||||
result = evaluate_progression(
|
||||
spec,
|
||||
issue_states={548: "closed", 549: "closed", 550: "closed", 551: "closed", 552: "open", 553: "open"},
|
||||
resources={
|
||||
"uptime_percent_30d": 99.0,
|
||||
"capacity_utilization": 85.0,
|
||||
"innovation": 400,
|
||||
"all_models_local": True,
|
||||
"sovereign_stable_days": 12,
|
||||
"human_free_days": 0,
|
||||
},
|
||||
)
|
||||
|
||||
phase5 = result["phases"][4]
|
||||
assert phase5["unlocked"] is False
|
||||
blockers = {item["rule"] for item in phase5["blocking_requirements"]}
|
||||
assert blockers == {"innovation_gt_500", "sovereign_stable_days_gte_30"}
|
||||
|
||||
|
||||
def test_epic_complete_only_when_all_phase_issues_are_closed_and_phase_six_unlocked():
|
||||
spec = load_spec()
|
||||
result = evaluate_progression(
|
||||
spec,
|
||||
issue_states={548: "closed", 549: "closed", 550: "closed", 551: "closed", 552: "closed", 553: "closed"},
|
||||
resources={
|
||||
"uptime_percent_30d": 99.5,
|
||||
"capacity_utilization": 85.0,
|
||||
"innovation": 900,
|
||||
"all_models_local": True,
|
||||
"sovereign_stable_days": 45,
|
||||
"human_free_days": 9,
|
||||
},
|
||||
)
|
||||
|
||||
assert result["epic_complete"] is True
|
||||
assert result["current_phase"]["number"] == 6
|
||||
assert result["next_locked_phase"] is None
|
||||
@@ -1,319 +0,0 @@
|
||||
# GENOME.md — the-nexus
|
||||
|
||||
**Generated:** 2026-04-14
|
||||
**Repo:** Timmy_Foundation/the-nexus
|
||||
**Analysis:** Codebase Genome #672
|
||||
|
||||
---
|
||||
|
||||
## Project Overview
|
||||
|
||||
The Nexus is Timmy's canonical 3D home-world — a browser-based Three.js application that serves as:
|
||||
1. **Local-first training ground** for Timmy (the sovereign AI)
|
||||
2. **Wizardly visualization surface** for the fleet system
|
||||
3. **Portal architecture** connecting to other worlds and services
|
||||
|
||||
The app is a real-time 3D environment with spatial memory, GOFAI reasoning, agent presence, and portal-based navigation.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph Browser["BROWSER LAYER"]
|
||||
HTML[index.html]
|
||||
APP[app.js - 4082 lines]
|
||||
CSS[style.css]
|
||||
Worker[gofai_worker.js]
|
||||
end
|
||||
|
||||
subgraph ThreeJS["THREE.JS RENDERING"]
|
||||
Scene[Scene Management]
|
||||
Camera[Camera System]
|
||||
Renderer[WebGL Renderer]
|
||||
Post[Post-processing<br/>Bloom, SMAA]
|
||||
Physics[Physics/Player]
|
||||
end
|
||||
|
||||
subgraph Nexus["NEXUS COMPONENTS"]
|
||||
SM[SpatialMemory]
|
||||
SA[SpatialAudio]
|
||||
MB[MemoryBirth]
|
||||
MO[MemoryOptimizer]
|
||||
MI[MemoryInspect]
|
||||
MP[MemoryPulse]
|
||||
RT[ReasoningTrace]
|
||||
RV[ResonanceVisualizer]
|
||||
end
|
||||
|
||||
subgraph GOFAI["GOFAI REASONING"]
|
||||
Worker2[Web Worker]
|
||||
Rules[Rule Engine]
|
||||
Facts[Fact Store]
|
||||
Inference[Inference Loop]
|
||||
end
|
||||
|
||||
subgraph Backend["BACKEND SERVICES"]
|
||||
Server[server.py<br/>WebSocket Bridge]
|
||||
L402[L402 Cost API]
|
||||
Portal[Portal Registry]
|
||||
end
|
||||
|
||||
subgraph Data["DATA/PERSISTENCE"]
|
||||
Local[localStorage]
|
||||
IDB[IndexedDB]
|
||||
JSON[portals.json]
|
||||
Vision[vision.json]
|
||||
end
|
||||
|
||||
HTML --> APP
|
||||
APP --> ThreeJS
|
||||
APP --> Nexus
|
||||
APP --> GOFAI
|
||||
APP --> Backend
|
||||
APP --> Data
|
||||
|
||||
Worker2 --> APP
|
||||
Server --> APP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entry Points
|
||||
|
||||
### Primary Entry
|
||||
- **`index.html`** — Main HTML shell, loads app.js
|
||||
- **`app.js`** — Main application (4082 lines), Three.js scene setup
|
||||
|
||||
### Secondary Entry Points
|
||||
- **`boot.js`** — Bootstrap sequence
|
||||
- **`bootstrap.mjs`** — ES module bootstrap
|
||||
- **`server.py`** — WebSocket bridge server
|
||||
|
||||
### Configuration Entry Points
|
||||
- **`portals.json`** — Portal definitions and destinations
|
||||
- **`vision.json`** — Vision/agent configuration
|
||||
- **`config/fleet_agents.json`** — Fleet agent definitions
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
```
|
||||
User Input
|
||||
↓
|
||||
app.js (Event Loop)
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Three.js Scene │
|
||||
│ - Player movement │
|
||||
│ - Camera controls │
|
||||
│ - Physics simulation │
|
||||
│ - Portal detection │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Nexus Components │
|
||||
│ - SpatialMemory (room/context) │
|
||||
│ - MemoryBirth (new memories) │
|
||||
│ - MemoryPulse (heartbeat) │
|
||||
│ - ReasoningTrace (GOFAI output) │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ GOFAI Worker (off-thread) │
|
||||
│ - Rule evaluation │
|
||||
│ - Fact inference │
|
||||
│ - Decision making │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────┐
|
||||
│ Backend Services │
|
||||
│ - WebSocket (server.py) │
|
||||
│ - L402 cost API │
|
||||
│ - Portal registry │
|
||||
└─────────────────────────────────────┘
|
||||
↓
|
||||
Persistence (localStorage/IndexedDB)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
### 1. Nexus Object (`NEXUS`)
|
||||
Central configuration and state object containing:
|
||||
- Color palette
|
||||
- Room definitions
|
||||
- Portal configurations
|
||||
- Agent settings
|
||||
|
||||
### 2. SpatialMemory
|
||||
Manages room-based context for the AI agent:
|
||||
- Room transitions trigger context switches
|
||||
- Facts are stored per-room
|
||||
- NPCs have location awareness
|
||||
|
||||
### 3. Portal System
|
||||
Connects the 3D world to external services:
|
||||
- Portals defined in `portals.json`
|
||||
- Each portal links to a service/endpoint
|
||||
- Visual indicators in 3D space
|
||||
|
||||
### 4. GOFAI Worker
|
||||
Off-thread reasoning engine:
|
||||
- Rule-based inference
|
||||
- Fact store with persistence
|
||||
- Decision making for agent behavior
|
||||
|
||||
### 5. Memory Components
|
||||
- **MemoryBirth**: Creates new memories from interactions
|
||||
- **MemoryOptimizer**: Compresses and deduplicates memories
|
||||
- **MemoryPulse**: Heartbeat system for memory health
|
||||
- **MemoryInspect**: Debug/inspection interface
|
||||
|
||||
---
|
||||
|
||||
## API Surface
|
||||
|
||||
### Internal APIs (JavaScript)
|
||||
|
||||
| Module | Export | Purpose |
|
||||
|--------|--------|---------|
|
||||
| `app.js` | `NEXUS` | Main config/state object |
|
||||
| `SpatialMemory` | class | Room-based context management |
|
||||
| `SpatialAudio` | class | 3D positional audio |
|
||||
| `MemoryBirth` | class | Memory creation |
|
||||
| `MemoryOptimizer` | class | Memory compression |
|
||||
| `ReasoningTrace` | class | GOFAI reasoning visualization |
|
||||
|
||||
### External APIs (HTTP/WebSocket)
|
||||
|
||||
| Endpoint | Protocol | Purpose |
|
||||
|----------|----------|---------|
|
||||
| `ws://localhost:PORT` | WebSocket | Real-time bridge to backend |
|
||||
| `http://localhost:8080/api/cost-estimate` | HTTP | L402 cost estimation |
|
||||
| Portal endpoints | Various | External service connections |
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Runtime Dependencies
|
||||
- **Three.js** — 3D rendering engine
|
||||
- **Three.js Addons** — Post-processing (Bloom, SMAA)
|
||||
|
||||
### Build Dependencies
|
||||
- **ES Modules** — Native browser modules
|
||||
- **No bundler** — Direct script loading
|
||||
|
||||
### Backend Dependencies
|
||||
- **Python 3.x** — server.py
|
||||
- **WebSocket** — Real-time communication
|
||||
|
||||
---
|
||||
|
||||
## Test Coverage
|
||||
|
||||
### Existing Tests
|
||||
- `tests/boot.test.js` — Bootstrap sequence tests
|
||||
|
||||
### Test Gaps
|
||||
1. **Three.js scene initialization** — No tests
|
||||
2. **Portal system** — No tests
|
||||
3. **Memory components** — No tests
|
||||
4. **GOFAI worker** — No tests
|
||||
5. **WebSocket communication** — No tests
|
||||
6. **Spatial memory transitions** — No tests
|
||||
7. **Physics/player movement** — No tests
|
||||
|
||||
### Recommended Test Priorities
|
||||
1. Portal detection and activation
|
||||
2. Spatial memory room transitions
|
||||
3. GOFAI worker message passing
|
||||
4. WebSocket connection handling
|
||||
5. Memory persistence (localStorage/IndexedDB)
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Current Risks
|
||||
1. **WebSocket without auth** — server.py has no authentication
|
||||
2. **localStorage sensitive data** — Memories stored unencrypted
|
||||
3. **CORS open** — No origin restrictions on WebSocket
|
||||
4. **L402 endpoint** — Cost API may expose internal state
|
||||
|
||||
### Mitigations
|
||||
1. Add WebSocket authentication
|
||||
2. Encrypt sensitive memories
|
||||
3. Restrict CORS origins
|
||||
4. Rate limit L402 endpoint
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
the-nexus/
|
||||
├── app.js # Main app (4082 lines)
|
||||
├── index.html # HTML shell
|
||||
├── style.css # Styles
|
||||
├── server.py # WebSocket bridge
|
||||
├── boot.js # Bootstrap
|
||||
├── bootstrap.mjs # ES module bootstrap
|
||||
├── gofai_worker.js # GOFAI web worker
|
||||
├── portals.json # Portal definitions
|
||||
├── vision.json # Vision config
|
||||
├── nexus/ # Nexus components
|
||||
│ └── components/
|
||||
│ ├── spatial-memory.js
|
||||
│ ├── spatial-audio.js
|
||||
│ ├── memory-birth.js
|
||||
│ ├── memory-optimizer.js
|
||||
│ ├── memory-inspect.js
|
||||
│ ├── memory-pulse.js
|
||||
│ ├── reasoning-trace.js
|
||||
│ └── resonance-visualizer.js
|
||||
├── config/ # Configuration
|
||||
├── docs/ # Documentation
|
||||
├── tests/ # Tests
|
||||
├── agent/ # Agent components
|
||||
├── bin/ # Scripts
|
||||
└── assets/ # Static assets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Debt
|
||||
|
||||
1. **Large app.js** (4082 lines) — Should be split into modules
|
||||
2. **No TypeScript** — Pure JavaScript, no type safety
|
||||
3. **Manual DOM manipulation** — Could use a framework
|
||||
4. **No build system** — Direct ES modules, no optimization
|
||||
5. **Limited error handling** — Minimal try/catch coverage
|
||||
|
||||
---
|
||||
|
||||
## Migration Notes
|
||||
|
||||
From CLAUDE.md:
|
||||
- Current `main` does NOT ship the old root frontend files
|
||||
- A clean checkout serves a directory listing
|
||||
- The live browser shell exists in legacy form at `/Users/apayne/the-matrix`
|
||||
- Migration priorities: #684 (docs), #685 (legacy audit), #686 (smoke tests), #687 (restore shell)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Restore browser shell** — Bring frontend back to main
|
||||
2. **Add tests** — Cover critical paths (portals, memory, GOFAI)
|
||||
3. **Split app.js** — Modularize the 4082-line file
|
||||
4. **Add authentication** — Secure WebSocket and APIs
|
||||
5. **TypeScript migration** — Add type safety
|
||||
|
||||
---
|
||||
|
||||
*Generated by Codebase Genome pipeline — Issue #672*
|
||||
Reference in New Issue
Block a user