2125_GCE/TECHNICAL_DOCUMENTATION.md

# Glyph Compression Executor — Technical Documentation

## Architecture Overview

### Dual-Layer Symbolic System

SuperDave 2125 implements a **dual-layer architecture**:

#### Computational Layer
- **Purpose**: Execute Python code through compressed binary format
- **Components**:
  - GSZ3 compression (zlib + SHA256 checksum)
  - XIC binary format (XIC header + JSON manifest + compressed payload)
  - LAIN 8-lane cognition engine
  - Segment runtime executor

#### Symbolic Layer
- **Purpose**: Analyze code through 600 specialized glyphs with 152 superpowers
- **Components**:
  - LedoGlyph600 registry (600 glyphs)
  - Superpower registry (152 superpowers)
  - Multi-glyph resonance calculation
  - Glyph activation from intent

### Data Flow

```
Python Source → GSZ3 Compress → XIC Pack → LAIN Cognition → Execution Result
```

### Compression Pipeline

1. **Segmentation**: Split code into logical segments
2. **Compression**: GSZ3 format (zlib level 9 + SHA256[:3] checksum)
3. **Packing**: XIC binary format with JSON manifest
4. **Execution**: Decompress → Execute through LAIN → Return fused symbol

---

## 600 Glyphs System

### G001 (Ledo/Aether Node) - The Root Glyph

**Unique Properties**:
- **152 superpowers** (ALL available)
- **Specialized Type**: `aether_node`
- **Power Boost**: 387.95x (38,695% effectiveness increase)
- **VRAM Budget**: 7.5GB (maximum for GTX 1080)
- **Priority**: 10.0 (maximum)
- **Constraints**: None (primordial authority)
- **Enhancements**: `universal_override`, `primordial_resonance`, `system_root_access`

**Purpose**: G001 is the **primordial root glyph** that holds all system authority. It cannot be replicated by any other glyph.

### Other Glyphs (G002-G600)

**Superpower Limits**:
- **Min**: 9 superpowers
- **Max**: 22 superpowers
- **Most Common**: 15 superpowers (269 glyphs)

**Distribution**:
```
9-10: 7 glyphs
11-12: 54 glyphs
13-15: 485 glyphs
16-22: 54 glyphs
152: 1 glyph (G001 only)
```

### Glyph Categories

| Category | Count | Purpose |
|----------|-------|---------|
| neural | 75 | Core cognition |
| communication | 72 | Data transfer |
| defense | 68 | Security |
| energy | 65 | Power management |
| life-support | 62 | System stability |
| navigation | 58 | Path finding |
| propulsion | 55 | Movement control |
| research | 55 | Discovery |

---

## 152 Superpowers

### Superpower Bands

| Band | Range | Purpose |
|------|-------|---------|
| A | 1-15 | Foundational operations |
| B | 16-45 | Advanced processing |
| C | 46-76 | Specialized functions |
| D | 77-152 | Advanced capabilities |

### Boost Calculation

```python
power_boost = 1.0 + Σ(boost_percent) / 100.0
```

**Example**:
- G001 with 152 superpowers: **387.95x**
- G002 with 18 superpowers: **14.50x**
- G050 with 15 superpowers: **8.25x**

### Top Superpowers

| ID | Name | Boost | Band |
|----|------|-------|------|
| 1 | DNA Supercoiling Access | +65% | A |
| 77 | MOF Fluidic Ion Transistor | +250% | D |
| 100 | Superheavy Element Synthesis | +450% | D |
| 152 | Neuralink-Style Brain-Computer Interface | +480% | D |

---

## GSZ3 Compression

### Format Specification

```
Header (12 bytes):
  [0-3]   Magic: "GSZ3" (0x47535A33)
  [4]     Version: 1
  [5-8]   Payload Length (uint32, big-endian)
  [9-11]  Checksum: SHA256(payload)[:3]

Payload:
  zlib level 9 compressed data
```

### Compression Algorithm

1. UTF-8 encode text
2. zlib compress (level 9)
3. SHA256 hash compressed data
4. Take first 3 bytes as checksum
5. Concatenate: Magic + Version + Length + Checksum + Compressed Data

