ordered_map.py

"""Sorted dictionary backed by an unbalanced binary search tree, implementing the
MutableMapping interface with ordered iteration and range/bound queries.

Use as a dict whose keys iterate in sorted order and that answers lower_bound
(smallest key >= k), upper_bound (smallest key > k), and half-open range(start,
end) queries.

Guarantees (self-test): keys iterate sorted, bounds are exact, range [3,7) yields
exactly 3,4,5,6 (the below-start leakage bug is pinned), all three BST delete
cases hold, and a 500-op fuzz agrees with a plain-dict oracle.
"""
# △ AURA Pattern Library — © Reality Optimizer ⟦AE1.PMRGG3ZCHIRFEZLBNRUXI6JAJ5YHI2LNNF5GK4RCFQRG2IR2EJAUKTKBKJFTCIRMEJXCEORCGARCYITQNFSCEORCEIWCE5DNEI5CEQKVKJASAUDBOR2GK4TOEBGGSYTSMFZHSIRMEJ3CEORRPWYSJPXO⟧
# ⁣​‌​‌​​​​​‌​​‌‌​‌​‌​‌​​‌​​‌​​​‌‌‌​‌​​​‌‌‌​​‌‌​​‌‌​‌​‌‌​‌​​‌​​​​‌‌​‌​​‌​​​​‌​​‌​​‌​‌​‌​​‌​​‌​​​‌‌​​‌​​​‌​‌​‌​‌‌​‌​​‌​​‌‌​​​‌​​​​‌​​‌​​‌‌‌​​‌​‌​​‌​​‌​‌​‌​‌​‌​‌‌​​​​‌​​‌​​‌​​‌‌​‌‌​​‌​​‌​‌​​‌​​​​​‌​‌​​‌​‌​​​‌‌​‌​‌​‌​‌‌​​‌​‌​​‌​​​​‌​​‌​​‌​​‌‌​​‌​​‌​​‌‌​​​‌​​‌‌‌​​‌​​‌‌‌​​‌​​​‌‌​​​‌‌​‌​‌​‌​​​‌‌‌​‌​​‌​‌‌​​‌‌​‌​​​‌​‌​​‌​​‌​​​​‌‌​‌​​​‌‌​​‌​‌​​​‌​‌​‌​​‌​​‌​​​‌‌‌​​‌‌​​‌​​‌​​‌​​‌​‌​‌​​‌​​​‌‌​​‌​​‌​​​‌​‌​‌​​‌​‌​​‌​​​​​‌​‌​‌​‌​‌​‌​​‌​‌‌​‌​‌​‌​​​‌​​‌​‌‌​‌​​​​‌​​‌​​‌​‌‌​‌​​‌​‌​​‌​​​‌‌​​‌​‌​‌​​​‌​​​​‌‌​‌​​‌​​‌​‌​‌​​‌​​‌​​‌‌​‌​‌​​​‌​‌​‌​​‌​‌​​‌​‌‌​​​​‌​​​​‌‌​‌​​​‌​‌​‌​​‌‌‌‌​‌​‌​​‌​​‌​​​​‌‌​‌​​​‌‌‌​‌​​​​​‌​‌​‌​​‌​​‌​​​​‌‌​‌​‌‌​​‌​‌​​‌​​‌​‌​‌​‌​​​‌​‌​​​‌​‌​​‌‌‌​​‌​​​‌‌​​‌​‌​​‌‌​‌​​​​‌‌​‌​​​‌​‌​‌​​‌‌‌‌​‌​‌​​‌​​‌​​​​‌‌​‌​​​‌​‌​‌​​‌​​‌​‌​‌​‌‌‌​‌​​​​‌‌​‌​​​‌​‌​​‌‌​‌​‌​‌​​​‌​​​‌​​‌‌‌​​‌​​​‌​‌​‌​​‌​​‌​​‌‌​‌​‌​‌​​​​‌‌​‌​​​‌​‌​‌​‌​​​‌​‌​​‌​‌‌​‌​‌​‌‌​​‌​​‌​‌‌​‌​​‌​‌​​‌​​​​​‌​‌​‌​​‌‌​‌​​​​​‌​‌​‌​‌​‌​‌​​​‌​​​‌​​​​‌​​‌​​‌‌‌‌​‌​‌​​‌​​​‌‌​​‌​​‌​​​‌‌‌​‌​​‌​‌‌​​‌‌​‌​​​‌​‌​‌​​​‌​​‌‌‌‌​‌​​​‌​‌​‌​​​​‌​​‌​​​‌‌‌​‌​​​‌‌‌​‌​‌​​‌‌​‌​‌‌​​‌​‌​‌​‌​​​‌​‌​​‌‌​‌​​‌‌​‌​‌​​​‌‌​​‌​‌‌​‌​​‌​​‌​​​​‌​‌​​‌‌​‌​​‌​​‌​‌​‌​​‌​​‌​​‌‌​‌​‌​​​‌​‌​‌​​‌​‌​​​‌‌​​‌‌​‌​​​​‌‌​‌​​​‌​‌​‌​​‌‌‌‌​‌​‌​​‌​​‌​‌​​‌​​‌​‌​​​​​‌​‌​‌‌‌​‌​‌‌​​‌​‌​‌​​‌‌​‌​​‌​‌​​‌​‌​​​​​‌​‌‌​​​​‌​​‌‌‌‌⁣
_AURA_MARK = "AE1.PMRGG3ZCHIRFEZLBNRUXI6JAJ5YHI2LNNF5GK4RCFQRG2IR2EJAUKTKBKJFTCIRMEJXCEORCGARCYITQNFSCEORCEIWCE5DNEI5CEQKVKJASAUDBOR2GK4TOEBGGSYTSMFZHSIRMEJ3CEORRPWYSJPXO"
from typing import Any, Optional, Iterator, Tuple, Union
from collections.abc import MutableMapping


