docs/FRACTAL_ADDRESSING.md

# Fractal Coordinate Decoder - Implementation Guide

## Overview

The Fractal Coordinate Decoder maps 32-bit Heat Codes to spatial coordinates using quadtree descent. This enables **non-linear, fractal distribution** of atom updates across the canvas, creating the "Infinite Canvas" capability.

## Algorithm: `resolve_fractal_address()`

### Input
- `heat_code_int`: 32-bit integer (from 4-byte Heat Code)
- `canvas_size`: (width, height) tuple

### Process

1. **Initialize**: Start with full canvas rectangle `(0, 0, canvas_width, canvas_height)`

2. **Descent Loop**: For each of 16 levels (MSB to LSB):
   - Extract 2-bit pair from heat code
   - Map to quadrant:
     - `00` → Top-Left (no translation)
     - `01` → Top-Right (x += w/2)
     - `10` → Bottom-Left (y += h/2)
     - `11` → Bottom-Right (x += w/2, y += h/2)
   - Subdivide: `w /= 2`, `h /= 2`

3. **Termination**: Stop when:
   - Region size ≤ minimum bucket size (64px), OR
   - Stop sequence detected (consecutive `0000` after level 8)

4. **Output**: ZoneRect `(x, y, width, height)` defining exact spatial region

### Bit Structure

```
32-bit Heat Code: [31:30] [29:28] [27:26] ... [3:2] [1:0]
                   Level 1  Level 2  Level 3 ... Level 15 Level 16
```

Each 2-bit pair selects a quadrant at that quadtree level.

### Example

**Heat Code: `0x80000000`** (MSB set)

- Level 1 (bits 31-30): `10` → Bottom-Left → `y += h/2`
- Level 2 (bits 29-28): `00` → Top-Left → no translation
- ... continues descending until bucket size reached

Result: Zone in bottom-left quadrant of canvas.

## Integration

### In LogosDisplayInterpreter

```python
# Decode bucket position
bucket_x, bucket_y = display_interpreter.decode_bucket_position(heat_code_hex)

# Get exact zone rectangle
zone_rect = display_interpreter.get_fractal_zone_rect(heat_code_hex)
```

### In LogosFractalEngine

```python
# Direct fractal addressing
zone_rect = fractal_engine.resolve_fractal_address(heat_code_int, canvas_size)

# Bucket coordinate mapping
bucket_x, bucket_y = fractal_engine.fractal_to_bucket_coords(
    heat_code_int, num_buckets_x, num_buckets_y
)
```

## Benefits

1. **Non-Linear Distribution**: Updates occur in fractal pattern, not sequential
2. **Infinite Canvas**: Supports up to 2^16 × 2^16 resolution (65,536 × 65,536)
3. **Scalable Addressing**: Same heat code maps to different regions at different scales
4. **Deterministic**: Same heat code always maps to same region

## Test Results

See `coordinate_decoder_test.py` for validation:

- `00000000` → Top-Left region
- `FFFFFFFF` → Bottom-Right region  
- `80000000` → Bottom-Left path (top-right quadrant of left half)
- Each heat code maps to distinct spatial region

## Technical Notes

- **Minimum Bucket Size**: 64px (configurable)
- **Maximum Depth**: 16 levels (2^16 = 65,536 subdivisions)
- **Stop Sequence**: Early termination on `0000` after level 8
- **Coordinate Clamping**: Final ZoneRect clamped to canvas bounds