Sphere-Vortex Framework

███████╗██████╗ ██╗  ██╗███████╗██████╗ ███████╗    ██╗   ██╗ ██████╗ ██████╗ ████████╗███████╗██╗  ██╗
██╔════╝██╔══██╗██║  ██║██╔════╝██╔══██╗██╔════╝    ██║   ██║██╔═══██╗██╔══██╗╚══██╔══╝██╔════╝╚██╗██╔╝
███████╗██████╔╝███████║█████╗  ██████╔╝█████╗█████╗██║   ██║██║   ██║██████╔╝   ██║   █████╗   ╚███╔╝
╚════██║██╔═══╝ ██╔══██║██╔══╝  ██╔══██╗██╔══╝╚════╝╚██╗ ██╔╝██║   ██║██╔══██╗   ██║   ██╔══╝   ██╔██╗
███████║██║     ██║  ██║███████╗██║  ██║███████╗     ╚████╔╝ ╚██████╔╝██║  ██║   ██║   ███████╗██╔╝ ██╗
╚══════╝╚═╝     ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝      ╚═══╝   ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝

AI-Native Cognitive Architecture with Sphere-Vortex Foundations

Dual-layer architecture bridging AI cognition and mathematical physics through Kuramoto oscillator dynamics, Hebbian STDP learning, and non-anthropocentric automation.

---

Table of Contents

• Overview
• Quick Start
• Architecture
• Project Structure
• Core Components
• Configuration
• State Management
• Specifications
• Claude Code Integration
• ULTRAPLATE Integration
• Development
• Quality Standards
• Documentation Index

---

Overview

The Sphere-Vortex Framework implements a novel cognitive architecture that bridges:

1. AI Cognitive Interface - Relevance scoring, semantic proximity, attention diffusion
2. Mathematical Substrate - Kuramoto oscillators, wave dynamics, spherical harmonics

Key innovations:

• L09 Advanced Monitoring - Welford's anomaly detection, EMA resonance, flow health (200ms cycle)
• L10 Emergent Behaviour - 5 pattern detection algorithms, signal aggregation, catalyst (500ms cycle)
• L11 Omniscience Loop - 4-phase coherence cycle (Measurement → Evaluation → Adaptation → Verification, 100ms)
• L12 Evolution Chamber - NSGA-II multi-objective genetic algorithm, 8 evolvable parameters (5000ms cycle)
• Hebbian STDP Learning - Spike-timing dependent plasticity for pathway reinforcement
• Homeostatic Regulation - Automatic LTP:LTD ratio maintenance (target: 2.0-4.0)
• NEXUS Collision Detection - Module dependency conflict resolution
• Non-Anthropocentric Automation - 14 Claude Code hooks for autonomous operation
• 32 API Routes - Full REST API with Prometheus metrics (25 gauges/counters)
• 1,309 Tests - 995 library + 314 integration/e2e tests, all passing

See MASTER_INDEX.md for the complete project inventory See .claude/CLAUDE.md for context bootstrap

---

Quick Start

# Clone and build
git clone <repository>
cd sphere_vortex_framework

# Build release
cargo build --release

# Run tests
cargo test

# Clippy compliance (god-tier)
cargo clippy -- -D warnings -W clippy::pedantic

# Start service (port 8120)
./target/release/sphere_vortex --config config/sphere_vortex.toml

# Health check
curl http://localhost:8120/health

See ai_specs/SPEC_008_DEPLOYMENT_PROCEDURES.md for detailed deployment

---

Architecture

Layer 1: AI Cognitive Interface

Component	Symbol	Description
Relevance Scores	rᵢ ∈ [0,1]	Context relevance weighting
Semantic Proximity	d(a,b)	Distance in embedding space
Attention Diffusion	∇·A	Attention flow dynamics
Episodic Memory	Mₑ	Experience-based injection

Layer 2: Mathematical Substrate

