logos/logos_core.py

"""
logos_core.py - The Mathematical Heart of LOGOS
Core SPCW Protocol functions: Fractal Addressing and Prime Harmonization
"""

# ==========================================
# LOGOS CONSTANTS
# ==========================================
PRIME_MODULO = 9973
ATOM_SIZE = 512
HEAT_CODE_SIZE = 4
META_SIZE = 3          # domain_id (1) + gap_id (2)
PAYLOAD_SIZE = 508     # Total payload = 512 - 4 (heat code) = 508

# 2-bit state codes for matrix/bucket logic
STATE_NULL = 0b00       # no activity / void
STATE_ASC = 0b01        # ascending / filling
STATE_DESC = 0b10       # descending / draining
STATE_PEAK = 0b11       # critical / peak

# Static table of the first 1000 primes (uint16 fits in L1; ~2KB)
# 1000th prime = 7919
STATIC_PRIMES: list[int] = [
    2, 3, 5, 7, 11, 13, 17, 19, 23, 29,
    31, 37, 41, 43, 47, 53, 59, 61, 67, 71,
    73, 79, 83, 89, 97, 101, 103, 107, 109, 113,
    127, 131, 137, 139, 149, 151, 157, 163, 167, 173,
    179, 181, 191, 193, 197, 199, 211, 223, 227, 229,
    233, 239, 241, 251, 257, 263, 269, 271, 277, 281,
    283, 293, 307, 311, 313, 317, 331, 337, 347, 349,
    353, 359, 367, 373, 379, 383, 389, 397, 401, 409,
    419, 421, 431, 433, 439, 443, 449, 457, 461, 463,
    467, 479, 487, 491, 499, 503, 509, 521, 523, 541,
    547, 557, 563, 569, 571, 577, 587, 593, 599, 601,
    607, 613, 617, 619, 631, 641, 643, 647, 653, 659,
    661, 673, 677, 683, 691, 701, 709, 719, 727, 733,
    739, 743, 751, 757, 761, 769, 773, 787, 797, 809,
    811, 821, 823, 827, 829, 839, 853, 857, 859, 863,
    877, 881, 883, 887, 907, 911, 919, 929, 937, 941,
    947, 953, 967, 971, 977, 983, 991, 997, 1009, 1013,
    1019, 1021, 1031, 1033, 1039, 1049, 1051, 1061, 1063, 1069,
    1087, 1091, 1093, 1097, 1103, 1109, 1117, 1123, 1129, 1151,
    1153, 1163, 1171, 1181, 1187, 1193, 1201, 1213, 1217, 1223,
    1229, 1231, 1237, 1249, 1259, 1277, 1279, 1283, 1289, 1291,
    1297, 1301, 1303, 1307, 1319, 1321, 1327, 1361, 1367, 1373,
    1381, 1399, 1409, 1423, 1427, 1429, 1433, 1439, 1447, 1451,
    1453, 1459, 1471, 1481, 1483, 1487, 1489, 1493, 1499, 1511,
    1523, 1531, 1543, 1549, 1553, 1559, 1567, 1571, 1579, 1583,
    1597, 1601, 1607, 1609, 1613, 1619, 1621, 1627, 1637, 1657,
    1663, 1667, 1669, 1693, 1697, 1699, 1709, 1721, 1723, 1733,
    1741, 1747, 1753, 1759, 1777, 1783, 1787, 1789, 1801, 1811,
    1823, 1831, 1847, 1861, 1867, 1871, 1873, 1877, 1879, 1889,
    1901, 1907, 1913, 1931, 1933, 1949, 1951, 1973, 1979, 1987,
    1993, 1997, 1999, 2003, 2011, 2017, 2027, 2029, 2039, 2053,
    2063, 2069, 2081, 2083, 2087, 2089, 2099, 2111, 2113, 2129,
    2131, 2137, 2141, 2143, 2153, 2161, 2179, 2203, 2207, 2213,
    2221, 2237, 2239, 2243, 2251, 2267, 2269, 2273, 2281, 2287,
    2293, 2297, 2309, 2311, 2333, 2339, 2341, 2347, 2351, 2357,
    2371, 2377, 2381, 2383, 2389, 2393, 2399, 2411, 2417, 2423,
    2437, 2441, 2447, 2459, 2467, 2473, 2477, 2503, 2521, 2531,
    2539, 2543, 2549, 2551, 2557, 2579, 2591, 2593, 2609, 2617,
    2621, 2633, 2647, 2657, 2659, 2663, 2671, 2677, 2683, 2687,
    2689, 2693, 2699, 2707, 2711, 2713, 2719, 2729, 2731, 2741,
    2749, 2753, 2767, 2777, 2789, 2791, 2797, 2801, 2803, 2819,
    2833, 2837, 2843, 2851, 2857, 2861, 2879, 2887, 2897, 2903,
    2909, 2917, 2927, 2939, 2953, 2957, 2963, 2969, 2971, 2999,
    3001, 3011, 3019, 3023, 3037, 3041, 3049, 3061, 3067, 3079,
    3083, 3089, 3109, 3119, 3121, 3137, 3163, 3167, 3169, 3181,
    3187, 3191, 3203, 3209, 3217, 3221, 3229, 3251, 3253, 3257,
    3259, 3271, 3299, 3301, 3307, 3313, 3319, 3323, 3329, 3331,
    3343, 3347, 3359, 3361, 3371, 3373, 3389, 3391, 3407, 3413,
    3433, 3449, 3457, 3461, 3463, 3467, 3469, 3491, 3499, 3511,
    3517, 3527, 3529, 3533, 3539, 3541, 3547, 3557, 3559, 3571,
    3581, 3583, 3593, 3607, 3613, 3617, 3623, 3631, 3637, 3643,
    3659, 3671, 3673, 3677, 3691, 3697, 3701, 3709, 3719, 3727,
    3733, 3739, 3761, 3767, 3769, 3779, 3793, 3797, 3803, 3821,
    3823, 3833, 3847, 3851, 3853, 3863, 3877, 3881, 3889, 3907,
    3911, 3917, 3919, 3923, 3929, 3931, 3943, 3947, 3967, 3989,
    4001, 4003, 4007, 4013, 4019, 4021, 4027, 4049, 4051, 4057,
    4073, 4079, 4091, 4093, 4099, 4111, 4127, 4129, 4133, 4139,
    4153, 4157, 4159, 4177, 4201, 4211, 4217, 4219, 4229, 4231,
    4241, 4243, 4253, 4259, 4261, 4271, 4273, 4283, 4289, 4297,
    4327, 4337, 4339, 4349, 4357, 4363, 4373, 4391, 4397, 4409,
    4421, 4423, 4441, 4447, 4451, 4457, 4463, 4481, 4483, 4493,
    4507, 4513, 4517, 4519, 4523, 4547, 4549, 4561, 4567, 4583,
    4591, 4597, 4603, 4621, 4637, 4639, 4643, 4649, 4651, 4657,
    4663, 4673, 4679, 4691, 4703, 4721, 4723, 4729, 4733, 4751,
    4759, 4783, 4787, 4789, 4793, 4799, 4801, 4813, 4817, 4831,
    4861, 4871, 4877, 4889, 4903, 4909, 4919, 4931, 4933, 4937,
    4943, 4951, 4957, 4967, 4969, 4973, 4987, 4993, 4999, 5003,
    5009, 5011, 5021, 5023, 5039, 5051, 5059, 5077, 5081, 5087,
    5099, 5101, 5107, 5113, 5119, 5147, 5153, 5167, 5171, 5179,
    5189, 5197, 5209, 5227, 5231, 5233, 5237, 5261, 5273, 5279,
    5281, 5297, 5303, 5309, 5323, 5333, 5347, 5351, 5381, 5387,
    5393, 5399, 5407, 5413, 5417, 5419, 5431, 5437, 5441, 5443,
    5449, 5471, 5477, 5479, 5483, 5501, 5503, 5507, 5519, 5521,
    5527, 5531, 5557, 5563, 5569, 5573, 5581, 5591, 5623, 5639,
    5641, 5647, 5651, 5653, 5657, 5659, 5669, 5683, 5689, 5693,
    5701, 5711, 5717, 5737, 5741, 5743, 5749, 5776, 5783, 5791, 5801, 5807,
    5813, 5821, 5827, 5839, 5843, 5849, 5851, 5857, 5861, 5867,
    5869, 5879, 5881, 5897, 5903, 5923, 5927, 5939, 5953, 5981,
    5987, 6007, 6011, 6029, 6037, 6043, 6047, 6053, 6067, 6073,
    6079, 6089, 6091, 6101, 6113, 6121, 6133, 6143, 6151, 6163,
    6173, 6197, 6199, 6203, 6211, 6217, 6221, 6229, 6247, 6257,
    6263, 6269, 6271, 6277, 6287, 6299, 6301, 6311, 6317, 6323,
    6329, 6337, 6343, 6353, 6359, 6361, 6367, 6373, 6379, 6389,
    6397, 6421, 6427, 6431, 6433, 6437, 6449, 6451, 6469, 6473,
    6481, 6491, 6521, 6529, 6547, 6551, 6553, 6563, 6569, 6571,
    6577, 6581, 6599, 6607, 6619, 6637, 6653, 6659, 6661, 6673,
    6679, 6689, 6691, 6701, 6703, 6709, 6719, 6733, 6737, 6761,
    6763, 6779, 6781, 6791, 6793, 6803, 6823, 6827, 6829, 6833,
    6841, 6857, 6863, 6869, 6871, 6883, 6899, 6907, 6911, 6917,
    6947, 6959, 6961, 6967, 6971, 6977, 6983, 6991, 6997, 7001,
    7013, 7019, 7027, 7039, 7043, 7057, 7069, 7079, 7103, 7109,
    7121, 7127, 7129, 7151, 7159, 7177, 7187, 7193, 7207, 7211,
    7213, 7219, 7229, 7237, 7243, 7247, 7253, 7283, 7297, 7307,
    7309, 7321, 7331, 7333, 7349, 7351, 7369, 7393, 7411, 7417,
    7433, 7451, 7457, 7459, 7477, 7481, 7487, 7489, 7499, 7507,
    7517, 7523, 7529, 7537, 7541, 7547, 7549, 7559, 7561, 7573,
    7577, 7583, 7589, 7591, 7603, 7607, 7621, 7639, 7643, 7649,
    7669, 7673, 7681, 7687, 7691, 7699, 7703, 7717, 7723, 7727,
    7741, 7753, 7757, 7759, 7789, 7793, 7817, 7823, 7829, 7841,
    7853, 7867, 7873, 7877, 7879, 7883, 7901, 7907, 7919,
]


