uhc 0.1.0__tar.gz

uhc-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UHC Contributors
+
+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.

uhc-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: uhc
+Version: 0.1.0
+Summary: Unified Hash-Compression Engine: compressed-domain hashing over LZ77 streams
+Author: UHC Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/uhc-framework/uhc
+Project-URL: Documentation, https://github.com/uhc-framework/uhc
+Project-URL: Repository, https://github.com/uhc-framework/uhc
+Project-URL: Issues, https://github.com/uhc-framework/uhc/issues
+Keywords: compression,hashing,lz77,deduplication,integrity,polynomial-hash,deflate,zstandard,lz4
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: System :: Archiving :: Compression
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Provides-Extra: formats
+Requires-Dist: lz4>=4.0; extra == "formats"
+Requires-Dist: zstandard>=0.22; extra == "formats"
+Requires-Dist: blake3>=1.0; extra == "formats"
+Dynamic: license-file
+
+# UHC — Unified Hash-Compression Engine
+
+A Python framework for compressed-domain hashing over LZ77 streams.
+
+UHC computes the polynomial hash of uncompressed data by operating directly on compressed token streams (DEFLATE, LZ4, Zstandard), without ever materializing the decompressed bytes.
+
+## Key Features
+
+- **Compressed-domain hashing:** Compute integrity hashes without decompression
+- **Hash-augmented rope:** Novel data structure with RepeatNode for O(k·log q) overlapping back-reference resolution
+- **Multi-hash collision resistance:** k-wise independent polynomial hashes with configurable security levels
+- **Format compatible:** DEFLATE, LZ4, Zstandard support via unified token abstraction
+- **Sliding window:** O(1) memory relative to decompressed size for bounded-window formats
+
+## Installation
+
+```bash
+pip install uhc
+```
+
+## Quick Start
+
+```python
+import uhc
+
+# Coming soon — Phase 1 implementation in progress
+```
+
+## Mathematical Foundation
+
+The complete mathematical framework (24 theorems, 14 lemmas, 5 corollaries) with full proofs is available in `theory/compressed_domain_hashing_framework.md`.
+
+## Project Status
+
+**Phase 1:** Algebraic core — polynomial hash, naive LZ77, compressed-domain verifier
+
+## License
+
+MIT

uhc-0.1.0/README.md

@@ -0,0 +1,39 @@
+# UHC — Unified Hash-Compression Engine
+
+A Python framework for compressed-domain hashing over LZ77 streams.
+
+UHC computes the polynomial hash of uncompressed data by operating directly on compressed token streams (DEFLATE, LZ4, Zstandard), without ever materializing the decompressed bytes.
+
+## Key Features
+
+- **Compressed-domain hashing:** Compute integrity hashes without decompression
+- **Hash-augmented rope:** Novel data structure with RepeatNode for O(k·log q) overlapping back-reference resolution
+- **Multi-hash collision resistance:** k-wise independent polynomial hashes with configurable security levels
+- **Format compatible:** DEFLATE, LZ4, Zstandard support via unified token abstraction
+- **Sliding window:** O(1) memory relative to decompressed size for bounded-window formats
+
+## Installation
+
+```bash
+pip install uhc
+```
+
+## Quick Start
+
+```python
+import uhc
+
+# Coming soon — Phase 1 implementation in progress
+```
+
+## Mathematical Foundation
+
+The complete mathematical framework (24 theorems, 14 lemmas, 5 corollaries) with full proofs is available in `theory/compressed_domain_hashing_framework.md`.
+
+## Project Status
+
+**Phase 1:** Algebraic core — polynomial hash, naive LZ77, compressed-domain verifier
+
+## License
+
+MIT

