"""
The memory bridge: real host RAM as the storage array, DDR bus LOGIC emulated by
verified neural units.

This is the honest core of the "run it on your old PC" idea. The bytes live in a
buffer in the machine's actual DDR3/DDR4. Every access is routed through the
neural DDR units for a CHOSEN generation, so the bridge presents that
generation's *behavior* over ordinary host memory:

  * DDR3  -> no DBI: bytes drive the bus as-is.
  * DDR4/5 -> DBI:   the verified neural DBI unit encodes each byte onto the
                     "bus" (>4 zeros -> invert + flag), so <=4 DQ lines are ever
                     LOW; reads decode it back, bit-exact.

No capacity or speed is created: this models the data-path logic, it does not
turn DDR3 into DDR5 silicon.
"""

from __future__ import annotations

from .dbi import NeuralDBIEncode, NeuralDBIDecode


class MemoryBridge:
    def __init__(self, size: int, enc: NeuralDBIEncode, dec: NeuralDBIDecode,
                 generation: str = "DDR5"):
        self.size = size
        self.enc = enc
        self.dec = dec
        self.generation = generation
        self.dbi = generation in ("DDR4", "DDR5")   # DBI introduced in DDR4
        # storage in real host RAM: the (possibly DBI-encoded) data byte + flag.
        self._data = bytearray(size)
        self._flag = bytearray(size)
        # bus statistics
        self.dq_low_total = 0
        self.transfers = 0

    def write(self, addr: int, value: int) -> None:
        value &= 0xFF
        if self.dbi:
            enc, flag = self.enc.encode(value)       # verified neural unit
        else:
            enc, flag = value, 0
        self._data[addr] = enc
        self._flag[addr] = flag
        self.dq_low_total += 8 - bin(enc).count("1")  # DQ lines driven LOW
        self.transfers += 1

    def read(self, addr: int) -> int:
        enc, flag = self._data[addr], self._flag[addr]
        if self.dbi:
            return self.dec.decode(enc, flag)        # verified neural unit
        return enc

    def avg_dq_low(self) -> float:
        return self.dq_low_total / max(1, self.transfers)