# Domain registry for canonical separation (medium defaults)
PRIME_DOMAINS = {
    "medium": {
        "id": 1,
        "primes": [9949, 9967, 9973, 10007],
        "gap_signatures": ["16822816", "777", "242", "115"],
    },
    "small": {
        "id": 2,
        "primes": [19, 23, 29],
        "gap_signatures": ["22", "24", "26"],
    },
    "large": {
        "id": 3,
        "primes": [15485863],
        "gap_signatures": ["101", "131"],
    },
    # Video streaming domains
    "video_meta": {
        "id": 10,  # META = keyframe (full frame)
        "primes": [7919],  # 1000th prime - stable reference
        "gap_signatures": ["meta"],
    },
    "video_delta": {
        "id": 11,  # DELTA = temporal difference
        "primes": [7907, 7901],  # Adjacent primes - temporal flow
        "gap_signatures": ["delta"],
    },
}


def get_domain_registry():
    """Expose domain registry."""
    return PRIME_DOMAINS


def validate_prime_candidate(n: int) -> bool:
    """
    Minimal PPM-like check for plausibility of a prime candidate.
    For primes > 5, last digit cannot be even or 5.
    """
    if n <= 5:
        return True
    if n % 2 == 0 or n % 5 == 0:
        return False
    return True


