hashrope 0.1.0__py3-none-any.whl

hashrope/__init__.py

@@ -0,0 +1,64 @@
+"""
+hashrope -- Hash rope data structure with algebraic content addressing.
+
+A balanced binary tree (BB[2/7]) augmented with polynomial hash metadata
+at every node. Supports O(log w) concat, split, and substring hashing,
+plus O(log q) repetition encoding via RepeatNode and geometric accumulator.
+
+All arithmetic is performed modulo a Mersenne prime using bit-shift
+reduction (no expensive division).
+"""
+
+__version__ = "0.1.0"
+
+from hashrope.polynomial_hash import (
+    PolynomialHash,
+    phi,
+    mersenne_mod,
+    mersenne_mul,
+    MERSENNE_61,
+    MERSENNE_127,
+)
+from hashrope.rope import (
+    Leaf,
+    Internal,
+    RepeatNode,
+    Node,
+    rope_concat,
+    rope_split,
+    rope_repeat,
+    rope_substr_hash,
+    rope_len,
+    rope_hash,
+    rope_from_bytes,
+    rope_to_bytes,
+    validate_rope,
+)
+from hashrope.sliding import SlidingWindow
+
+__all__ = [
+    # Polynomial hash
+    "PolynomialHash",
+    "phi",
+    "mersenne_mod",
+    "mersenne_mul",
+    "MERSENNE_61",
+    "MERSENNE_127",
+    # Rope nodes
+    "Leaf",
+    "Internal",
+    "RepeatNode",
+    "Node",
+    # Rope operations
+    "rope_concat",
+    "rope_split",
+    "rope_repeat",
+    "rope_substr_hash",
+    "rope_len",
+    "rope_hash",
+    "rope_from_bytes",
+    "rope_to_bytes",
+    "validate_rope",
+    # Sliding window
+    "SlidingWindow",
+]

hashrope/polynomial_hash.py