Component	Formula	Description
Kuramoto Dynamics	dφᵢ/dt = ωᵢ + (K/N)·Σⱼ sin(φⱼ - φᵢ)	Oscillator synchronization
Order Parameter	r·e^(iψ) = (1/N)·Σ e^(iφⱼ)	Synchronization measure
Wave Equation	∇²Ψ - (1/c²)∂²Ψ/∂t² = 0	Wave propagation
Spherical Harmonics	Yₗᵐ(θ,φ)	Angular decomposition

See ai_docs/CONTEXT_BRIDGE_PART1_FOUNDATION.md for architecture details

---

Project Structure

sphere_vortex_framework/
├── README.md                    # This file
├── MASTER_INDEX.md              # Complete project inventory
├── Cargo.toml                   # Rust dependencies
│
├── src/                         # Source code (37 files, 9 module directories)
│   ├── core/                    # M1-M3: Foundation
│   ├── vortex/                  # M4-M8: Mathematical substrate
│   ├── mesh/                    # M9-M11: Service mesh
│   ├── cognitive/               # M12-M14: Cognitive tools (18)
│   ├── learning/                # M15-M17: Hebbian STDP
│   ├── bridge/                  # M18: Translation + EventBridge
│   ├── nexus/                   # M19-M21: Collision detection
│   ├── events/                  # M22-M23: Event system
│   └── omniscience/             # L11: Omniscience loop (IMPLEMENTED)
│
├── config/                      # Configuration (12 files)
│   ├── sphere_vortex.toml       # Main configuration
│   ├── dev.toml                 # Development overrides
│   ├── staging.toml             # Staging overrides
│   ├── prod.toml                # Production overrides
│   ├── vortex.toml              # Vortex dynamics
│   ├── learning.toml            # Learning system
│   ├── cognitive_tools.toml     # Cognitive tools
│   ├── services.toml            # Service mesh
│   ├── database.toml            # Database
│   ├── logging.toml             # Logging
│   └── metrics.toml             # Metrics & tracing
│
├── .claude/                     # Claude Code integration
│   ├── CLAUDE.md                # Context bootstrap
│   ├── settings.json            # Hook configuration
│   ├── hooks/                   # 14 automation hooks
│   ├── skills/                  # 10 cognitive skills
│   └── state/                   # Runtime state (12 files)
│
├── ai_docs/                     # Architecture documentation
│   ├── QUICKSTART.md            # Navigation hub
│   ├── layers/                  # Layer specs (L01-L11)
│   └── modules/                 # Module specs (M01-M23)
│
├── ai_specs/                    # Specifications (14 files)
│   ├── SPEC_INDEX.md            # Specification index
│   ├── SPEC_001-010_*.md        # Core specifications
│   ├── API_SPEC.md              # API documentation
│   └── openapi.yaml             # OpenAPI 3.0
│
└── migrations/                  # Database schemas (7 files)

---

Core Components

Source Modules (23 + Omniscience)

Layer	Modules	Purpose
L01 Core	M1-M3	Foundation types, errors (15), config (7 sections)
L02 Vortex	M4-M8	Kuramoto, wave, momentum, harmonics
L03 Mesh	M9-M11	Service mesh, health, circuit breaker
L04 Cognitive	M12-M14	18 cognitive tools
L05 Learning	M15-M17	Hebbian STDP, homeostatic
L06 Bridge	M18+	Layer 1 ↔ Layer 2 translation + EventBridge
L07 NEXUS	M19-M21	Collision detection, routing
L08 Events	M22-M23	Event system, dispatcher
L11 Omniscience	Implemented	4-phase coherence loop, adaptation signals

Cognitive Tools (18 Total)

Priority	Count	Tools
P0 Critical	6	observe_self, observe_context, query_pathways, reflect_session, compute_order_parameter, get_unified_state
P1 High	5	suggest_next_tools, detect_collisions, route_query, kuramoto_step, compute_critical_coupling
P2 Medium	5	track_momentum, record_synergy, detect_vortex, compute_interior_field, detect_feedback_loop
P3 Low	2	compute_angular_momentum, analyze_harmonics

See ai_specs/SPEC_002_COGNITIVE_TOOLS.md for tool specifications

---

Configuration