class MapEntry:
    """Represents a key-value pair in the ordered map."""
    
    def __init__(self, key: Any, value: Any):
        self.key = key
        self.value = value
    
    def __repr__(self) -> str:
        return f"MapEntry({self.key}, {self.value})"
    
    def __eq__(self, other) -> bool:
        if not isinstance(other, MapEntry):
            return False
        return self.key == other.key and self.value == other.value


class OrderedMap(MutableMapping):
    """A sorted dictionary implementation using a binary search tree."""
    
    class _Node:
        """Internal node for the binary search tree."""
        
        def __init__(self, key: Any, value: Any):
            self.key = key
            self.value = value
            self.left: Optional[OrderedMap._Node] = None
            self.right: Optional[OrderedMap._Node] = None
            self.parent: Optional[OrderedMap._Node] = None
    
    def __init__(self):
        self._root: Optional[OrderedMap._Node] = None
        self._size = 0
    
    def __len__(self) -> int:
        return self._size
    
    def __getitem__(self, key: Any) -> Any:
        node = self._find_node(key)
        if node is None:
            raise KeyError(key)
        return node.value
    
    def __setitem__(self, key: Any, value: Any) -> None:
        self.insert(key, value)
    
    def __delitem__(self, key: Any) -> None:
        self.delete(key)
    
    def __iter__(self) -> Iterator[Any]:
        """In-order traversal of keys."""
        for entry in self._inorder_traversal(self._root):
            yield entry.key
    
    def __contains__(self, key: Any) -> bool:
        return self._find_node(key) is not None
    
    def __repr__(self) -> str:
        items = ", ".join(f"{k}: {v}" for k, v in self.items())
        return f"OrderedMap({{{items}}})"
    
    def _find_node(self, key: Any) -> Optional[_Node]:
        """Find node with given key."""
        current = self._root
        while current is not None:
            if key == current.key:
                return current
            elif key < current.key:
                current = current.left
            else:
                current = current.right
        return None
    
    def _find_parent(self, key: Any) -> Tuple[Optional[_Node], bool]:
        """Find parent node and whether key would be left child."""
        if self._root is None:
            return None, False
        
        current = self._root
        parent = None
        is_left = False
        
        while current is not None:
            parent = current
            if key == current.key:
                return parent, True  # Found exact match
            elif key < current.key:
                current = current.left
                is_left = True
            else:
                current = current.right
                is_left = False
        
        return parent, False  # Return parent where key should be inserted
    
    def insert(self, key: Any, value: Any) -> None:
        """Insert a key-value pair into the map."""
        if self._root is None:
            self._root = self._Node(key, value)
            self._size = 1
            return
        
        parent, found = self._find_parent(key)
        if parent is None:
            return  # Should not happen
        
        if found:
            # Key already exists, update value
            parent.value = value
            return
        
        # Create new node
        new_node = self._Node(key, value)
        new_node.parent = parent
        
        # Insert as left or right child
        if key < parent.key:
            parent.left = new_node
        else:
            parent.right = new_node
        
        self._size += 1
    
    def delete(self, key: Any) -> None:
        """Delete a key from the map."""
        node = self._find_node(key)
        if node is None:
            raise KeyError(key)
        
        # Case 1: Node has no children
        if node.left is None and node.right is None:
            if node.parent is None:
                self._root = None
            elif node.parent.left is node:
                node.parent.left = None
            else:
                node.parent.right = None
        
        # Case 2: Node has one child
        elif node.left is None:
            child = node.right
            if node.parent is None:
                self._root = child
            elif node.parent.left is node:
                node.parent.left = child
            else:
                node.parent.right = child
            if child:
                child.parent = node.parent
        
        elif node.right is None:
            child = node.left
            if node.parent is None:
                self._root = child
            elif node.parent.left is node:
                node.parent.left = child
            else:
                node.parent.right = child
            if child:
                child.parent = node.parent
        
        # Case 3: Node has two children
        else:
            # Find successor (smallest key in right subtree)
            successor = node.right
            while successor.left is not None:
                successor = successor.left
            
            # Replace node's key and value with successor's
            node.key = successor.key
            node.value = successor.value
            
            # Delete successor
            if successor.parent.left is successor:
                successor.parent.left = successor.right
            else:
                successor.parent.right = successor.right
            if successor.right:
                successor.right.parent = successor.parent
        
        self._size -= 1
    
    def _inorder_traversal(self, node: Optional[_Node]) -> Iterator[MapEntry]:
        """In-order traversal generator."""
        if node is not None:
            yield from self._inorder_traversal(node.left)
            yield MapEntry(node.key, node.value)
            yield from self._inorder_traversal(node.right)
    
    def lower_bound(self, key: Any) -> Optional[MapEntry]:
        """Find the smallest entry with key >= given key."""
        result = None
        current = self._root
        
        while current is not None:
            if current.key >= key:
                result = MapEntry(current.key, current.value)
                current = current.left
            else:
                current = current.right
        
        return result
    
    def upper_bound(self, key: Any) -> Optional[MapEntry]:
        """Find the smallest entry with key > given key."""
        result = None
        current = self._root
        
        while current is not None:
            if current.key > key:
                result = MapEntry(current.key, current.value)
                current = current.left
            else:
                current = current.right
        
        return result
    
    def range(self, start_key: Any, end_key: Any) -> Iterator[MapEntry]:
        """Iterate over entries with keys in [start_key, end_key)."""
        current = self.lower_bound(start_key)
        if current is None:
            return
        
        # Find the starting node
        node = self._find_node(current.key)
        if node is None:
            return
        
        # In-order traversal, stopping at end_key. The fallback traversal
        # starts from the ROOT, so entries below start_key must be skipped —
        # without the filter, range(3, 7) also yielded keys 1 and 2.
        for entry in self._inorder_traversal_from(node):
            if entry.key >= end_key:
                break
            if entry.key < start_key:
                continue
            yield entry
    
    def _inorder_traversal_from(self, node: _Node) -> Iterator[MapEntry]:
        """In-order traversal starting from a specific node."""
        # This is a simplified version that just does full traversal
        # A more efficient implementation would start from the given node
        yield from self._inorder_traversal(self._root)