@@ -0,0 +1,241 @@
+"""
+Polynomial hash over Z/pZ with Mersenne prime arithmetic.
+
+Implements Definitions 1-3, Lemmas 1-2, 13-14, Theorems 1-3, 5
+from the compressed-domain hashing framework.
+
+All arithmetic is performed modulo a Mersenne prime p = 2^61 - 1
+using bit-shift reduction (Lemma 14) to avoid expensive division.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+MERSENNE_61: int = (1 << 61) - 1  # 2^61 - 1
+MERSENNE_127: int = (1 << 127) - 1  # 2^127 - 1 (recommended for high security, Corollary 5)
+
+
+# ---------------------------------------------------------------------------
+# Mersenne prime arithmetic (Lemma 14)
+# ---------------------------------------------------------------------------
+
+def mersenne_mod(a: int, p: int = MERSENNE_61) -> int:
+    """
+    Reduce a non-negative integer a modulo a Mersenne prime p = 2^k - 1.
+
+    Uses the identity: a mod (2^k - 1) = (a >> k) + (a & ((1 << k) - 1))
+    with at most one conditional subtraction.
+
+    Proof (Lemma 14): Write a = q·2^k + r. Then a = q·(p+1) + r = q·p + (q+r),
+    so a ≡ q + r (mod p). Since q + r < 2^(k+1), at most one subtraction suffices.
+    """
+    # Determine k from p: p = 2^k - 1, so k = p.bit_length()
+    k = p.bit_length()
+    # Repeated folding for very large values
+    while a >= (1 << (2 * k)):
+        a = (a >> k) + (a & p)
+    # Final fold
+    a = (a >> k) + (a & p)
+    # At most one more fold needed
+    a = (a >> k) + (a & p)
+    # Conditional subtraction
+    if a >= p:
+        a -= p
+    return a
+
+
+def mersenne_mul(a: int, b: int, p: int = MERSENNE_61) -> int:
+    """
+    Compute (a * b) mod p for Mersenne prime p.
+
+    Python's arbitrary-precision integers make this straightforward:
+    multiply natively, then reduce via mersenne_mod.
+    """
+    return mersenne_mod(a * b, p)
+
+
+# ---------------------------------------------------------------------------
+# Geometric accumulator Φ (Definition 3, Theorem 3)
+# ---------------------------------------------------------------------------
+
+def phi(q: int, alpha: int, p: int = MERSENNE_61) -> int:
+    """
+    Compute Φ(q, α) = Σ_{i=0}^{q-1} α^i (mod p) via inverse-free
+    repeated doubling.
+
+    Recurrence (Theorem 3):
+        Φ(0, α) = 0
+        Φ(1, α) = 1
+        Φ(2k, α)   = Φ(k, α) · (1 + α^k)
+        Φ(2k+1, α) = Φ(2k, α) · α + 1
+
+    Handles the degenerate case α ≡ 1 (mod p) correctly,
+    yielding Φ(q, 1) = q (mod p) (Lemma 3).
+
+    Time: O(log q) multiplications in Z/pZ.
+
+    Implementation note: We scan q's bits left-to-right (MSB to LSB).
+    We maintain alpha_power = α^n where n is the current accumulated
+    value of q built so far. At each step:
+      - Doubling (n → 2n): alpha_power squares (α^n → α^(2n))
+      - Odd step (n → n+1): alpha_power multiplies by α (α^n → α^(n+1))
+    This ensures the correct α^k is used in each doubling step.
+    """
+    if q == 0:
+        return 0
+    if q == 1:
+        return 1
+
+    bits = q.bit_length()
+
+    phi_val = 1           # Φ(1, α) = 1
+    alpha_power = alpha   # α^1 — tracks α^(current n)
+
+    # Scan from the second-most-significant bit down to bit 0
+    for i in range(bits - 2, -1, -1):
+        # Even step: Φ(2k, α) = Φ(k, α) · (1 + α^k)
+        # alpha_power currently holds α^k
+        phi_val = mersenne_mul(phi_val, (1 + alpha_power) % p, p)
+        # α^k → α^(2k)
+        alpha_power = mersenne_mul(alpha_power, alpha_power, p)
+
+        # If current bit is 1: odd step (2k → 2k+1)
+        if (q >> i) & 1:
+            # Φ(2k+1, α) = Φ(2k, α) · α + 1
+            phi_val = (mersenne_mul(phi_val, alpha, p) + 1) % p
+            # α^(2k) → α^(2k+1)
+            alpha_power = mersenne_mul(alpha_power, alpha, p)
+
+    return phi_val
+
+
+# ---------------------------------------------------------------------------
+# Polynomial Hash (Definition 2, Theorems 1-2, 5)
+# ---------------------------------------------------------------------------
+
+class PolynomialHash:
+    """
+    Polynomial hash function over Z/pZ.
+
+    H(s) = Σ_{i=0}^{n-1} (s_i + 1) · x^(n-1-i) (mod p)
+
+    The +1 offset (Definition 2) ensures no byte maps to zero in Z/pZ,
+    preventing the zero-padding collision (Lemma 1).
+
+    Parameters
+    ----------
+    prime : int
+        A Mersenne prime. Default: 2^61 - 1.
+    base : int
+        The hash base x, chosen from {2, ..., p-1}.
+    """
+
+    __slots__ = ("_p", "_x", "_power_cache")
+
+    def __init__(self, prime: int = MERSENNE_61, base: int = 131) -> None:
+        if base < 2 or base >= prime:
+            raise ValueError(f"Base must be in [2, p-1], got {base}")
+        self._p = prime
+        self._x = base
+        self._power_cache: dict[int, int] = {0: 1, 1: base}
+
+    @property
+    def prime(self) -> int:
+        return self._p
+
+    @property
+    def base(self) -> int:
+        return self._x
+
+    def power(self, n: int) -> int:
+        """
+        Compute x^n mod p with caching.
+
+        Uses Python's built-in pow(x, n, p) which implements
+        binary exponentiation (Lemma 13).
+        """
+        if n in self._power_cache:
+            return self._power_cache[n]
+        result = pow(self._x, n, self._p)
+        self._power_cache[n] = result
+        return result
+
+    def hash(self, data: bytes) -> int:
+        """
+        Compute H(data) = Σ (data[i] + 1) · x^(n-1-i) (mod p).
+
+        For the empty string, returns 0 (Definition 2).
+
+        Parameters
+        ----------
+        data : bytes
+            The byte string to hash.
+
+        Returns
+        -------
+        int
+            Hash value in [0, p-1].
+        """
+        if len(data) == 0:
+            return 0
+
+        p = self._p
+        x = self._x
+        h = 0
+        for byte in data:
+            # h = h · x + (byte + 1)
+            h = mersenne_mod(h * x + byte + 1, p)
+        return h
+
+    def hash_concat(self, h_a: int, len_b: int, h_b: int) -> int:
+        """
+        Compute H(A ‖ B) from H(A), |B|, H(B) via Theorem 1.
+
+        H(A ‖ B) = H(A) · x^|B| + H(B) (mod p)
+        """
+        x_pow = self.power(len_b)
+        return mersenne_mod(h_a * x_pow + h_b, self._p)
+
+    def hash_repeat(self, h_s: int, d: int, q: int) -> int:
+        """
+        Compute H(S^q) from H(S) and |S| = d via Theorem 2.
+
+        H(S^q) = H(S) · Φ(q, x^d) (mod p)
+        """
+        x_d = self.power(d)
+        phi_val = phi(q, x_d, self._p)
+        return mersenne_mul(h_s, phi_val, self._p)
+
+    def hash_overlap(self, h_p: int, d: int, l: int, h_prefix: int) -> int:
+        """
+        Compute H(W) for overlapping back-reference via Theorem 5.
+
+        W = P^q ‖ P[0..r-1] where q = ⌊l/d⌋, r = l mod d.
+
+        H(W) = H(P) · Φ(q, x^d) · x^r + H(P[0..r-1]) (mod p)
+
+        Parameters
+        ----------
+        h_p : int
+            H(P), hash of the pattern of length d.
+        d : int
+            Pattern length.
+        l : int
+            Total back-reference length (d < l for overlapping).
+        h_prefix : int
+            H(P[0..r-1]) where r = l mod d. Pass 0 if r = 0.
+        """
+        q, r = divmod(l, d)
+        x_d = self.power(d)
+        x_r = self.power(r)
+
+        # H(P) · Φ(q, x^d)
+        phi_val = phi(q, x_d, self._p)
+        h_repeated = mersenne_mul(h_p, phi_val, self._p)
+
+        # · x^r + H(P[0..r-1])
+        result = mersenne_mod(h_repeated * x_r + h_prefix, self._p)
+        return result

hashrope/rope.py

@@ -0,0 +1,601 @@
+"""
+Hash rope data structure for compressed-domain hashing.
+
+Implements Part III of the framework:
+- Definition 6: Leaf, Internal, RepeatNode
+- Definition 7: Invariants I1-I9 (BB[2/7] weight balance)
+- Lemma 4: Hash correctness (structural induction)
+- Lemma 5: Height bound O(log w)
+- Lemma 6: Rotations preserve hash invariant
+- Lemma 7: RepeatNode splittability
+- Lemma 8: Join complexity O(k · |h_L - h_R|)
+- Lemma 8': RepeatNode bisection for rebalancing
+- Theorem 6: Join (full specification)
+- Theorem 7: Split in O(k · log w)
+- Theorem 8: Repeat via RepeatNode in O(k · log q), O(1) space
+- Theorem 9: Allocation-free SubstrHash in O(k · log w)
+- Theorem 10: Concat = Join
+
+All nodes are immutable (Invariant I9). Operations return new trees
+with structural sharing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from hashrope.polynomial_hash import (
+    PolynomialHash,
+    phi,
+    mersenne_mod,
+    mersenne_mul,
+    MERSENNE_61,
+)
+
+# ---------------------------------------------------------------------------
+# Balance parameter (Definition 7, Invariant I8)
+# ---------------------------------------------------------------------------
+
+# BB[α] with α = 2/7 (Nievergelt-Reingold condition).
+# A node is balanced if each child's weight is at least α * parent weight.
+ALPHA_NUM = 2
+ALPHA_DEN = 7
+
+# Type alias
+Node = Optional["Leaf | Internal | RepeatNode"]
+
+
+# ---------------------------------------------------------------------------
+# Definition 6: Node types
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class Leaf:
+    """
+    Leaf node storing a byte sequence (Definition 6a).
+
+    Invariant I1: hash_val = H(data).
+    Weight is always 1.
+    """
+
+    data: bytes
+    hash_val: int
+    len: int
+    weight: int
+
+    def __init__(self, data: bytes, h: PolynomialHash) -> None:
+        if len(data) == 0:
+            raise ValueError("Leaf cannot be empty")
+        object.__setattr__(self, "data", bytes(data))
+        object.__setattr__(self, "len", len(data))
+        object.__setattr__(self, "hash_val", h.hash(data))
+        object.__setattr__(self, "weight", 1)
+
+
+@dataclass(frozen=True, slots=True)
+class Internal:
+    """
+    Internal node joining two subtrees (Definition 6b).
+
+    Invariant I2: len = left.len + right.len
+    Invariant I3: hash_val = left.hash_val · x^(right.len) + right.hash_val
+    Invariant I4: weight = left.weight + right.weight
+    """
+
+    left: Leaf | Internal | RepeatNode
+    right: Leaf | Internal | RepeatNode
+    hash_val: int
+    len: int
+    weight: int
+
+    def __init__(
+        self,
+        left: Leaf | Internal | RepeatNode,
+        right: Leaf | Internal | RepeatNode,
+        h: PolynomialHash,
+    ) -> None:
+        object.__setattr__(self, "left", left)
+        object.__setattr__(self, "right", right)
+        object.__setattr__(self, "len", left.len + right.len)
+        object.__setattr__(self, "weight", left.weight + right.weight)
+        # I3: hash = left.hash · x^(right.len) + right.hash
+        hv = h.hash_concat(left.hash_val, right.len, right.hash_val)
+        object.__setattr__(self, "hash_val", hv)
+
+
+@dataclass(frozen=True, slots=True)
+class RepeatNode:
+    """
+    Repeat node representing child^reps (Definition 6c).
+
+    Invariant I5: len = child.len * reps
+    Invariant I6: hash_val = child.hash_val · Φ(reps, x^(child.len))
+    Invariant I7: weight = child.weight * reps
+    """
+
+    child: Leaf | Internal | RepeatNode
+    reps: int
+    hash_val: int
+    len: int
+    weight: int
+
+    def __init__(
+        self,
+        child: Leaf | Internal | RepeatNode,
+        reps: int,
+        h: PolynomialHash,
+    ) -> None:
+        if reps < 2:
+            raise ValueError(f"RepeatNode reps must be >= 2, got {reps}")
+        object.__setattr__(self, "child", child)
+        object.__setattr__(self, "reps", reps)
+        object.__setattr__(self, "len", child.len * reps)
+        object.__setattr__(self, "weight", child.weight * reps)
+        # I6: hash = child.hash · Φ(reps, x^d)
+        x_d = h.power(child.len)
+        phi_val = phi(reps, x_d, h.prime)
+        hv = mersenne_mul(child.hash_val, phi_val, h.prime)
+        object.__setattr__(self, "hash_val", hv)
+
+
+# ---------------------------------------------------------------------------
+# Accessors
+# ---------------------------------------------------------------------------
+
+
+def rope_len(node: Node) -> int:
+    """Total byte length of the string represented by node."""
+    return 0 if node is None else node.len
+
+
+def rope_hash(node: Node) -> int:
+    """Hash of the string represented by node."""
+    return 0 if node is None else node.hash_val
+
+
+def _weight(node: Node) -> int:
+    return 0 if node is None else node.weight
+
+
+def _height(node: Node) -> int:
+    """Approximate height for join decisions."""
+    if node is None:
+        return 0
+    if isinstance(node, Leaf):
+        return 1
+    if isinstance(node, RepeatNode):
+        return _height(node.child) + 1
+    # Internal
+    return 1 + max(_height(node.left), _height(node.right))
+
+
+# ---------------------------------------------------------------------------
+# Balance helpers (Invariant I8)
+# ---------------------------------------------------------------------------
+
+
+def _is_balanced(left: Node, right: Node) -> bool:
+    """Check BB[2/7] condition for a potential Internal(left, right)."""
+    total = _weight(left) + _weight(right)
+    if total <= 2:
+        return True
+    wl = _weight(left)
+    # α ≤ wl/total ≤ 1-α  ⟺  α·total ≤ wl ≤ (1-α)·total
+    # With α = 2/7: 2·total ≤ 7·wl and 7·wl ≤ 5·total
+    return ALPHA_NUM * total <= ALPHA_DEN * wl <= (ALPHA_DEN - ALPHA_NUM) * total
+
+
+def _rotate_right(node: Internal, h: PolynomialHash) -> Leaf | Internal | RepeatNode:
+    """Right rotation: Internal(Internal(A, B), C) → Internal(A, Internal(B, C))."""
+    u = node.left
+    if not isinstance(u, Internal):
+        return node  # can't rotate
+    a, b, c = u.left, u.right, node.right
+    new_right = Internal(b, c, h)
+    return Internal(a, new_right, h)
+
+
+def _rotate_left(node: Internal, h: PolynomialHash) -> Leaf | Internal | RepeatNode:
+    """Left rotation: Internal(A, Internal(B, C)) → Internal(Internal(A, B), C)."""
+    u = node.right
+    if not isinstance(u, Internal):
+        return node
+    a, b, c = node.left, u.left, u.right
+    new_left = Internal(a, b, h)
+    return Internal(new_left, c, h)
+
+
+def _rebalance(left: Leaf | Internal | RepeatNode,
+               right: Leaf | Internal | RepeatNode,
+               h: PolynomialHash) -> Leaf | Internal | RepeatNode:
+    """
+    Create a balanced Internal node from left and right.
+    Applies single or double rotations as needed (Lemma 6).
+    """
+    node = Internal(left, right, h)
+    wl, wr = _weight(left), _weight(right)
+    total = wl + wr
+
+    if total <= 2 or _is_balanced(left, right):
+        return node
+
+    if wl * ALPHA_DEN < ALPHA_NUM * total:
+        # Left too light → rotate left
+        if isinstance(right, Internal):
+            # Check if double rotation needed
+            if _weight(right.left) * ALPHA_DEN > (ALPHA_DEN - ALPHA_NUM) * wr:
+                # Double: rotate right child right, then rotate left
+                new_right = _rotate_right(right, h)
+                node = Internal(left, new_right, h)
+            return _rotate_left(node, h)
+        return node
+
+    if wr * ALPHA_DEN < ALPHA_NUM * total:
+        # Right too light → rotate right
+        if isinstance(left, Internal):
+            if _weight(left.right) * ALPHA_DEN > (ALPHA_DEN - ALPHA_NUM) * wl:
+                new_left = _rotate_left(left, h)
+                node = Internal(new_left, right, h)
+            return _rotate_right(node, h)
+        return node
+
+    return node
+
+
+# ---------------------------------------------------------------------------
+# Theorem 6 / Lemma 8: Join (Concat)
+# ---------------------------------------------------------------------------
+
+
+def rope_concat(
+    left: Node, right: Node, h: PolynomialHash
+) -> Node:
+    """
+    Join two ropes (Theorem 6, Theorem 10).
+
+    Returns a valid hash rope representing left's string ‖ right's string.
+    Time: O(k · |h_L - h_R|).
+    """
+    if left is None:
+        return right
+    if right is None:
+        return left
+    return _join(left, right, h)
+
+
+def _join(
+    left: Leaf | Internal | RepeatNode,
+    right: Leaf | Internal | RepeatNode,
+    h: PolynomialHash,
+) -> Leaf | Internal | RepeatNode:
+    """Core join with rebalancing."""
+    if _is_balanced(left, right):
+        return Internal(left, right, h)
+
+    wl, wr = _weight(left), _weight(right)
+
+    if wl > wr:
+        # Left is heavier — descend right spine of left
+        if isinstance(left, Internal):
+            new_right = _join(left.right, right, h)
+            return _rebalance(left.left, new_right, h)
+        elif isinstance(left, RepeatNode):
+            # Split the repeat node in half, join right half with right
+            mid = left.len // 2
+            ll, lr = rope_split(left, mid, h)
+            new_right = _join(lr, right, h)
+            return _join(ll, new_right, h)
+        else:
+            # Leaf — just make Internal
+            return Internal(left, right, h)
+    else:
+        # Right is heavier — descend left spine of right
+        if isinstance(right, Internal):
+            new_left = _join(left, right.left, h)
+            return _rebalance(new_left, right.right, h)
+        elif isinstance(right, RepeatNode):
+            mid = right.len // 2
+            rl, rr = rope_split(right, mid, h)
+            new_left = _join(left, rl, h)
+            return _join(new_left, rr, h)
+        else:
+            return Internal(left, right, h)
+
+
+# ---------------------------------------------------------------------------
+# Theorem 7: Split
+# ---------------------------------------------------------------------------
+
+
+def rope_split(
+    node: Node, pos: int, h: PolynomialHash
+) -> tuple[Node, Node]:
+    """
+    Split rope at byte position pos (Theorem 7).
+
+    Returns (left, right) where left has pos bytes, right has the rest.
+    Time: O(k · log w).
+    """
+    if node is None:
+        return None, None
+    if pos <= 0:
+        return None, node
+    if pos >= node.len:
+        return node, None
+    return _split(node, pos, h)
+
+
+def _split(
+    node: Leaf | Internal | RepeatNode,
+    pos: int,
+    h: PolynomialHash,
+) -> tuple[Node, Node]:
+    """Core split. 0 < pos < node.len guaranteed."""
+
+    if isinstance(node, Leaf):
+        left = Leaf(node.data[:pos], h)
+        right = Leaf(node.data[pos:], h)
+        return left, right
+
+    if isinstance(node, Internal):
+        ll = node.left.len
+        if pos == ll:
+            return node.left, node.right
+        if pos < ll:
+            l1, l2 = _split(node.left, pos, h)
+            return l1, rope_concat(l2, node.right, h)
+        else:
+            r1, r2 = _split(node.right, pos - ll, h)
+            return rope_concat(node.left, r1, h), r2
+
+    if isinstance(node, RepeatNode):
+        return _split_repeat(node, pos, h)
+
+    raise TypeError(f"Unknown node type: {type(node)}")
+
+
+def _split_repeat(
+    node: RepeatNode, pos: int, h: PolynomialHash
+) -> tuple[Node, Node]:
+    """
+    Split a RepeatNode at byte position pos (Lemma 7).
+
+    Let d = child.len, m = pos // d, r = pos % d.
+    """
+    d = node.child.len
+    m, r = divmod(pos, d)
+    q = node.reps
+
+    if r == 0:
+        # Split falls on repetition boundary
+        left = _make_repeat(node.child, m, h)
+        right = _make_repeat(node.child, q - m, h)
+        return left, right
+    else:
+        # Split falls within a repetition
+        child_left, child_right = _split(node.child, r, h)
+
+        # Left = Repeat(child, m) ‖ child_left
+        left_rep = _make_repeat(node.child, m, h)
+        left = rope_concat(left_rep, child_left, h)
+
+        # Right = child_right ‖ Repeat(child, q - m - 1)
+        right_rep = _make_repeat(node.child, q - m - 1, h)
+        right = rope_concat(child_right, right_rep, h)
+
+        return left, right
+
+
+def _make_repeat(
+    child: Leaf | Internal | RepeatNode, reps: int, h: PolynomialHash
+) -> Node:
+    """Create a Repeat with proper handling of reps 0 and 1."""
+    if reps == 0:
+        return None
+    if reps == 1:
+        return child
+    return RepeatNode(child, reps, h)
+
+
+# ---------------------------------------------------------------------------
+# Theorem 8: Repeat
+# ---------------------------------------------------------------------------
+
+
+def rope_repeat(
+    node: Leaf | Internal | RepeatNode,
+    q: int,
+    h: PolynomialHash,
+) -> Node:
+    """
+    Create a RepeatNode representing node^q (Theorem 8).
+
+    Time: O(k · log q) for the Φ computation. O(1) new nodes.
+    """
+    if q == 0:
+        return None
+    if q == 1:
+        return node
+    return RepeatNode(node, q, h)
+
+
+# ---------------------------------------------------------------------------
+# Theorem 9: SubstrHash (allocation-free)
+# ---------------------------------------------------------------------------
+
+
+def rope_substr_hash(
+    node: Node,
+    start: int,
+    length: int,
+    h: PolynomialHash,
+) -> int:
+    """
+    Compute H(S[start..start+length-1]) without allocating nodes (Theorem 9).
+
+    Time: O(k · log w). Space: O(log w) stack.
+    """
+    if node is None or length == 0:
+        return 0
+    return _hash_range(node, start, length, h)
+
+
+def _hash_range(
+    node: Leaf | Internal | RepeatNode,
+    start: int,
+    length: int,
+    h: PolynomialHash,
+) -> int:
+    """Recursive hash range query."""
+    p = h.prime
+
+    if isinstance(node, Leaf):
+        return h.hash(node.data[start:start + length])
+
+    if isinstance(node, Internal):
+        ll = node.left.len
+        if start + length <= ll:
+            # Entirely in left
+            return _hash_range(node.left, start, length, h)
+        if start >= ll:
+            # Entirely in right
+            return _hash_range(node.right, start - ll, length, h)
+        # Spanning
+        l_len = ll - start
+        r_len = length - l_len
+        h_l = _hash_range(node.left, start, l_len, h)
+        h_r = _hash_range(node.right, 0, r_len, h)
+        return h.hash_concat(h_l, r_len, h_r)
+
+    if isinstance(node, RepeatNode):
+        d = node.child.len
+        # Map into the repeating pattern
+        first_copy = start // d
+        start_in_copy = start % d
+
+        end = start + length - 1
+        last_copy = end // d
+        end_in_copy = end % d
+
+        if first_copy == last_copy:
+            # Entirely within one copy
+            return _hash_range(node.child, start_in_copy, length, h)
+
+        # Three parts: tail of first copy, full copies, head of last copy
+        # 1. Tail of first copy: child[start_in_copy .. d-1]
+        tail_len = d - start_in_copy
+        h_tail = _hash_range(node.child, start_in_copy, tail_len, h)
+
+        # 2. Full copies in the middle
+        full_copies = last_copy - first_copy - 1
+        if full_copies > 0:
+            x_d = h.power(d)
+            phi_val = phi(full_copies, x_d, p)
+            h_full = mersenne_mul(node.child.hash_val, phi_val, p)
+        else:
+            h_full = 0
+        full_len = full_copies * d
+
+        # 3. Head of last copy: child[0 .. end_in_copy]
+        head_len = end_in_copy + 1
+        h_head = _hash_range(node.child, 0, head_len, h)
+
+        # Combine: tail ‖ full ‖ head
+        # H(tail ‖ full ‖ head) = H(tail) · x^(full_len + head_len) + H(full) · x^(head_len) + H(head)
+        result = mersenne_mod(
+            h.power(full_len + head_len) * h_tail
+            + h.power(head_len) * h_full
+            + h_head,
+            p,
+        )
+        return result
+
+    raise TypeError(f"Unknown node type: {type(node)}")
+
+
+# ---------------------------------------------------------------------------
+# Reconstruction: rope → bytes
+# ---------------------------------------------------------------------------
+
+
+def rope_to_bytes(node: Node) -> bytes:
+    """Reconstruct the byte string from a rope (for testing)."""
+    if node is None:
+        return b""
+    parts: list[bytes] = []
+    _collect_bytes(node, parts)
+    return b"".join(parts)
+
+
+def _collect_bytes(node: Leaf | Internal | RepeatNode, parts: list[bytes]) -> None:
+    if isinstance(node, Leaf):
+        parts.append(node.data)
+    elif isinstance(node, Internal):
+        _collect_bytes(node.left, parts)
+        _collect_bytes(node.right, parts)
+    elif isinstance(node, RepeatNode):
+        for _ in range(node.reps):
+            _collect_bytes(node.child, parts)
+
+
+# ---------------------------------------------------------------------------
+# Construction helper
+# ---------------------------------------------------------------------------
+
+
+def rope_from_bytes(data: bytes, h: PolynomialHash) -> Node:
+    """Create a rope from a byte string. Returns None for empty."""
+    if len(data) == 0:
+        return None
+    return Leaf(data, h)
+
+
+# ---------------------------------------------------------------------------
+# Validation (for testing)
+# ---------------------------------------------------------------------------
+
+
+def validate_rope(node: Node, h: PolynomialHash | None = None) -> None:
+    """
+    Validate all rope invariants (Definition 7). Raises AssertionError on violation.
+    """
+    if node is None:
+        return
+
+    if isinstance(node, Leaf):
+        assert node.weight == 1, f"Leaf weight must be 1, got {node.weight}"
+        assert node.len == len(node.data), "Leaf len mismatch"
+        return
+
+    if isinstance(node, Internal):
+        # I2
+        assert node.len == node.left.len + node.right.len, "Internal len mismatch"
+        # I4
+        assert node.weight == node.left.weight + node.right.weight, "Internal weight mismatch"
+        # I8: balance
+        total = node.weight
+        wl = node.left.weight
+        if total > 2:
+            assert ALPHA_NUM * total <= ALPHA_DEN * wl, (
+                f"Left child too light: {wl}/{total}"
+            )
+            assert ALPHA_DEN * wl <= (ALPHA_DEN - ALPHA_NUM) * total, (
+                f"Left child too heavy: {wl}/{total}"
+            )
+        # Recurse
+        validate_rope(node.left, h)
+        validate_rope(node.right, h)
+        return
+
+    if isinstance(node, RepeatNode):
+        # I5
+        assert node.len == node.child.len * node.reps, "RepeatNode len mismatch"
+        # I7
+        assert node.weight == node.child.weight * node.reps, "RepeatNode weight mismatch"
+        assert node.reps >= 2, f"RepeatNode reps must be >= 2, got {node.reps}"
+        validate_rope(node.child, h)
+        return
+
+    raise TypeError(f"Unknown node type: {type(node)}")