def encode_metadata(domain_key: str = "medium", gap_id: int = 0) -> bytes:
    """
    Pack domain id (1 byte) and gap signature id (2 bytes).
    Total: 3 bytes metadata.
    
    Gap ID expanded to 16 bits to support large tiles (up to 65535 atoms per tile).
    """
    domain_info = PRIME_DOMAINS.get(domain_key, {"id": 0})
    raw_id = domain_info.get("id", 0)
    domain_id = raw_id if isinstance(raw_id, int) else 0
    domain_id = domain_id & 0xFF
    gap_id = gap_id & 0xFFFF  # 16-bit gap_id
    return bytes([domain_id, (gap_id >> 8) & 0xFF, gap_id & 0xFF])


def decode_metadata(meta_bytes: bytes):
    """Unpack domain key and gap id from three-byte metadata."""
    if len(meta_bytes) < 3:
        # Fallback for old 2-byte format
        if len(meta_bytes) >= 2:
            domain_id, gap_id = meta_bytes[0], meta_bytes[1]
        else:
            return ("unknown", 0)
    else:
        domain_id = meta_bytes[0]
        gap_id = (meta_bytes[1] << 8) | meta_bytes[2]
    
    domain_key = "unknown"
    for k, v in PRIME_DOMAINS.items():
        if v.get("id") == domain_id:
            domain_key = k
            break
    return (domain_key, gap_id)