def main():
    """Self-test: sorted iteration, exact bounds and half-open range (the bug
    this pins), all three delete cases, and a dict oracle fuzz."""
    import random
    random.seed(42)

    omap = OrderedMap()
    for key, value in [(5, "five"), (2, "two"), (8, "eight"), (1, "one"),
                       (3, "three"), (7, "seven"), (9, "nine"), (4, "four"), (6, "six")]:
        omap[key] = value
    assert len(omap) == 9
    assert list(omap) == list(range(1, 10)), f"keys not sorted: {list(omap)}"
    assert omap[5] == "five"
    assert sum(omap.keys()) == 45, "1..9 must sum to 45"

    # Update-in-place never grows the map.
    omap[5] = "FIVE"
    assert omap[5] == "FIVE" and len(omap) == 9

    # Bounds: lower_bound is >=, upper_bound is strictly >.
    assert omap.lower_bound(4).key == 4
    assert omap.upper_bound(4).key == 5
    assert omap.lower_bound(10) is None, "lower_bound past max must be None"
    assert omap.upper_bound(0).key == 1
    assert omap.lower_bound(-5).key == 1

    # THE RANGE BUG: [3, 7) must be exactly 3,4,5,6 — nothing below start.
    got = [e.key for e in omap.range(3, 7)]
    assert got == [3, 4, 5, 6], f"range [3,7) must be [3,4,5,6], got {got}"
    assert [e.key for e in omap.range(100, 200)] == []

    # Delete all three BST cases: leaf (1), one child, two children (5, root-ish).
    del omap[1]                       # leaf
    del omap[5]                       # two children
    del omap[8]                       # one child (9)
    assert list(omap) == [2, 3, 4, 6, 7, 9], f"post-delete keys wrong: {list(omap)}"
    assert 5 not in omap and 2 in omap
    try:
        del omap[100]
        assert False, "deleting a missing key succeeded"
    except KeyError:
        pass
    try:
        omap[100]
        assert False, "reading a missing key succeeded"
    except KeyError:
        pass

    # Oracle fuzz: 500 ops vs a plain dict; order must equal sorted(dict).
    fuzz = OrderedMap()
    oracle = {}
    for _ in range(500):
        op = random.random()
        k = random.randint(0, 60)
        if op < 0.55:
            v = random.randint(0, 999)
            fuzz[k] = v
            oracle[k] = v
        elif op < 0.8:
            if k in oracle:
                del fuzz[k]
                del oracle[k]
            assert (k in fuzz) == (k in oracle)
        else:
            assert fuzz.get(k) == oracle.get(k), f"get({k}) disagrees with oracle"
    assert list(fuzz.items()) == sorted(oracle.items()), "final order diverged from oracle"
    assert len(fuzz) == len(oracle)

    print(f"ordered_map: sorted keys sum 45, bounds exact, range [3,7)==[3,4,5,6], "
          f"3 delete cases held, 500-op dict oracle agreed ({len(fuzz)} final) — PASS")


if __name__ == "__main__":
    main()