hashrope/sliding.py

@@ -0,0 +1,210 @@
+"""
+Sliding window hash rope for bounded-memory streaming hash computation.
+
+Adapted from UHC's SlidingRopeState (Definition 10, Theorem 11).
+Provides a generic sliding window over a hash rope without any
+compression-format dependencies.
+
+The window maintains a prefix hash and a bounded rope, evicting old
+data as new data arrives. At any point, the full-sequence hash
+H(T[0..pos-1]) can be computed in O(1) from the prefix hash and
+the window rope hash.
+
+Invariant I_slide (holds after every operation):
+    (1) h_prefix = H(T[0 .. l_prefix - 1])
+    (2) r_window represents T[l_prefix .. pos - 1]
+    (3) rope_len(r_window) = pos - l_prefix <= W
+    (4) H(T[0..pos-1]) = h_prefix * x^(pos - l_prefix) + rope_hash(r_window)
+"""
+
+from __future__ import annotations
+
+from hashrope.polynomial_hash import PolynomialHash, MERSENNE_61
+from hashrope.rope import (
+    Leaf,
+    Node,
+    rope_concat,
+    rope_split,
+    rope_repeat,
+    rope_len,
+    rope_hash,
+)
+
+
+class SlidingWindow:
+    """
+    Bounded-memory sliding window over a hash rope.
+
+    Maintains a window of at most W = d_max + m_max bytes as a rope,
+    plus a prefix hash covering all evicted bytes. Supports two
+    operations:
+
+    - append_bytes(data): append literal bytes
+    - append_copy(offset, length): append a copy from within the window
+
+    At any point, current_hash() returns H(T[0..pos-1]) in O(1).
+
+    Parameters
+    ----------
+    d_max : int
+        Maximum copy-back distance. The window retains at least d_max
+        bytes after eviction so that future copies can find their source.
+    m_max : int
+        Maximum copy length. Together with d_max, determines the
+        maximum window extent W = d_max + m_max.
+    prime : int
+        Mersenne prime for hash arithmetic. Default: 2^61 - 1.
+    base : int
+        Hash base. Default: 131.
+    """
+
+    __slots__ = (
+        "h", "d_max", "m_max", "W",
+        "h_prefix", "l_prefix", "r_window", "pos",
+    )
+
+    def __init__(
+        self,
+        d_max: int = 32768,
+        m_max: int = 258,
+        prime: int = MERSENNE_61,
+        base: int = 131,
+    ) -> None:
+        if d_max < 1:
+            raise ValueError(f"d_max must be >= 1, got {d_max}")
+        if m_max < 1:
+            raise ValueError(f"m_max must be >= 1, got {m_max}")
+
+        self.h = PolynomialHash(prime=prime, base=base)
+        self.d_max = d_max
+        self.m_max = m_max
+        self.W = d_max + m_max
+
+        # State (Definition 10)
+        self.h_prefix: int = 0       # H(T[0..l_prefix-1])
+        self.l_prefix: int = 0       # evicted byte count
+        self.r_window: Node = None   # rope for T[l_prefix..pos-1]
+        self.pos: int = 0            # total bytes ingested
+
+    @property
+    def window_len(self) -> int:
+        """Current window size in bytes."""
+        return rope_len(self.r_window)
+
+    def current_hash(self) -> int:
+        """
+        Compute H(T[0..pos-1]) from sliding state via Theorem 1:
+            H(T) = H_prefix * x^(window_len) + H(window)
+        """
+        wl = self.window_len
+        wh = rope_hash(self.r_window) if self.r_window else 0
+        return self.h.hash_concat(self.h_prefix, wl, wh)
+
+    def final_hash(self) -> int:
+        """
+        FinalHash() -- Theorem 11.
+
+        H(T[0..N-1]) = H_prefix * x^(R_window.len) + R_window.hash
+        """
+        return self.current_hash()
+
+    def append_bytes(self, data: bytes) -> None:
+        """
+        Append literal bytes to the stream.
+
+        Parameters
+        ----------
+        data : bytes
+            One or more bytes to append.
+        """
+        if not data:
+            return
+        leaf = Leaf(data, self.h)
+        self.r_window = rope_concat(self.r_window, leaf, self.h)
+        self.pos += len(data)
+        self._evict()
+
+    def append_copy(self, offset: int, length: int) -> None:
+        """
+        Append a copy-from-window reference.
+
+        Copies `length` bytes starting `offset` bytes back from the
+        current end of the window. Handles both non-overlapping
+        (offset >= length) and overlapping (offset < length) cases.
+
+        Parameters
+        ----------
+        offset : int
+            Distance back from the current end of the window.
+            Must be <= pos and <= window_len.
+        length : int
+            Number of bytes to copy. For overlapping copies
+            (offset < length), the pattern of length `offset`
+            is repeated as needed.
+
+        Raises
+        ------
+        ValueError
+            If offset exceeds decoded length or window size.
+        """
+        win_len = self.window_len
+
+        if offset > self.pos:
+            raise ValueError(
+                f"Invalid copy: offset {offset} exceeds "
+                f"decoded length {self.pos}"
+            )
+
+        if offset > win_len:
+            raise ValueError(
+                f"Copy offset {offset} exceeds window size {win_len}. "
+                f"Increase d_max (currently {self.d_max}) to at least {offset}."
+            )
+
+        start = win_len - offset
+
+        if offset >= length:
+            # Non-overlapping
+            _, tmp = rope_split(self.r_window, start, self.h)
+            source, _ = rope_split(tmp, length, self.h)
+            self.r_window = rope_concat(self.r_window, source, self.h)
+        else:
+            # Overlapping: extract pattern of length `offset`, repeat
+            _, tmp = rope_split(self.r_window, start, self.h)
+            pattern, _ = rope_split(tmp, offset, self.h)
+
+            q, r = divmod(length, offset)
+            rep: Node = rope_repeat(pattern, q, self.h) if q >= 1 else None
+            if r > 0:
+                partial, _ = rope_split(pattern, r, self.h)
+                rep = rope_concat(rep, partial, self.h)
+            self.r_window = rope_concat(self.r_window, rep, self.h)
+
+        self.pos += length
+        self._evict()
+
+    def _evict(self) -> None:
+        """
+        Evict excess bytes from the window.
+
+        After eviction: rope_len(r_window) <= d_max, ensuring that
+        future copies of distance <= d_max find their source.
+
+        Correctness (Lemma 12): The prefix hash update follows from
+        Theorem 1 (concatenation composability).
+        """
+        win_len = rope_len(self.r_window)
+        if win_len <= self.W:
+            return
+
+        # Evict down to d_max bytes remaining
+        excess = win_len - self.d_max
+        r_old, r_keep = rope_split(self.r_window, excess, self.h)
+
+        # Fold evicted bytes into h_prefix via Theorem 1
+        old_len = rope_len(r_old)
+        old_hash = rope_hash(r_old)
+        self.h_prefix = self.h.hash_concat(self.h_prefix, old_len, old_hash)
+
+        self.l_prefix += excess
+        self.r_window = r_keep