# ---------------- Prime helpers ----------------
def get_static_primes() -> list[int]:
    """Return static prime table (first 1000 primes)."""
    return STATIC_PRIMES


def prime_basin_histogram(values: list[int]) -> dict[int, int]:
    """
    Build a histogram of greatest prime factor (GPF) hits against static primes.
    Values not divisible by any static prime are counted in key -1.
    """
    if not values:
        return {}
    hist: dict[int, int] = {}
    primes = STATIC_PRIMES
    for val in values:
        gpf = -1
        for p in primes:
            if p * p > val:
                break
            if val % p == 0:
                while val % p == 0:
                    val //= p
                gpf = p
        if val > 1 and val in primes:
            gpf = val
        hist[gpf] = hist.get(gpf, 0) + 1
    return hist


def pack_states_2bit(states: list[int]) -> bytes:
    """
    Pack list of 2-bit states into bytes (4 states per byte).
    """
    if not states:
        return b""
    out = bytearray()
    for i in range(0, len(states), 4):
        chunk = states[i:i + 4]
        while len(chunk) < 4:
            chunk.append(STATE_NULL)
        b = ((chunk[0] & 0b11) << 6) | ((chunk[1] & 0b11) << 4) | ((chunk[2] & 0b11) << 2) | (chunk[3] & 0b11)
        out.append(b)
    return bytes(out)


def resolve_fractal_address(heat_code_int, canvas_width, canvas_height, min_size=64):
    """
    Decodes a 32-bit Heat Code into a spatial ZoneRect (x, y, w, h).
    This is the non-linear addressing logic using quadtree descent.
    
    Args:
        heat_code_int: 32-bit integer (from 4-byte Heat Code)
        canvas_width: Canvas width in pixels
        canvas_height: Canvas height in pixels
        min_size: Minimum bucket size in pixels (termination condition)
        
    Returns:
        ZoneRect: (x, y, width, height) tuple defining spatial region
    """
    x, y = 0.0, 0.0
    w, h = float(canvas_width), float(canvas_height)
    
    # Process 32 bits, 2 bits at a time (16 levels max)
    for level in range(16):
        # Extract 2 bits (MSB -> LSB) shift logic
        shift = 30 - (level * 2)
        quadrant = (heat_code_int >> shift) & 0b11
        
        # Halve dimensions
        w /= 2.0
        h /= 2.0
        
        # Quadrant Mapping: 00=TL, 01=TR, 10=BL, 11=BR
        if quadrant == 0b01:  # Top-Right
            x += w
        elif quadrant == 0b10:  # Bottom-Left
            y += h
        elif quadrant == 0b11:  # Bottom-Right
            x += w
            y += h
        # 0b00 (Top-Left): No translation needed
        
        # Stop condition: if region too small
        if w < min_size or h < min_size:
            break
    
    # Ensure minimum size
    w = max(w, min_size)
    h = max(h, min_size)
    
    # Clamp to canvas bounds
    x = max(0, min(x, canvas_width - 1))
    y = max(0, min(y, canvas_height - 1))
    w = min(w, canvas_width - x)
    h = min(h, canvas_height - y)
    
    return (int(x), int(y), int(w), int(h))