Configuration Files (12 Total)

File	Purpose
sphere_vortex.toml	Main configuration with all settings
dev.toml	Development: debug logging, relaxed timeouts
staging.toml	Staging: production-like with full tracing
prod.toml	Production: optimized, strict security
vortex.toml	Vortex dynamics: Kuramoto, wave, harmonics
learning.toml	Learning: STDP, homeostatic, pathways
cognitive_tools.toml	Tools: 17 tools with schemas and timeouts
services.toml	Mesh: 9 ULTRAPLATE services
database.toml	Database: SQLite with migrations
logging.toml	Logging: levels, formats, rotation
metrics.toml	Metrics: Prometheus, OpenTelemetry

Key Settings

# Server
port = 8120

# Vortex
coupling_strength = 2.5
oscillator_count = 17
coherence_threshold = 0.85

# Learning
ltp_rate = 0.1
ltd_rate = 0.05
stdp_window_ms = 100

# Homeostatic Targets
target_relevance = 0.85
target_coherence = 0.90
target_synergy = 0.85

See config/README.md for configuration documentation

---

State Management

Runtime State Files (12 Total)

File	Layer	Purpose
unified_state.json	All	Complete system state
module_tensors.json	All	11D tensors for 23 modules
vortex_state.json	L02	Kuramoto oscillators, wave, momentum
learning_state.json	L05	STDP, homeostatic, pathways
mesh_state.json	L03	Service health, circuit breakers
cognitive_state.json	L04	17 tools, introspection
nexus_state.json	L07	Collision, routing, synergy
event_state.json	L08	Event categories, dispatcher
bridge_state.json	L06	Translation functions
core_state.json	L01	Error counts, configuration
session_state.json	-	Session tracking

11D Tensor Dimensions

Index	Label	Range
0	module_id	[1, 23]
1	layer_id	[1, 8]
2	complexity	[0, 1]
3	synergy	[0, 1]
4	resonance	[0, 1]
5	tension	[0, 1]
6-8	momentum_xyz	[-1, 1]
9	coherence	[0, 1]
10	readiness	[0, 1]

See .claude/state/STATE_INDEX.md for state documentation

---

Specifications

Specification Files (10 Core + 4 API)

Spec	Purpose
SPEC_001	Architecture Paradigm
SPEC_002	Cognitive Tools (17)
SPEC_003	Memory & Learning
SPEC_004	Integration & Service Mesh
SPEC_005	Error Handling & Robustness
SPEC_006	Performance & Observability
SPEC_007	Security & Scalability
SPEC_008	Deployment Procedures
SPEC_009	Code Conventions
SPEC_010	Testing Requirements

See ai_specs/SPEC_INDEX.md for specification index

---

Claude Code Integration

Hooks (14 Total)

Event	Hooks
PreToolUse	compliance_guard, sensitive_file_guard, dead_code_detector, anti_pattern_scanner
PostToolUse	learning_recorder, code_formatter, homeostatic_monitor, ralph_loop_controller
SessionStart	context_loader
UserPromptSubmit	skill_detector
Stop	context_preserver
SubagentStop	subagent_tracker
Notification	synthex_notifier

Skills (10 Total)

Skill	Modules	Purpose
kuramoto-sync	M4	Oscillator synchronization
stdp-learning	M15-M17	STDP learning
compilation-compliance	All	God-tier clippy
testing-excellence	All	God-tier testing
framework-health	All	Health monitoring
module-tensor	M3	11D tensor analysis
nexus-collision	M19-M21	Collision detection
vortex-detect	M5-M8	Vortex patterns
homeostatic-tune	M16	Homeostatic control
anti-pattern	All	Anti-pattern detection

See .claude/hooks/HOOKS_INDEX.md for hook documentation

---

ULTRAPLATE Integration

Service	Port	Synergy
Sphere-Vortex	8120	-
SYNTHEX	8090	0.985
SAN-K7	8100	0.992
NAIS	8101	0.974
CodeSynthor V7	8110	0.985
Tool Library	8105	-

See config/services.toml for service configuration

