the-nexus/docs/symbolic-debugger.md

GOFAI Symbolic Engine Debugger Overlay

Refs: the-nexus #871

Overview

A specialized debug overlay that shows the internal state of the Symbolic Engine in real-time. Press Ctrl+Shift+G to toggle.

Features

1. Active Symbols Panel

Displays all facts currently in the symbolic engine with their truth values:

• Green ● = true
• Red ○ = false

2. FSM States Panel

Shows the current state of all registered finite state machines:

• Agent ID on the left
• Current state on the right (highlighted)

3. Reasoning Paths Panel

Chronological log of all reasoning steps:

• Timestamp
• Rule that fired
• Outcome produced

4. Knowledge Graph Panel

• Node count and edge count
• Mini visualization of graph topology (up to 15 nodes)
• Color-coded by type (Agent, Location, etc.)

5. Performance Metrics

• Number of facts
• Number of rules
• JavaScript heap usage (if available)

Usage

import { SymbolicDebugger } from './nexus/components/symbolic-debugger.js';
import { SymbolicEngine } from './nexus/symbolic-engine.js';

// Create engine
const engine = new SymbolicEngine();

// Initialize debugger
SymbolicDebugger.init({
  engine: engine,
  fsmRegistry: new Map(), // optional
  knowledgeGraph: null    // optional
});

// Show the overlay
SymbolicDebugger.show();

// Or toggle with Ctrl+Shift+G

Auto-refresh

The debugger updates automatically every second when visible. Manual refresh via the ↻ button.

Dragging

The overlay can be dragged by its header to reposition on screen.

Testing

node tests/test_symbolic_debugger.js