def prime_harmonizer(heat_code_int):
    """
    The SPCW Classification Logic.
    Determines if a Heat Code is META (Harmonized) or DELTA (Phase Hole).
    
    Args:
        heat_code_int: 32-bit integer (from 4-byte Heat Code)
        
    Returns:
        (is_meta, residue): Tuple of (bool, int)
            - is_meta: True if harmonized (META), False if noise (DELTA)
            - residue: Modulo residue value
    """
    residue = heat_code_int % PRIME_MODULO
    is_meta = (residue == 0)
    return is_meta, residue


def calculate_heat_code(path_bits):
    """
    Compresses a quadtree navigation path into a 32-bit integer (Heat Code).
    
    Args:
        path_bits: List of 2-bit integers (0-3) representing quadrant choices
        
    Returns:
        heat_code_int: 32-bit integer encoding the path
    """
    code = 0
    # Pack from MSB (Level 1) down to LSB
    # 32 bits allow for 16 levels of depth (2 bits per level)
    for i, quadrant in enumerate(path_bits[:16]):  # Cap at 16 levels
        shift = 30 - (i * 2)
        if shift >= 0:
            code |= (quadrant & 0b11) << shift
    return code


def pack_atom(heat_code, payload_data, domain_key="medium", gap_id=0):
    """
    Constructs a 512-byte Atom: [Heat Code (4B)] + [Metadata (2B)] + [Payload (506B)]
    
    Args:
        heat_code: 32-bit integer Heat Code
        payload_data: bytes or bytearray of payload (will be padded/truncated to 508 bytes)
        domain_key: domain identifier string (default "medium")
        gap_id: gap signature id (0-255)
        
    Returns:
        atom: bytes object of exactly 512 bytes
    """
    import struct
    
    meta = encode_metadata(domain_key, gap_id)

    # Header: Heat Code (Big Endian unsigned int)
    header = struct.pack('>I', heat_code)
    
    # Payload: Ensure exactly (PAYLOAD_SIZE - len(meta)) bytes of user data
    if isinstance(payload_data, bytes):
        payload_bytes = payload_data
    else:
        payload_bytes = bytes(payload_data)
    
    usable = PAYLOAD_SIZE - len(meta)
    if len(payload_bytes) < usable:
        payload_bytes = payload_bytes + b'\x00' * (usable - len(payload_bytes))
    else:
        payload_bytes = payload_bytes[:usable]
    
    return header + meta + payload_bytes


def unpack_atom(atom_bytes):
    """
    Unpacks a 512-byte Atom into Heat Code, Payload, Domain Metadata.
    
    Args:
        atom_bytes: bytes object of exactly 512 bytes
        
    Returns:
        (heat_code, payload, domain_key, gap_id): Tuple
    """
    import struct
    
    if len(atom_bytes) != ATOM_SIZE:
        raise ValueError(f"Atom must be exactly {ATOM_SIZE} bytes, got {len(atom_bytes)}")
    
    # Extract Heat Code (first 4 bytes, Big Endian)
    heat_code = struct.unpack('>I', atom_bytes[:HEAT_CODE_SIZE])[0]
    
    # Metadata (next META_SIZE bytes: domain_id + gap_id)
    meta = atom_bytes[HEAT_CODE_SIZE:HEAT_CODE_SIZE + META_SIZE]
    domain_key, gap_id = decode_metadata(meta)
    
    # Payload (remaining bytes)
    payload = atom_bytes[HEAT_CODE_SIZE + META_SIZE:]
    
    return heat_code, payload, domain_key, gap_id


def get_gpf(n: int) -> int:
    """
    Returns Greatest Prime Factor (GPF) of integer n.
    Used for Prime Topology Routing and Domain classification.
    """
    if n <= 1: return 1
    gpf = 1
    d = 2
    temp = n
    while d * d <= temp:
        if temp % d == 0:
            gpf = d
            while temp % d == 0:
                temp //= d
        d += 1
    if temp > 1:
        gpf = max(gpf, temp)
    return gpf