---

Development

Prerequisites

• Rust 1.75+ (2021 edition)
• SQLite 3.x
• Python 3.9+ (for hooks)

Build Commands

# Development build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

# Clippy (god-tier)
cargo clippy -- -D warnings -W clippy::pedantic

# Format
cargo fmt -- --check

# Coverage
cargo tarpaulin --fail-under 80

# Run benchmarks
cargo bench

# Run specific benchmark
cargo bench --bench kuramoto_dynamics

Benchmarks (8 files)

Benchmark	Layer	Description
kuramoto_dynamics	L02	Oscillator integration, order parameter
pathway_learning	L05	STDP, homeostatic regulation
collision_detection	L07	NEXUS collision, routing, synergy
tensor_operations	L01	11D tensor manipulation
cognitive_tools	L04	Tool execution, planning
event_dispatch	L08	Event creation, dispatching
wave_dynamics	L02	Wave equation, harmonics

See benches/README.md for detailed benchmark documentation.

Environment-Specific Builds

# Development
cargo run -- --config config/sphere_vortex.toml --env dev

# Staging
./target/release/sphere_vortex --config config/sphere_vortex.toml --env staging

# Production
./target/release/sphere_vortex --config config/sphere_vortex.toml --env prod

---

Quality Standards

Quality Gates

Gate	Requirement
unsafe code	Zero
.unwrap()	Zero
.expect()	Zero
Clippy warnings	Zero
Test coverage	≥ 80%
Documentation	100% public items

Learning Parameters

LTP_RATE: 0.1           // Long-Term Potentiation
LTD_RATE: 0.05          // Long-Term Depression
STDP_WINDOW_MS: 100     // Timing window
HEALTHY_RATIO: 2.0-4.0  // LTP:LTD balance

See ai_specs/SPEC_009_CODE_CONVENTIONS.md for coding standards

---

Documentation Index

Core Documentation

Document	Location
MASTER_INDEX	MASTER_INDEX.md
CLAUDE.md	.claude/CLAUDE.md
QUICKSTART	ai_docs/QUICKSTART.md
SPEC_INDEX	ai_specs/SPEC_INDEX.md
STATE_INDEX	.claude/state/STATE_INDEX.md
Config README	config/README.md

Architecture Documentation

Document	Purpose
Part 1: Foundation	Core architecture
Part 2: Integration	Layer integration
Part 3: Resilience	Error handling
Part 4: Operations	Deployment

Layer & Module Documentation

Resource	Location
Layer Index	ai_docs/layers/LAYERS_INDEX.md
Module Index	ai_docs/modules/MODULES_INDEX.md

User Documentation (docs/)

Document	Audience	Description
INDEX	All	Documentation navigation
EXECUTIVE_SUMMARY	Executives	Vision and goals
ARCHITECTURE_OVERVIEW	Architects	System design
USER_GUIDE	Operators	Usage instructions
DEVELOPERS_GUIDE	Developers	Development guide
GLOSSARY	All	75 technical terms
FAQ	All	Common questions

---

Status

Version: 2.0.0 | Status: DEPLOYED | L11 Omniscience: IMPLEMENTED

Completed

Component	Count	Status
Source modules	23 + Omniscience	Implemented
Source files	37	Implemented
Tests (lib + integration)	1,070	All passing
Release binary	bin/sphere_vortex (4.4MB)	Built
Specifications	14	Complete
Config files	12	Complete
State files	12	Complete
Migrations	7	Complete
Skills	10	Complete
Hooks	14	Complete

L11 Omniscience Loop API

Endpoint	Method	Purpose
/api/omniscience/coherence	GET	Current coherence + severity
/api/omniscience/metrics	GET	Snapshots + oscillator state
/api/omniscience/adapt	POST	Trigger manual adaptation
/api/omniscience/history	GET	Historical coherence

---

Sphere-Vortex Framework v2.0.0 | 23 Modules + Omniscience | DEPLOYED Updated: 2026-01-31 | L11 Omniscience Loop Implemented | 1,070 Tests Passing