### Decompression Algorithm

1. Verify magic number
2. Read version
3. Read payload length
4. Verify checksum
5. zlib decompress
6. UTF-8 decode

---

## LAIN 8-Lane Symbolic Cognition

### Lane Assignment Algorithm

Lanes are assigned based on **segment content analysis**:

```python
def _infer_lane_from_content(content):
    if has_control_flow: return 0   # if, for, while, return, try, except, with
    elif has_comments: return 3     # #, //, /*, */
    elif has_hints: return 4        # hint, note, todo, fixme, warning, danger
    elif has_metadata: return 3     # <glyph:, metadata, tag, annotation
    elif has_execution_hints: return 4  # rm -rf, del, os.system, subprocess
    elif has_template: return 5     # step, todo:, placeholder, fill-in
    elif has_contributor: return 6  # author, contributor, copyright, @
    elif has_epoch: return 7        # epoch, timestamp, date, time, version
    else: return 1                  # default semantic flow
```

### Lane Processing

Each lane processes segments with specialized handlers:

| Lane | Processor | Output |
|------|-----------|--------|
| 0 | structural_logic | Control flow analysis |
| 1 | semantic_flow | Core meaning extraction |
| 2 | compression_residue | Artifact detection |
| 3 | symbolic_metadata | Tag/annotation analysis |
| 4 | execution_hints | Safety analysis |
| 5 | predictive_scaffolding | Pattern prediction |
| 6 | contributor_imprint | Author style detection |
| 7 | epoch_resonance | Temporal context |

---

## Multi-Glyph Resonance

### Calculation Formula

For each glyph, compute 5-dimensional metrics:

```python
weight = (glyph_score / 335) * 0.7 + (activation_score / 100) * 0.3
lineage_score = inheritance_weight
contributor_score = connectivity / 100
frequency_score = sqrt(P² + R² + A² + W²) / 200
grammar_score = stability / 100
```

### Global Resonance

```python
global_resonance = Σ(weight) / count
```

---

## Superpower Assignment Algorithm

### Power Count Formula

```python
power_count = 5 + int((avg_metric / 100) * 20)
```

Where `avg_metric = (power + complexity + resonance + stability + connectivity + affinity) / 6`

### Band Eligibility

| Tier | Bands | Rule |
|------|-------|------|
| G001 | A, B, C, D | Aether node (all bands) |
| G002-G150 | A, B | Tier 1-15 |
| G151-G300 | B, C | Tier 16-30 |
| G301-G450 | C, D | Tier 31-45 |
| G451-G600 | D, C | Tier 46-60 |

### Superpower Scoring

```python
score = 0.45 × metrics + 0.35 × type_bias + 0.15 × boost% + 0.05 × hash
```

Where:
- `metrics` = average of glyph metrics (0-100)
- `type_bias` = 100 if preferred, 25 if not
- `boost%` = superpower boost percentage
- `hash` = deterministic variety (MD5 of glyph_id + superpower_id)

---

## File Format Specifications

### .gx Binary Format

```
Header (8 bytes):
  [0-2]   Magic: "XIC" (0x584943)
  [3]     Version: 1
  [4-7]   Manifest Length (uint32, big-endian)

Manifest (variable length):
  JSON with keys:
    - magic: "GXIC1"
    - version: 1
    - source_file: str
    - source_type: str
    - version_str: str
    - contributor: str
    - timestamp: ISO 8601
    - codex_lineage: {
        segments: [{
          id: str,
          start: int,
          end: int,
          start_byte: int,
          end_byte: int
        }]
      }

Payload:
  GSZ3 compressed data
```

### JSON Manifest Format

```json
{
  "magic": "GXIC1",
  "version": 1,
  "source_file": "test.py",
  "source_type": ".py",
  "version_str": "1.0.0",
  "contributor": "GlyphRunner",
  "timestamp": "2026-06-14T00:00:00Z",
  "codex_lineage": {
    "segments": [
      {
        "id": "seg_0",
        "start": 0,
        "end": 5,
        "start_byte": 0,
        "end_byte": 54
      }
    ]
  }
}
```

---

