Update README.md

README.md

@@ -1,161 +1,251 @@
-# LOGOS: SPCW (Scalar Prime Composite Wave) Protocol
-
-A deterministic, non-linear data transport protocol that replaces sequential scanning with fractal addressing.
-
-## The Problem
-
-Modern transport (PCIe/Network) treats data as a linear stream ("The Cake"), creating bandwidth bottlenecks. Sequential scanning forces data to flow in memory address order, regardless of geometric significance.
-
-## The Solution
-
-LOGOS transmits generative instructions ("The Bake"). Using a 512-byte Atom architecture and Prime Modulo addressing, the receiver reconstructs the state fractally. Data is populated by geometric significance, not memory address order.
-
-## Key Features
-
-- **Fractal Address Space**: 32-bit Heat Codes mapped to Quadtree geometry
-- **Prime Constraint**: 9973 Modulo harmonization for signal integrity
-- **Non-Linear Reconstruction**: Data populated by geometric significance, not memory address order
-- **Compression via Geometry**: Only transmit "active" parts of the signal
-- **Infinite Canvas**: Supports up to 2^16 × 2^16 resolution (65,536 × 65,536 pixels)
-
-## Repository Structure
-
-```
-LOGOS_SPCW_Protocol/
-├── README.md               # This file
-├── logos_core.py           # The Math (Fractal Decoder + Prime Modulo)
-├── bake_stream.py          # The Encoder (Image -> SPCW)
-├── eat_cake.py             # The Player (SPCW -> Screen)
-├── data/                   # Sample files
-│   └── sample.spcw         # Pre-baked binary file
-└── requirements.txt        # numpy, opencv-python
-```
-
-## Installation
-
-```bash
-pip install -r requirements.txt
-```
-
-## Quick Start
-
-### 1. Bake an Image (Encode)
-
-```bash
-python bake_stream.py input.png output.spcw
-python bake_stream.py input.png output.spcw --tolerance 3.0  # Stricter fidelity
-```
-
-The Deep Baker uses bottom-up dissolution + pruning:
-- Dissolve to max depth (full inspection)
-- Collapse only when four children are identical within tolerance
-
-### 2. Eat the Cake (Decode/Playback)
-
-```bash
-python eat_cake.py output.spcw
-python eat_cake.py output.spcw --output reconstructed.png
-python eat_cake.py output.spcw --heatmap  # Show order of operations
-```
-
-The Player reconstructs the image using fractal addressing:
-- Each atom's Heat Code determines its spatial position
-- Canvas state is updated non-linearly (fractal pattern)
-- Heatmap mode visualizes reconstruction order (red=early, blue=late)
-
-## Protocol Details
-
-### Atom Structure (512 bytes)
-
-- **Heat Code**: First 4 bytes (32 bits) - Fractal address
-- **Wave Payload**: Remaining 508 bytes - Data/instructions
-
-### Fractal Addressing
-
-32-bit Heat Code decoded as 16-level quadtree descent:
-- **Bit Structure**: Bits 31-30 (Level 1), Bits 29-28 (Level 2), ..., Bits 1-0 (Level 16)
-- **Quadrant Mapping**: 00=Top-Left, 01=Top-Right, 10=Bottom-Left, 11=Bottom-Right
-- **Termination**: Stops at minimum bucket size (64px) or stop sequence
-
-### Prime Harmonization
-
-- `residue = heat_code % 9973`
-- `residue == 0` → META (Harmonized Wave/Structure)
-- `residue != 0` → DELTA (Phase Hole/Heat/Correction)
-
-## Core Functions (`logos_core.py`)
-
-### `resolve_fractal_address(heat_code_int, canvas_width, canvas_height)`
-
-Decodes 32-bit Heat Code to spatial ZoneRect `(x, y, width, height)` via quadtree descent.
-
-### `prime_harmonizer(heat_code_int)`
-
-Classifies Heat Code as META (harmonized) or DELTA (phase hole).
-
-### `calculate_heat_code(path_bits)`
-
-Encodes quadtree path (list of 2-bit quadrants) into 32-bit Heat Code.
-
-### `pack_atom(heat_code, payload_data)`
-
-Constructs 512-byte Atom: `[Heat Code (4B)] + [Payload (508B)]`.
-
-## Use Cases
-
-### 1. Compression via Geometry
-
-Demonstrates that only "active" parts of a signal need transmission. Uniform regions compress to single atoms.
-
-### 2. Non-Linear Stream Processing
-
-Heatmap mode visually proves non-linear reconstruction. Large blocks appear first, fine details fill in later—not top-to-bottom scanning.
-
-### 3. Infinite Canvas Support
-
-Fractal addressing supports resolutions up to 65,536 × 65,536 without linear memory constraints.
-
-### 4. Deterministic Transport
-
-Same Heat Code always maps to same spatial region, enabling deterministic reconstruction across systems.
-
-## Technical Notes
-
-- **Minimum Bucket Size**: 64px (configurable)
-- **Maximum Depth**: 16 levels (2^16 = 65,536 subdivisions)
-- **Coordinate Clamping**: Final ZoneRect clamped to canvas bounds
-- **Big Endian**: Heat Code stored as Big Endian unsigned int
-
-## Examples
-
-### Example 1: Encode and Decode
-
-```bash
-# Bake a test image (deep dissolution)
-python bake_stream.py test_image.png test.spcw --tolerance 5.0 --max-depth 10
-
-# Reconstruct it
-python eat_cake.py test.spcw --output reconstructed.png
-```
-
-### Example 2: Visualize Reconstruction Order
-
-```bash
-# Show heatmap (proves non-linear processing)
-python eat_cake.py test.spcw --heatmap --output heatmap.png
-```
-
-The heatmap shows red (early atoms) and blue (late atoms), proving that reconstruction is fractal, not sequential.
-
-## Architecture Philosophy
-
-**The Cake/Bake Axiom:**
-- **Bake**: The input stream (Instructions + Ingredients)
-- **Cake**: The output (reconstructed reality)
-- **The Oven**: The reconstruction engine (fractal addressing + state updates)
-
-LOGOS separates "what to transmit" (The Bake) from "how to reconstruct" (The Oven). The receiver doesn't need to know the original structure—it follows the fractal instructions.
-
-## License
-
-Reference Implementation for the LOGOS DSP Bridge protocol.
+# LOGOS: SPCW (Scalar Prime Composite Wave) Protocol
+
+A deterministic, non-linear data transport protocol that replaces sequential scanning with fractal addressing.
+
+## The Problem
+
+Modern transport (PCIe/Network) treats data as a linear stream ("The Cake"), creating bandwidth bottlenecks. Sequential scanning forces data to flow in memory address order, regardless of geometric significance.
+
+## The Solution
+
+LOGOS transmits generative instructions ("The Bake"). Using a 512-byte Atom architecture and Prime Modulo addressing, the receiver reconstructs the state fractally. Data is populated by geometric significance, not memory address order.
+
+## Key Features
+
+- **Fractal Address Space**: 32-bit Heat Codes mapped to Quadtree geometry
+- **Prime Constraint**: 9973 Modulo harmonization for signal integrity
+- **Non-Linear Reconstruction**: Data populated by geometric significance, not memory address order
+- **Compression via Geometry**: Only transmit "active" parts of the signal
+- **Infinite Canvas**: Supports up to 2^16 × 2^16 resolution (65,536 × 65,536 pixels)
+
+## Repository Structure
+
+```
+LOGOS_SPCW_Protocol/
+├── README.md               # This file
+├── logos_core.py           # The Math (Fractal Decoder + Prime Modulo)
+├── bake_stream.py          # The Encoder (Image -> SPCW)
+├── eat_cake.py             # The Player (SPCW -> Screen)
+├── data/                   # Sample files
+│   └── sample.spcw         # Pre-baked binary file
+└── requirements.txt        # numpy, opencv-python
+```
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+## Quick Start
+
+### 1. Bake an Image (Encode)
+
+```bash
+python bake_stream.py input.png output.spcw
+python bake_stream.py input.png output.spcw --tolerance 3.0  # Stricter fidelity
+```
+
+The Deep Baker uses bottom-up dissolution + pruning:
+- Dissolve to max depth (full inspection)
+- Collapse only when four children are identical within tolerance
+
+### 2. Eat the Cake (Decode/Playback)
+
+```bash
+python eat_cake.py output.spcw
+python eat_cake.py output.spcw --output reconstructed.png
+python eat_cake.py output.spcw --heatmap  # Show order of operations
+```
+
+The Player reconstructs the image using fractal addressing:
+- Each atom's Heat Code determines its spatial position
+- Canvas state is updated non-linearly (fractal pattern)
+- Heatmap mode visualizes reconstruction order (red=early, blue=late)
+
+## Protocol Details
+import gradio as gr
+import numpy as np
+import plotly.graph_objects as go
+import sympy
+import networkx as nx
+
+# --- MODULE 1: SPCW LOGIC (The Primitive) ---
+def generate_spcw_waveform(sequence_length, persistence_factor):
+    """
+    Simulates the Scalar Prime Composite Waveform.
+    High persistence (00) = Low Heat. Change (11) = High Heat.
+    """
+    # 1. Generate Primes (The Logic Backbone)
+    primes = list(sympy.primerange(0, sequence_length))
+    
+    # 2. Simulate "Heat" based on Prime Gaps (your logic)
+    x = np.arange(len(primes))
+    # Synthetic "Heat" metric based on gap delta
+    heat = np.diff(primes, prepend=0) * (1 - persistence_factor)
+    
+    # 3. Create Visualization (The "Heat Map")
+    fig = go.Figure()
+    fig.add_trace(go.Scatter(x=x, y=primes, mode='lines+markers', name='Prime Scalar'))
+    fig.add_trace(go.Bar(x=x, y=heat, name='Delta Heat (Change Energy)'))
+    
+    fig.update_layout(title="SPCW Persistence & Change Matrix", template="plotly_dark")
+    return fig
+
+# --- MODULE 2: MATROSKA TOPOLOGY (The Network) ---
+def visualize_matroska_network(shells):
+    """
+    Creates a concentric 'Matroska' network visualization.
+    """
+    G = nx.Graph()
+    pos = {}
+    
+    # Create concentric shells
+    for i in range(1, shells + 1):
+        radius = i * 5
+        nodes_in_layer = i * 6  # Hexagonal growth pattern
+        for j in range(nodes_in_layer):
+            node_id = f"L{i}-{j}"
+            angle = (2 * np.pi * j) / nodes_in_layer
+            pos[node_id] = (radius * np.cos(angle), radius * np.sin(angle))
+            G.add_node(node_id, layer=i)
+            
+            # Connect to previous shell (The "Persistence" Link)
+            if i > 1:
+                prev_node = f"L{i-1}-{int(j/nodes_in_layer * ((i-1)*6))}"
+                G.add_edge(node_id, prev_node)
+
+    # Extract positions for Plotly
+    edge_x = []
+    edge_y = []
+    for edge in G.edges():
+        x0, y0 = pos[edge[0]]
+        x1, y1 = pos[edge[1]]
+        edge_x.extend([x0, x1, None])
+        edge_y.extend([y0, y1, None])
+
+    node_x = [pos[node][0] for node in G.nodes()]
+    node_y = [pos[node][1] for node in G.nodes()]
+
+    fig = go.Figure(data=[
+        go.Scatter(x=edge_x, y=edge_y, line=dict(width=0.5, color='#888'), hoverinfo='none', mode='lines'),
+        go.Scatter(x=node_x, y=node_y, mode='markers', marker=dict(color='cyan', size=5))
+    ])
+    fig.update_layout(title="Modular Concentric Prime Matroska Network", showlegend=False, template="plotly_dark")
+    return fig
+
+# --- THE INTERFACE ---
+with gr.Blocks(theme=gr.themes.Monochrome()) as demo:
+    gr.Markdown("# LOGOS: Modular Concentric Prime Matroska Network")
+    gr.Markdown("Interactive architectural validation for SPCW and Nested Domains.")
+    
+    with gr.Tab("SPCW Waveform"):
+        with gr.Row():
+            seq_len = gr.Slider(10, 1000, value=100, label="Sequence Length")
+            per_factor = gr.Slider(0.0, 1.0, value=0.5, label="Persistence Factor (00 State)")
+        spcw_plot = gr.Plot(label="Persistence/Change Matrix")
+        btn_spcw = gr.Button("Generate Waveform")
+        btn_spcw.click(generate_spcw_waveform, inputs=[seq_len, per_factor], outputs=spcw_plot)
+
+    with gr.Tab("Matroska Topology"):
+        shells_slider = gr.Slider(1, 10, value=3, step=1, label="Nesting Depth (Shells)")
+        matroska_plot = gr.Plot(label="Network Topology")
+        btn_net = gr.Button("Build Network")
+        btn_net.click(visualize_matroska_network, inputs=[shells_slider], outputs=matroska_plot)
+
+demo.launch()
+
+### Atom Structure (512 bytes)
+
+- **Heat Code**: First 4 bytes (32 bits) - Fractal address
+- **Wave Payload**: Remaining 508 bytes - Data/instructions
+
+### Fractal Addressing
+
+32-bit Heat Code decoded as 16-level quadtree descent:
+- **Bit Structure**: Bits 31-30 (Level 1), Bits 29-28 (Level 2), ..., Bits 1-0 (Level 16)
+- **Quadrant Mapping**: 00=Top-Left, 01=Top-Right, 10=Bottom-Left, 11=Bottom-Right
+- **Termination**: Stops at minimum bucket size (64px) or stop sequence
+
+### Prime Harmonization
+
+- `residue = heat_code % 9973`
+- `residue == 0` → META (Harmonized Wave/Structure)
+- `residue != 0` → DELTA (Phase Hole/Heat/Correction)
+
+## Core Functions (`logos_core.py`)
+
+### `resolve_fractal_address(heat_code_int, canvas_width, canvas_height)`
+
+Decodes 32-bit Heat Code to spatial ZoneRect `(x, y, width, height)` via quadtree descent.
+
+### `prime_harmonizer(heat_code_int)`
+
+Classifies Heat Code as META (harmonized) or DELTA (phase hole).
+
+### `calculate_heat_code(path_bits)`
+
+Encodes quadtree path (list of 2-bit quadrants) into 32-bit Heat Code.
+
+### `pack_atom(heat_code, payload_data)`
+
+Constructs 512-byte Atom: `[Heat Code (4B)] + [Payload (508B)]`.
+
+## Use Cases
+
+### 1. Compression via Geometry
+
+Demonstrates that only "active" parts of a signal need transmission. Uniform regions compress to single atoms.
+
+### 2. Non-Linear Stream Processing
+
+Heatmap mode visually proves non-linear reconstruction. Large blocks appear first, fine details fill in later—not top-to-bottom scanning.
+
+### 3. Infinite Canvas Support
+
+Fractal addressing supports resolutions up to 65,536 × 65,536 without linear memory constraints.
+
+### 4. Deterministic Transport
+
+Same Heat Code always maps to same spatial region, enabling deterministic reconstruction across systems.
+
+## Technical Notes
+
+- **Minimum Bucket Size**: 64px (configurable)
+- **Maximum Depth**: 16 levels (2^16 = 65,536 subdivisions)
+- **Coordinate Clamping**: Final ZoneRect clamped to canvas bounds
+- **Big Endian**: Heat Code stored as Big Endian unsigned int
+
+## Examples
+
+### Example 1: Encode and Decode
+
+```bash
+# Bake a test image (deep dissolution)
+python bake_stream.py test_image.png test.spcw --tolerance 5.0 --max-depth 10
+
+# Reconstruct it
+python eat_cake.py test.spcw --output reconstructed.png
+```
+
+### Example 2: Visualize Reconstruction Order
+
+```bash
+# Show heatmap (proves non-linear processing)
+python eat_cake.py test.spcw --heatmap --output heatmap.png
+```
+
+The heatmap shows red (early atoms) and blue (late atoms), proving that reconstruction is fractal, not sequential.
+
+## Architecture Philosophy
+
+**The Cake/Bake Axiom:**
+- **Bake**: The input stream (Instructions + Ingredients)
+- **Cake**: The output (reconstructed reality)
+- **The Oven**: The reconstruction engine (fractal addressing + state updates)
+
+LOGOS separates "what to transmit" (The Bake) from "how to reconstruct" (The Oven). The receiver doesn't need to know the original structure—it follows the fractal instructions.
+
+## License
+
+Reference Implementation for the LOGOS DSP Bridge protocol.