hashrope-0.1.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: hashrope
+Version: 0.1.0
+Summary: Hash rope: a BB[2/7] balanced binary tree with polynomial hash metadata for O(log n) concat, split, substring hashing, and O(log q) repetition encoding.
+Project-URL: Homepage, https://github.com/jemsbhai/hashrope
+Project-URL: Repository, https://github.com/jemsbhai/hashrope
+Project-URL: Issues, https://github.com/jemsbhai/hashrope/issues
+Author-email: Muntaser Syed <muntaser@ieee.org>
+License: MIT
+License-File: LICENSE
+Keywords: balanced-tree,content-addressing,data-structure,hash,mersenne-prime,polynomial-hash,rope
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hashrope
+
+A BB[2/7] weight-balanced binary tree augmented with polynomial hash metadata at every node.
+
+[![PyPI version](https://img.shields.io/pypi/v/hashrope)](https://pypi.org/project/hashrope/)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/hashrope)](https://pypi.org/project/hashrope/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-88%20passing-brightgreen)](https://github.com/jemsbhai/hashrope)
+
+**Zero dependencies. Pure Python. Python 3.10+.**
+
+## What it does
+
+hashrope is a rope data structure where every node carries a polynomial hash. This enables:
+
+- **O(k log w) concat and split** with strict BB[2/7] rebalancing via recursive join
+- **O(k log q) repetition encoding** via RepeatNode -- represents "repeat this subtree q times" without materializing the data
+- **O(k log w) substring hashing** without allocating new nodes
+- **O(1) whole-sequence hash** at any point during streaming ingestion
+- **Bounded-memory sliding window** that evicts old data while maintaining a running hash of everything seen
+
+All arithmetic uses Mersenne prime modular reduction (bit-shift, no division).
+
+## Install
+
+```
+pip install hashrope
+```
+
+## Quick start
+
+```python
+from hashrope import PolynomialHash, Leaf, rope_concat, rope_split, rope_substr_hash, rope_hash
+
+h = PolynomialHash()
+
+# Build a rope
+a = Leaf(b"hello ", h)
+b = Leaf(b"world", h)
+ab = rope_concat(a, b, h)
+
+# Whole-string hash matches direct computation
+assert rope_hash(ab) == h.hash(b"hello world")
+
+# Split at any byte position
+left, right = rope_split(ab, 6, h)
+
+# Substring hash without allocation
+sub_h = rope_substr_hash(ab, 0, 5, h)
+assert sub_h == h.hash(b"hello")
+```
+
+### RepeatNode
+
+Encode repetitions in O(log q) time and O(1) space:
+
+```python
+from hashrope import PolynomialHash, Leaf, rope_repeat, rope_hash
+
+h = PolynomialHash()
+pattern = Leaf(b"ab", h)
+repeated = rope_repeat(pattern, 1000, h)  # "ab" x 1000
+
+# Hash computed in O(log 1000), not O(2000)
+assert rope_hash(repeated) == h.hash(b"ab" * 1000)
+```
+
+### SlidingWindow
+
+Bounded-memory streaming hash with copy-from-window support:
+
+```python
+from hashrope import PolynomialHash, SlidingWindow
+
+h = PolynomialHash()
+sw = SlidingWindow(d_max=1024, m_max=256)
+
+# Stream data in
+sw.append_bytes(b"hello ")
+sw.append_bytes(b"world")
+
+# Hash of everything seen so far
+assert sw.current_hash() == h.hash(b"hello world")
+
+# Copy-from-window (like LZ77 back-references)
+sw.append_copy(offset=5, length=5)  # copies "world" again
+assert sw.final_hash() == h.hash(b"hello worldworld")
+```
+
+## API reference
+
+### Polynomial hash
+
+| Function / Class | Description |
+|---|---|
+| `PolynomialHash(prime, base)` | Hash function over Z/pZ. Default: p = 2^61 - 1, base = 131 |
+| `PolynomialHash.hash(data)` | H(data) with +1 byte offset to prevent zero collisions |
+| `PolynomialHash.hash_concat(h_a, len_b, h_b)` | H(A \|\| B) from H(A), \|B\|, H(B) in O(1) |
+| `PolynomialHash.hash_repeat(h_s, d, q)` | H(S^q) from H(S) and \|S\| in O(log q) |
+| `PolynomialHash.hash_overlap(h_p, d, l, h_prefix)` | H(P^q \|\| P[0..r-1]) for overlapping references |
+| `phi(q, alpha, p)` | Geometric accumulator: sum of alpha^i for i in [0, q) in O(log q) |
+| `mersenne_mod(a, p)` | Bit-shift reduction mod Mersenne prime |
+| `mersenne_mul(a, b, p)` | Modular multiply via mersenne_mod |
+| `MERSENNE_61` | 2^61 - 1 (default prime) |
+| `MERSENNE_127` | 2^127 - 1 (high-security prime) |
+
+### Rope nodes
+
+| Class | Description |
+|---|---|
+| `Leaf(data, h)` | Immutable leaf storing a byte sequence. Weight = 1 |
+| `Internal(left, right, h)` | Internal node. Hash = H(left) \* x^len(right) + H(right) |
+| `RepeatNode(child, reps, h)` | Represents child^reps. Hash via geometric accumulator |
+
+### Rope operations
+
+| Function | Time | Description |
+|---|---|---|
+| `rope_concat(left, right, h)` | O(k \|h_L - h_R\|) | Concatenate with recursive join and BB[2/7] rebalancing |
+| `rope_split(node, pos, h)` | O(k log w) | Split at byte position |
+| `rope_repeat(node, q, h)` | O(k log q) | Create RepeatNode |
+| `rope_substr_hash(node, start, length, h)` | O(k log w) | Substring hash without allocation |
+| `rope_len(node)` | O(1) | Total byte length |
+| `rope_hash(node)` | O(1) | Hash of represented string |
+| `rope_from_bytes(data, h)` | O(n) | Create Leaf from bytes |
+| `rope_to_bytes(node)` | O(n) | Reconstruct bytes (for testing) |
+| `validate_rope(node)` | O(w) | Assert all 9 invariants hold |
+
+### SlidingWindow
+
+| Method | Description |
+|---|---|
+| `SlidingWindow(d_max, m_max, prime, base)` | Create window. W = d_max + m_max |
+| `.append_bytes(data)` | Append literal bytes |
+| `.append_copy(offset, length)` | Copy from window (handles overlapping) |
+| `.current_hash()` | H(everything seen) in O(1) |
+| `.final_hash()` | Same as current_hash (alias) |
+| `.window_len` | Current window size in bytes |
+| `.pos` | Total bytes ingested |
+
+## Mathematical foundation
+
+The data structure and its correctness proofs come from the compressed-domain hashing framework (24 theorems, 14 lemmas, 5 corollaries). Key results used by hashrope:
+
+| Result | Statement |
+|---|---|
+| Theorem 1 (Concatenation) | H(A \|\| B) = H(A) * x^{\|B\|} + H(B) |
+| Theorem 2 (Repetition) | H(S^q) = H(S) * Phi(q, x^d) |
+| Theorem 3 (Phi computation) | Phi(q, alpha) computable in O(log q) without modular inverse |
+| Theorem 6 (Join) | Recursive join with BB[2/7] rebalancing |
+| Theorem 7 (Split) | Split in O(k log w) with RepeatNode splittability |
+| Theorem 8 (Repeat) | RepeatNode in O(k log q), O(1) space |
+| Theorem 9 (SubstrHash) | Allocation-free substring hashing in O(k log w) |
+| Theorem 11 (Sliding window) | Bounded-memory streaming with eviction |
+
+## Provenance
+
+Extracted from [UHC](https://github.com/jemsbhai/uhc) (Unified Hash-Compression Engine). The rope and polynomial hash modules are verbatim copies with import paths updated. The sliding window is adapted from UHC's SlidingRopeState with the LZ77 dependency removed.
+
+## License
+
+MIT

hashrope-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+hashrope/__init__.py,sha256=Sx2C3jXNV5_mFIRc9GnuazzX4ZgBrpK6lwYLCH9E_AY,1383
+hashrope/polynomial_hash.py,sha256=W45PrlkK4OJi_a7QHdTOMFZqYvTNJrLqxjXI3RIdjDc,7520
+hashrope/rope.py,sha256=USsOegxBOqABiutYL6xSt6pDyrSCU5goWf6g8P-_Enk,19362
+hashrope/sliding.py,sha256=VoKpmxvyl7UqzCMKgQaMGi8Plt0l6EubMqHu4TKO_58,6926
+hashrope-0.1.0.dist-info/METADATA,sha256=gLMTmqb1LJcYplyOptSSQLfp1qXy2TpqaPCJd73EdFU,7400
+hashrope-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hashrope-0.1.0.dist-info/licenses/LICENSE,sha256=G8xR12Tb3ogZTszzaEMdOQYzc5ZpSvIHbiTm0bPIYpA,1091
+hashrope-0.1.0.dist-info/RECORD,,

hashrope-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hashrope-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muntaser Syed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.