## API Reference

### Symbolic Activation

```bash
POST /api/symbolic/activate
Content-Type: application/json

{
  "intent": "I need creative image generation",
  "request_type": "image",
  "metrics": {
    "power": 75,
    "resonance": 70
  }
}

Response:
{
  "status": "success",
  "glyph_id": "G002",
  "specialized_type": "star_bloom_creativity",
  "model": "forge",
  "priority": 8.5,
  "resonance_score": 87.3,
  "power_boost": 14.50,
  "superpower_count": 18,
  "routing": {
    "constraints": ["max_vram: 6.5GB"],
    "enhancements": ["bloomflare_engine"],
    "vram_budget": 6.5
  }
}
```

### System Status

```bash
GET /api/status

Response:
{
  "status": "operational",
  "vram": {
    "used_gb": 6.1,
    "total_gb": 8.0,
    "percent": 76.25
  },
  "vram_status": "VRAM safe",
  "models_running": {
    "llama": "available",
    "forge": "available",
    "janus": "pending",
    "google_ai": "unconfigured"
  },
  "vram_mode": "8GB",
  "compression": {
    "enabled": true,
    "format": "GSZ3",
    "glyphmart": "ready"
  }
}
```

---

## Performance Metrics

| Operation | Time | Notes |
|-----------|------|-------|
| Load 600 glyphs | <5ms | From JSON |
| Load 152 superpowers | <2ms | From JSON |
| Compress 1KB source | <1ms | GSZ3 + zlib |
| Decompress payload | <0.5ms | GSZ3 |
| Execute through LAIN | ~15ms | 8 lanes |
| Multi-glyph resonance | <50ms | 3 glyphs |
| Glyph activation | <10ms | Full pipeline |

---

## Testing

### Unit Tests

```bash
python3 tests/test_supercharged_registry.py
python3 tests/test_lain_glyph_bridge.py
python3 tests/test_cognitive_kernel.py
python3 tests/test_events.py
python3 tests/test_control_flow.py
```

### Integration Tests

```bash
python3 integration_tests/test_compile.py
python3 integration_tests/test_run.py
python3 integration_tests/test_inspect.py
python3 integration_tests/test_summary.py
python3 integration_tests/test_errors.py
python3 integration_tests/test_determinism.py
```

### Benchmark Tests

```bash
python3 benchmark/benchmark_superpowers.py
python3 benchmark/run_all_benchmarks.py
```

---

## Configuration

### Environment Variables

```bash
# VRAM mode
export VRAM_MODE="8GB"  # 8GB, 24GB, 48GB

# External endpoints
export FEDMART_ENDPOINT="http://localhost:8000/fedmart/ingest/xic"
export TABBY_API="http://192.168.2.12:11436"
export GOOGLE_API_KEY="your_key_here"
```

### VRAM Configuration

```python
VRAM_WARNING = 6.5   # GB
VRAM_CRITICAL = 7.8  # GB
TOTAL_VRAM = 8.0     # GB (GTX 1080)
```

---

## Troubleshooting

### VRAM Critical

**Symptom**: OOM during pipeline load

**Solution**: 
- Use `device_map="balanced"` mode
- Reduce batch size
- Close other models (Forge + Janus conflict)

### Compression Checksum Mismatch

**Symptom**: `GSZ3DecompressionError: Checksum mismatch`

**Solution**:
- Verify file integrity
- Re-compress source
- Check for file corruption

### Glyph Not Found

**Symptom**: `Glyph G001 not found`

**Solution**:
- Verify `supercharged_glyphs.json` exists
- Check file path in `super_registry.py`
- Run `glyph_explorer.py test`

---

## Future Enhancements

- [ ] Llama Chat integration (Pinokio)
- [ ] Janus Video generation (Pinokio)
- [ ] Google AI Vision (Gemini/Vertex)
- [ ] Database persistence for telemetry
- [ ] Authentication on endpoints
- [ ] Prometheus/Grafana metrics export
- [ ] PDF report generation
- [ ] Multi-run comparison view

---

**Version**: 2.0.0  
**Build Date**: June 14, 2026  
**Status**: ✅ Production Ready