uhc-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uhc"
+version = "0.1.0"
+description = "Unified Hash-Compression Engine: compressed-domain hashing over LZ77 streams"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "UHC Contributors"},
+]
+keywords = [
+    "compression",
+    "hashing",
+    "lz77",
+    "deduplication",
+    "integrity",
+    "polynomial-hash",
+    "deflate",
+    "zstandard",
+    "lz4",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: System :: Archiving :: Compression",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]
+formats = [
+    "lz4>=4.0",
+    "zstandard>=0.22",
+    "blake3>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/uhc-framework/uhc"
+Documentation = "https://github.com/uhc-framework/uhc"
+Repository = "https://github.com/uhc-framework/uhc"
+Issues = "https://github.com/uhc-framework/uhc/issues"
+
+[tool.setuptools.packages.find]
+include = ["uhc*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["uhc"]
+omit = ["tests/*"]

uhc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uhc-0.1.0/tests/test_polynomial_hash.py

@@ -0,0 +1,411 @@
+"""
+Tests for uhc.core.polynomial_hash
+
+Every test is traceable to a specific definition, lemma, or theorem
+in the compressed-domain hashing framework.
+"""
+
+import pytest
+
+# Will fail until implementation exists — that's TDD.
+from uhc.core.polynomial_hash import (
+    PolynomialHash,
+    mersenne_mod,
+    mersenne_mul,
+    phi,
+)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+P61 = (1 << 61) - 1  # Mersenne prime 2^61 - 1
+
+
+# ---------------------------------------------------------------------------
+# Mersenne arithmetic tests (Lemma 14)
+# ---------------------------------------------------------------------------
+
+class TestMersenneArithmetic:
+    """Tests for modular arithmetic with p = 2^61 - 1."""
+
+    def test_mersenne_mod_zero(self):
+        """0 mod p = 0."""
+        assert mersenne_mod(0) == 0
+
+    def test_mersenne_mod_small(self):
+        """Small values are unchanged."""
+        assert mersenne_mod(42) == 42
+
+    def test_mersenne_mod_p(self):
+        """p mod p = 0."""
+        assert mersenne_mod(P61) == 0
+
+    def test_mersenne_mod_p_plus_one(self):
+        """(p + 1) mod p = 1."""
+        assert mersenne_mod(P61 + 1) == 1
+
+    def test_mersenne_mod_2p(self):
+        """2p mod p = 0."""
+        assert mersenne_mod(2 * P61) == 0
+
+    def test_mersenne_mod_large(self):
+        """Large value reduces correctly."""
+        val = (1 << 120) + 17
+        assert mersenne_mod(val) == val % P61
+
+    def test_mersenne_mul_commutative(self):
+        """a * b = b * a (mod p)."""
+        a, b = 123456789, 987654321
+        assert mersenne_mul(a, b) == mersenne_mul(b, a)
+
+    def test_mersenne_mul_identity(self):
+        """a * 1 = a (mod p)."""
+        a = 999999999
+        assert mersenne_mul(a, 1) == mersenne_mod(a)
+
+    def test_mersenne_mul_zero(self):
+        """a * 0 = 0 (mod p)."""
+        assert mersenne_mul(123456, 0) == 0
+
+    def test_mersenne_mul_correctness(self):
+        """Multiply matches Python's native modular arithmetic."""
+        a, b = 2**60 - 3, 2**60 + 7
+        assert mersenne_mul(a, b) == (a * b) % P61
+
+
+# ---------------------------------------------------------------------------
+# Definition 2: Polynomial hash function
+# ---------------------------------------------------------------------------
+
+class TestHashDefinition:
+    """Tests for H(s) = Σ (s_i + 1) · x^(n-1-i) (mod p)."""
+
+    def test_empty_string_hashes_to_zero(self):
+        """Definition 2: H(ε) = 0."""
+        h = PolynomialHash(prime=P61, base=131)
+        assert h.hash(b"") == 0
+
+    def test_single_byte(self):
+        """H((c)) = c + 1 (mod p)."""
+        h = PolynomialHash(prime=P61, base=131)
+        assert h.hash(b"\x00") == 1       # 0 + 1
+        assert h.hash(b"\x01") == 2       # 1 + 1
+        assert h.hash(b"\xff") == 256     # 255 + 1
+
+    def test_two_bytes_manual(self):
+        """H((a, b)) = (a+1)·x + (b+1) (mod p)."""
+        x = 131
+        h = PolynomialHash(prime=P61, base=x)
+        a, b = 3, 7
+        expected = ((a + 1) * x + (b + 1)) % P61
+        assert h.hash(bytes([a, b])) == expected
+
+    def test_three_bytes_manual(self):
+        """H((a,b,c)) = (a+1)·x² + (b+1)·x + (c+1) (mod p)."""
+        x = 131
+        h = PolynomialHash(prime=P61, base=x)
+        a, b, c = 10, 20, 30
+        expected = ((a + 1) * x * x + (b + 1) * x + (c + 1)) % P61
+        assert h.hash(bytes([a, b, c])) == expected
+
+
+# ---------------------------------------------------------------------------
+# Lemma 1: Nonzero coefficients
+# ---------------------------------------------------------------------------
+
+class TestLemma1:
+    """The +1 offset ensures no byte maps to zero in Z/pZ."""
+
+    def test_null_byte_nonzero(self):
+        """H((0)) ≠ 0 — the zero-padding fix."""
+        h = PolynomialHash(prime=P61, base=131)
+        assert h.hash(b"\x00") != 0
+        assert h.hash(b"\x00") == 1
+
+    def test_all_null_strings_distinct(self):
+        """Strings of different lengths composed of null bytes hash differently."""
+        h = PolynomialHash(prime=P61, base=131)
+        hashes = [h.hash(b"\x00" * n) for n in range(1, 10)]
+        assert len(set(hashes)) == 9  # all distinct
+
+
+# ---------------------------------------------------------------------------
+# Lemma 2: Distinctness of single-byte hashes
+# ---------------------------------------------------------------------------
+
+class TestLemma2:
+    """For distinct bytes a ≠ b, H((a)) ≠ H((b))."""
+
+    def test_all_single_bytes_distinct(self):
+        h = PolynomialHash(prime=P61, base=131)
+        hashes = [h.hash(bytes([b])) for b in range(256)]
+        assert len(set(hashes)) == 256
+
+
+# ---------------------------------------------------------------------------
+# Theorem 1: Concatenation composability
+# ---------------------------------------------------------------------------
+
+class TestTheorem1:
+    """H(A ‖ B) = H(A) · x^|B| + H(B) (mod p)."""
+
+    def test_concat_two_strings(self):
+        h = PolynomialHash(prime=P61, base=131)
+        A = b"Hello"
+        B = b"World"
+        h_ab = h.hash(A + B)
+        h_a = h.hash(A)
+        h_b = h.hash(B)
+        x_pow_b = h.power(len(B))
+        expected = (h_a * x_pow_b + h_b) % P61
+        assert h_ab == expected
+
+    def test_concat_empty_left(self):
+        """H(ε ‖ B) = H(B)."""
+        h = PolynomialHash(prime=P61, base=131)
+        B = b"test"
+        assert h.hash(b"" + B) == h.hash(B)
+
+    def test_concat_empty_right(self):
+        """H(A ‖ ε) = H(A)."""
+        h = PolynomialHash(prime=P61, base=131)
+        A = b"test"
+        h_a = h.hash(A)
+        x_pow_0 = h.power(0)  # x^0 = 1
+        assert (h_a * x_pow_0 + 0) % P61 == h_a
+
+    def test_concat_associativity(self):
+        """H(A ‖ B ‖ C) is consistent regardless of grouping."""
+        h = PolynomialHash(prime=P61, base=131)
+        A, B, C = b"aa", b"bb", b"cc"
+        assert h.hash(A + B + C) == h.hash(A + B + C)
+        # Verify via Theorem 1 applied twice:
+        h_ab = (h.hash(A) * h.power(len(B)) + h.hash(B)) % P61
+        h_abc = (h_ab * h.power(len(C)) + h.hash(C)) % P61
+        assert h.hash(A + B + C) == h_abc
+
+    def test_concat_random_data(self):
+        """Theorem 1 holds for random byte sequences."""
+        import os
+        h = PolynomialHash(prime=P61, base=131)
+        for _ in range(20):
+            A = os.urandom(50)
+            B = os.urandom(50)
+            h_ab = h.hash(A + B)
+            expected = (h.hash(A) * h.power(len(B)) + h.hash(B)) % P61
+            assert h_ab == expected
+
+
+# ---------------------------------------------------------------------------
+# Definition 3 + Theorem 3: Geometric accumulator Φ
+# ---------------------------------------------------------------------------
+
+class TestPhi:
+    """Φ(q, α) = Σ_{i=0}^{q-1} α^i computed by repeated doubling."""
+
+    def test_phi_zero(self):
+        """Φ(0, α) = 0."""
+        assert phi(0, 5, P61) == 0
+
+    def test_phi_one(self):
+        """Φ(1, α) = 1."""
+        assert phi(1, 5, P61) == 1
+
+    def test_phi_two(self):
+        """Φ(2, α) = 1 + α."""
+        alpha = 5
+        assert phi(2, alpha, P61) == (1 + alpha) % P61
+
+    def test_phi_three(self):
+        """Φ(3, α) = 1 + α + α²."""
+        alpha = 5
+        expected = (1 + alpha + alpha * alpha) % P61
+        assert phi(3, alpha, P61) == expected
+
+    def test_phi_matches_naive(self):
+        """Doubling recurrence matches direct summation for small q."""
+        alpha = 7
+        for q in range(20):
+            naive = sum(pow(alpha, i, P61) for i in range(q)) % P61
+            assert phi(q, alpha, P61) == naive, f"Failed at q={q}"
+
+    def test_phi_large_q(self):
+        """Φ works for large q without overflow or timeout."""
+        alpha = 131
+        q = 1_000_000
+        # Just verify it completes and returns a value in [0, p)
+        result = phi(q, alpha, P61)
+        assert 0 <= result < P61
+
+    def test_phi_degeneracy_alpha_one(self):
+        """Lemma 3: Φ(q, 1) = q (mod p) for all q."""
+        for q in [0, 1, 2, 5, 10, 100, 999]:
+            assert phi(q, 1, P61) == q % P61
+
+    def test_phi_power_of_two_q(self):
+        """Φ(2^k, α) — pure even-case recursion."""
+        alpha = 13
+        for k in range(1, 15):
+            q = 1 << k
+            naive = sum(pow(alpha, i, P61) for i in range(q)) % P61
+            assert phi(q, alpha, P61) == naive
+
+
+# ---------------------------------------------------------------------------
+# Corollary 3: Closed-form equivalence
+# ---------------------------------------------------------------------------
+
+class TestCorollary3:
+    """When α ≢ 1, Φ(q,α) = (α^q - 1) / (α - 1)."""
+
+    def test_closed_form_matches_doubling(self):
+        alpha = 7
+        for q in [1, 2, 3, 5, 10, 50, 100]:
+            doubling = phi(q, alpha, P61)
+            # Closed form: (α^q - 1) · (α - 1)^(-1) mod p
+            alpha_q = pow(alpha, q, P61)
+            numerator = (alpha_q - 1) % P61
+            denominator_inv = pow(alpha - 1, P61 - 2, P61)  # Fermat inverse
+            closed = (numerator * denominator_inv) % P61
+            assert doubling == closed, f"Failed at q={q}"
+
+
+# ---------------------------------------------------------------------------
+# Theorem 2: Geometric repetition hash
+# ---------------------------------------------------------------------------
+
+class TestTheorem2:
+    """H(S^q) = H(S) · Φ(q, x^d) (mod p)."""
+
+    def test_repeat_single_byte(self):
+        """b"A" repeated q times."""
+        h = PolynomialHash(prime=P61, base=131)
+        S = b"A"
+        for q in [1, 2, 3, 5, 10, 50]:
+            direct = h.hash(S * q)
+            h_s = h.hash(S)
+            x_d = h.power(len(S))
+            algebraic = (h_s * phi(q, x_d, P61)) % P61
+            assert direct == algebraic, f"Failed at q={q}"
+
+    def test_repeat_multi_byte_pattern(self):
+        """b"abc" repeated q times."""
+        h = PolynomialHash(prime=P61, base=131)
+        S = b"abc"
+        for q in [1, 2, 3, 7, 20]:
+            direct = h.hash(S * q)
+            h_s = h.hash(S)
+            x_d = h.power(len(S))
+            algebraic = (h_s * phi(q, x_d, P61)) % P61
+            assert direct == algebraic, f"Failed at q={q}"
+
+    def test_repeat_zero(self):
+        """S^0 = ε, H(ε) = 0."""
+        h = PolynomialHash(prime=P61, base=131)
+        h_s = h.hash(b"abc")
+        x_d = h.power(3)
+        algebraic = (h_s * phi(0, x_d, P61)) % P61
+        assert algebraic == 0
+
+
+# ---------------------------------------------------------------------------
+# Theorem 5: Overlapping back-reference hash
+# ---------------------------------------------------------------------------
+
+class TestTheorem5:
+    """H(W) = H(P) · Φ(q, x^d) · x^r + H(P[0..r-1])."""
+
+    def test_exact_repetition_no_remainder(self):
+        """l is exact multiple of d: r = 0."""
+        h = PolynomialHash(prime=P61, base=131)
+        P = b"abc"  # d = 3
+        l = 12       # q = 4, r = 0
+        d = len(P)
+        q, r = divmod(l, d)
+
+        # Direct: hash the fully expanded string
+        W = P * q
+        direct = h.hash(W)
+
+        # Algebraic
+        h_p = h.hash(P)
+        x_d = h.power(d)
+        x_r = h.power(r)  # x^0 = 1
+        algebraic = (h_p * phi(q, x_d, P61) % P61 * x_r + h.hash(b"")) % P61
+        assert direct == algebraic
+
+    def test_repetition_with_remainder(self):
+        """l is not a multiple of d: r > 0."""
+        h = PolynomialHash(prime=P61, base=131)
+        P = b"abcd"  # d = 4
+        l = 11        # q = 2, r = 3
+        d = len(P)
+        q, r = divmod(l, d)
+        assert q == 2 and r == 3
+
+        # Direct
+        W = (P * q) + P[:r]  # "abcdabcdabc"
+        direct = h.hash(W)
+
+        # Algebraic (Theorem 5)
+        h_p = h.hash(P)
+        h_prefix = h.hash(P[:r])
+        x_d = h.power(d)
+        x_r = h.power(r)
+        algebraic = (h_p * phi(q, x_d, P61) % P61 * x_r % P61 + h_prefix) % P61
+        assert direct == algebraic
+
+    def test_single_byte_run_length(self):
+        """RLE case: d=1, pattern is single byte."""
+        h = PolynomialHash(prime=P61, base=131)
+        P = b"\x42"  # d = 1
+        l = 1000
+        d = 1
+        q, r = divmod(l, d)  # q = 1000, r = 0
+
+        direct = h.hash(P * l)
+
+        h_p = h.hash(P)
+        x_d = h.power(d)
+        algebraic = (h_p * phi(q, x_d, P61)) % P61
+        assert direct == algebraic
+
+    def test_various_patterns_and_lengths(self):
+        """Sweep over multiple pattern sizes and repetition lengths."""
+        h = PolynomialHash(prime=P61, base=131)
+        import os
+        for d in [1, 2, 3, 5, 8, 13]:
+            P = os.urandom(d)
+            for l in [d, d + 1, 2 * d, 2 * d + 1, 5 * d, 5 * d + 3]:
+                q, r = divmod(l, d)
+                W = (P * q) + P[:r]
+                direct = h.hash(W)
+
+                h_p = h.hash(P)
+                h_prefix = h.hash(P[:r]) if r > 0 else 0
+                x_d = h.power(d)
+                x_r = h.power(r)
+                algebraic = (h_p * phi(q, x_d, P61) % P61 * x_r % P61 + h_prefix) % P61
+                assert direct == algebraic, f"Failed: d={d}, l={l}, q={q}, r={r}"
+
+
+# ---------------------------------------------------------------------------
+# Power computation (Lemma 13)
+# ---------------------------------------------------------------------------
+
+class TestPowerComputation:
+    """x^n computed via repeated squaring."""
+
+    def test_power_zero(self):
+        h = PolynomialHash(prime=P61, base=131)
+        assert h.power(0) == 1
+
+    def test_power_one(self):
+        h = PolynomialHash(prime=P61, base=131)
+        assert h.power(1) == 131
+
+    def test_power_matches_builtin(self):
+        h = PolynomialHash(prime=P61, base=131)
+        for n in [2, 3, 10, 50, 100, 1000]:
+            assert h.power(n) == pow(131, n, P61)

uhc-0.1.0/uhc/__init__.py

@@ -0,0 +1,10 @@
+"""
+UHC — Unified Hash-Compression Engine
+
+Compressed-domain hashing over LZ77 streams.
+Computes polynomial hashes of uncompressed data directly from
+compressed token representations without decompression.
+"""
+
+__version__ = "0.1.0"
+__author__ = "UHC Contributors"

uhc-0.1.0/uhc/core/__init__.py

@@ -0,0 +1,3 @@
+"""
+UHC Core — algebraic primitives for compressed-domain hashing.
+"""

uhc-0.1.0/uhc/core/polynomial_hash.py

@@ -0,0 +1,240 @@
+"""
+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 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

uhc-0.1.0/uhc.egg-info/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: uhc
+Version: 0.1.0
+Summary: Unified Hash-Compression Engine: compressed-domain hashing over LZ77 streams
+Author: UHC Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/uhc-framework/uhc
+Project-URL: Documentation, https://github.com/uhc-framework/uhc
+Project-URL: Repository, https://github.com/uhc-framework/uhc
+Project-URL: Issues, https://github.com/uhc-framework/uhc/issues
+Keywords: compression,hashing,lz77,deduplication,integrity,polynomial-hash,deflate,zstandard,lz4
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: System :: Archiving :: Compression
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Provides-Extra: formats
+Requires-Dist: lz4>=4.0; extra == "formats"
+Requires-Dist: zstandard>=0.22; extra == "formats"
+Requires-Dist: blake3>=1.0; extra == "formats"
+Dynamic: license-file
+
+# UHC — Unified Hash-Compression Engine
+
+A Python framework for compressed-domain hashing over LZ77 streams.
+
+UHC computes the polynomial hash of uncompressed data by operating directly on compressed token streams (DEFLATE, LZ4, Zstandard), without ever materializing the decompressed bytes.
+
+## Key Features
+
+- **Compressed-domain hashing:** Compute integrity hashes without decompression
+- **Hash-augmented rope:** Novel data structure with RepeatNode for O(k·log q) overlapping back-reference resolution
+- **Multi-hash collision resistance:** k-wise independent polynomial hashes with configurable security levels
+- **Format compatible:** DEFLATE, LZ4, Zstandard support via unified token abstraction
+- **Sliding window:** O(1) memory relative to decompressed size for bounded-window formats
+
+## Installation
+
+```bash
+pip install uhc
+```
+
+## Quick Start
+
+```python
+import uhc
+
+# Coming soon — Phase 1 implementation in progress
+```
+
+## Mathematical Foundation
+
+The complete mathematical framework (24 theorems, 14 lemmas, 5 corollaries) with full proofs is available in `theory/compressed_domain_hashing_framework.md`.
+
+## Project Status
+
+**Phase 1:** Algebraic core — polynomial hash, naive LZ77, compressed-domain verifier
+
+## License
+
+MIT

uhc-0.1.0/uhc.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+tests/test_polynomial_hash.py
+uhc/__init__.py
+uhc.egg-info/PKG-INFO
+uhc.egg-info/SOURCES.txt
+uhc.egg-info/dependency_links.txt
+uhc.egg-info/requires.txt
+uhc.egg-info/top_level.txt
+uhc/core/__init__.py
+uhc/core/polynomial_hash.py

uhc-0.1.0/uhc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

uhc-0.1.0/uhc.egg-info/requires.txt

@@ -0,0 +1,9 @@
+
+[dev]
+pytest>=8.0
+pytest-cov>=5.0
+
+[formats]
+lz4>=4.0
+zstandard>=0.22
+blake3>=1.0

uhc-0.1.0/uhc.egg-info/top_level.txt

@@ -0,0 +1 @@
+uhc