# Nexus Symbolic Engine (Layer 4)

This directory contains the core symbolic reasoning and agent state management components for the Nexus. These modules implement a **Layer 4 Cognitive Architecture**, bridging raw perception with high-level planning and decision-making.

## Architecture Overview

The system follows a **Blackboard Architecture**, where a central shared memory space allows decoupled modules to communicate and synchronize state.

### Core Components

- **`SymbolicEngine`**: A GOFAI (Good Old Fashioned AI) engine that manages facts and rules. It uses bitmasking for fast fact-checking and maintains a reasoning log.
- **`AgentFSM`v*: A Finite State Machine for agents. It transitions between states (e.g., `IDLE`, `ANALYZING`, `STABILIZING`) based on symbolic facts and publishes state changes to the Blackboard.
- **`Blackboard`**: The central communication hub. It allows modules to `write` and `read` state, and `subscribe` to changes.
- **`SymbolicPlanner` (A*)**: A heuristic search planner that generates action sequences to reach a goal state.
- **`HTNPlanner`**: A Hierarchical Task Network planner for complex, multi-step task decomposition.
- **`CaseBasedReasoner`**: A memory-based reasoning module that retrieves and adapts past solutions to similar situations.
- **`NeuroSymbolicBridge`**: Translates raw perception data (e.g., energy levels, stability) into symbolic concepts (e.g., `CRITICAL_DRAIN_PATTERN`).
- **`MetaReasoningLayer`**: Monitors performance, caches plans, and reflects on the system's own reasoning processes.

## Usage

[```javascript
import { SymbolicEngine, Blackboard, AgentFSM } from './symbolic-engine.js';

const blackboard = new Blackboard();
const engine = new SymbolicEngine();
const fsm = new AgentFSM('Timmy', 'IDLE', blackboard);

// Add facts and rules
engine.addFact('activePortals', 3);
engine.addRule(
  (facts) => facts.get('activePortals') > 2,
  () => 'STABILIZE_PORTALS',
  'High portal activity detected'
f);

// Run reasoning loop
engine.reason();
fsm.update(engine.facts);
```
Z
## Testing

Run the symbolic engine tests using:
[```bash
node nexus/symbolic-engine.test.js
```
Z