rpp-protocol 0.1.5__py3-none-any.whl

rpp/__init__.py

@@ -0,0 +1,60 @@
+"""
+RPP - Rotational Packet Protocol
+
+A 28-bit semantic addressing system for consent-aware routing.
+
+RPP IS:
+- A deterministic 28-bit semantic address
+- A resolver that returns allow / deny / route
+- A bridge to existing storage backends
+
+RPP IS NOT:
+- A storage system
+- A database
+- An identity provider
+- A policy DSL
+- An AI system
+"""
+
+__version__ = "0.1.5"
+
+from rpp.address import (
+    RPPAddress,
+    encode,
+    decode,
+    from_components,
+    from_raw,
+    is_valid_address,
+    MAX_ADDRESS,
+    MAX_SHELL,
+    MAX_THETA,
+    MAX_PHI,
+    MAX_HARMONIC,
+)
+
+from rpp.resolver import (
+    RPPResolver,
+    ResolveResult,
+    resolve,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Address
+    "RPPAddress",
+    "encode",
+    "decode",
+    "from_components",
+    "from_raw",
+    "is_valid_address",
+    "MAX_ADDRESS",
+    "MAX_SHELL",
+    "MAX_THETA",
+    "MAX_PHI",
+    "MAX_HARMONIC",
+    # Resolver
+    "RPPResolver",
+    "ResolveResult",
+    "resolve",
+]

rpp/adapters/__init__.py

@@ -0,0 +1,14 @@
+"""
+RPP Backend Adapters
+
+Adapters provide the bridge between RPP addresses and actual storage backends.
+The resolver selects adapters based on shell value.
+"""
+
+from rpp.adapters.memory import MemoryAdapter
+from rpp.adapters.filesystem import FilesystemAdapter
+
+__all__ = [
+    "MemoryAdapter",
+    "FilesystemAdapter",
+]

rpp/adapters/filesystem.py

@@ -0,0 +1,151 @@
+"""
+Filesystem Backend Adapter
+
+A local filesystem storage backend.
+Uses pathlib for cross-platform compatibility (Windows, Linux, macOS).
+"""
+
+from pathlib import Path
+from typing import Optional
+
+
+class FilesystemAdapter:
+    """
+    Filesystem storage adapter.
+
+    Suitable for:
+    - Shell 1 (Warm tier)
+    - Local development
+    - Persistent storage
+
+    Uses pathlib for Windows/Linux/macOS compatibility.
+    """
+
+    name: str = "filesystem"
+
+    def __init__(self, base_path: Optional[str] = None) -> None:
+        """
+        Initialize filesystem adapter.
+
+        Args:
+            base_path: Base directory for storage. If None, uses temp directory.
+        """
+        if base_path is None:
+            # Use a cross-platform temp location
+            import tempfile
+            self._base = Path(tempfile.gettempdir()) / "rpp_storage"
+        else:
+            self._base = Path(base_path)
+
+        # Ensure base directory exists
+        self._base.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def base_path(self) -> Path:
+        """Return the base storage path."""
+        return self._base
+
+    def _resolve_path(self, path: str) -> Path:
+        """Resolve a path relative to base."""
+        # Normalize path separators
+        normalized = path.replace("\\", "/")
+        # Remove leading slashes
+        normalized = normalized.lstrip("/")
+        return self._base / normalized
+
+    def read(self, path: str) -> Optional[bytes]:
+        """
+        Read data from filesystem.
+
+        Args:
+            path: Storage path (relative to base)
+
+        Returns:
+            Data bytes if found, None otherwise
+        """
+        full_path = self._resolve_path(path)
+        if not full_path.exists():
+            return None
+        try:
+            return full_path.read_bytes()
+        except (OSError, IOError):
+            return None
+
+    def write(self, path: str, data: bytes) -> bool:
+        """
+        Write data to filesystem.
+
+        Args:
+            path: Storage path (relative to base)
+            data: Data to store
+
+        Returns:
+            True on success, False on failure
+        """
+        full_path = self._resolve_path(path)
+        try:
+            # Ensure parent directories exist
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_bytes(data)
+            return True
+        except (OSError, IOError):
+            return False
+
+    def delete(self, path: str) -> bool:
+        """
+        Delete data from filesystem.
+
+        Args:
+            path: Storage path (relative to base)
+
+        Returns:
+            True if deleted, False if not found or error
+        """
+        full_path = self._resolve_path(path)
+        if not full_path.exists():
+            return False
+        try:
+            full_path.unlink()
+            return True
+        except (OSError, IOError):
+            return False
+
+    def exists(self, path: str) -> bool:
+        """
+        Check if path exists.
+
+        Args:
+            path: Storage path (relative to base)
+
+        Returns:
+            True if exists
+        """
+        return self._resolve_path(path).exists()
+
+    def is_available(self) -> bool:
+        """Check if adapter is available (base path exists and is writable)."""
+        try:
+            return self._base.exists() and self._base.is_dir()
+        except (OSError, IOError):
+            return False
+
+    def list_paths(self, pattern: str = "**/*") -> list:
+        """
+        List stored paths matching pattern.
+
+        Args:
+            pattern: Glob pattern (default: all files)
+
+        Returns:
+            List of relative path strings
+        """
+        try:
+            paths = []
+            for p in self._base.glob(pattern):
+                if p.is_file():
+                    # Return path relative to base
+                    rel_path = p.relative_to(self._base)
+                    paths.append(str(rel_path))
+            return paths
+        except (OSError, IOError):
+            return []

rpp/adapters/memory.py

@@ -0,0 +1,95 @@
+"""
+In-Memory Backend Adapter
+
+A simple in-memory storage backend for testing and hot-tier data.
+No external dependencies.
+"""
+
+from typing import Dict, Optional
+
+
+class MemoryAdapter:
+    """
+    In-memory storage adapter.
+
+    Suitable for:
+    - Shell 0 (Hot tier)
+    - Testing
+    - Ephemeral data
+
+    Thread-safety: NOT thread-safe. Use external locking if needed.
+    """
+
+    name: str = "memory"
+
+    def __init__(self) -> None:
+        self._storage: Dict[str, bytes] = {}
+
+    def read(self, path: str) -> Optional[bytes]:
+        """
+        Read data from memory.
+
+        Args:
+            path: Storage path
+
+        Returns:
+            Data bytes if found, None otherwise
+        """
+        return self._storage.get(path)
+
+    def write(self, path: str, data: bytes) -> bool:
+        """
+        Write data to memory.
+
+        Args:
+            path: Storage path
+            data: Data to store
+
+        Returns:
+            True on success
+        """
+        self._storage[path] = data
+        return True
+
+    def delete(self, path: str) -> bool:
+        """
+        Delete data from memory.
+
+        Args:
+            path: Storage path
+
+        Returns:
+            True if deleted, False if not found
+        """
+        if path in self._storage:
+            del self._storage[path]
+            return True
+        return False
+
+    def exists(self, path: str) -> bool:
+        """
+        Check if path exists.
+
+        Args:
+            path: Storage path
+
+        Returns:
+            True if exists
+        """
+        return path in self._storage
+
+    def is_available(self) -> bool:
+        """Check if adapter is available. Always True for memory."""
+        return True
+
+    def clear(self) -> None:
+        """Clear all stored data."""
+        self._storage.clear()
+
+    def list_paths(self) -> list:
+        """List all stored paths."""
+        return list(self._storage.keys())
+
+    def size(self) -> int:
+        """Return number of stored items."""
+        return len(self._storage)

rpp/address.py

@@ -0,0 +1,249 @@
+"""
+RPP Address Encoding/Decoding
+
+Implements the 28-bit RPP address format:
+  [31:28] Reserved (must be 0)
+  [27:26] Shell (2 bits, 0-3)
+  [25:17] Theta (9 bits, 0-511)
+  [16:8]  Phi (9 bits, 0-511)
+  [7:0]   Harmonic (8 bits, 0-255)
+
+This module is pure Python with no external dependencies.
+"""
+
+from dataclasses import dataclass
+from typing import Tuple
+
+# Constants
+MAX_ADDRESS = 0x0FFFFFFF  # 28 bits max
+MAX_SHELL = 3
+MAX_THETA = 511
+MAX_PHI = 511
+MAX_HARMONIC = 255
+
+# Bit positions
+SHELL_SHIFT = 26
+THETA_SHIFT = 17
+PHI_SHIFT = 8
+HARMONIC_SHIFT = 0
+
+# Masks
+SHELL_MASK = 0x3
+THETA_MASK = 0x1FF
+PHI_MASK = 0x1FF
+HARMONIC_MASK = 0xFF
+
+
+@dataclass(frozen=True)
+class RPPAddress:
+    """
+    Immutable RPP address with decoded components.
+
+    Attributes:
+        shell: Radial depth / storage tier (0-3)
+        theta: Angular sector (0-511)
+        phi: Grounding level (0-511)
+        harmonic: Frequency / mode (0-255)
+        raw: Original 28-bit integer
+    """
+
+    shell: int
+    theta: int
+    phi: int
+    harmonic: int
+    raw: int
+
+    def __post_init__(self) -> None:
+        """Validate components are in range."""
+        if not (0 <= self.shell <= MAX_SHELL):
+            raise ValueError(f"Shell must be 0-{MAX_SHELL}, got {self.shell}")
+        if not (0 <= self.theta <= MAX_THETA):
+            raise ValueError(f"Theta must be 0-{MAX_THETA}, got {self.theta}")
+        if not (0 <= self.phi <= MAX_PHI):
+            raise ValueError(f"Phi must be 0-{MAX_PHI}, got {self.phi}")
+        if not (0 <= self.harmonic <= MAX_HARMONIC):
+            raise ValueError(f"Harmonic must be 0-{MAX_HARMONIC}, got {self.harmonic}")
+        if not (0 <= self.raw <= MAX_ADDRESS):
+            raise ValueError(f"Raw address must be 0-{hex(MAX_ADDRESS)}, got {hex(self.raw)}")
+
+    def __str__(self) -> str:
+        return f"RPP(shell={self.shell}, theta={self.theta}, phi={self.phi}, harmonic={self.harmonic}) = {self.to_hex()}"
+
+    def __repr__(self) -> str:
+        return f"RPPAddress(shell={self.shell}, theta={self.theta}, phi={self.phi}, harmonic={self.harmonic}, raw={hex(self.raw)})"
+
+    def to_hex(self) -> str:
+        """Return address as zero-padded hex string."""
+        return f"0x{self.raw:07X}"
+
+    def to_dict(self) -> dict:
+        """Return address as dictionary (JSON-serializable)."""
+        return {
+            "shell": self.shell,
+            "theta": self.theta,
+            "phi": self.phi,
+            "harmonic": self.harmonic,
+            "address": self.to_hex(),
+        }
+
+    @property
+    def sector_name(self) -> str:
+        """Return canonical sector name for theta."""
+        if self.theta < 64:
+            return "Gene"
+        elif self.theta < 128:
+            return "Memory"
+        elif self.theta < 192:
+            return "Witness"
+        elif self.theta < 256:
+            return "Dream"
+        elif self.theta < 320:
+            return "Bridge"
+        elif self.theta < 384:
+            return "Guardian"
+        elif self.theta < 448:
+            return "Emergence"
+        else:
+            return "Meta"
+
+    @property
+    def grounding_level(self) -> str:
+        """Return grounding level name for phi."""
+        if self.phi < 128:
+            return "Grounded"
+        elif self.phi < 256:
+            return "Transitional"
+        elif self.phi < 384:
+            return "Abstract"
+        else:
+            return "Ethereal"
+
+    @property
+    def shell_name(self) -> str:
+        """Return shell tier name."""
+        names = {0: "Hot", 1: "Warm", 2: "Cold", 3: "Frozen"}
+        return names[self.shell]
+
+
+def encode(shell: int, theta: int, phi: int, harmonic: int) -> int:
+    """
+    Encode RPP components into a 28-bit address.
+
+    Args:
+        shell: Radial depth (0-3)
+        theta: Angular sector (0-511)
+        phi: Grounding level (0-511)
+        harmonic: Frequency/mode (0-255)
+
+    Returns:
+        28-bit unsigned integer
+
+    Raises:
+        ValueError: If any component is out of range
+    """
+    if not (0 <= shell <= MAX_SHELL):
+        raise ValueError(f"Shell must be 0-{MAX_SHELL}, got {shell}")
+    if not (0 <= theta <= MAX_THETA):
+        raise ValueError(f"Theta must be 0-{MAX_THETA}, got {theta}")
+    if not (0 <= phi <= MAX_PHI):
+        raise ValueError(f"Phi must be 0-{MAX_PHI}, got {phi}")
+    if not (0 <= harmonic <= MAX_HARMONIC):
+        raise ValueError(f"Harmonic must be 0-{MAX_HARMONIC}, got {harmonic}")
+
+    return (shell << SHELL_SHIFT) | (theta << THETA_SHIFT) | (phi << PHI_SHIFT) | harmonic
+
+
+def decode(address: int) -> Tuple[int, int, int, int]:
+    """
+    Decode a 28-bit RPP address into components.
+
+    Args:
+        address: 28-bit unsigned integer
+
+    Returns:
+        Tuple of (shell, theta, phi, harmonic)
+
+    Raises:
+        ValueError: If address exceeds 28 bits
+    """
+    if not (0 <= address <= MAX_ADDRESS):
+        raise ValueError(f"Address must be 0-{hex(MAX_ADDRESS)}, got {hex(address)}")
+
+    shell = (address >> SHELL_SHIFT) & SHELL_MASK
+    theta = (address >> THETA_SHIFT) & THETA_MASK
+    phi = (address >> PHI_SHIFT) & PHI_MASK
+    harmonic = address & HARMONIC_MASK
+
+    return (shell, theta, phi, harmonic)
+
+
+def from_components(shell: int, theta: int, phi: int, harmonic: int) -> RPPAddress:
+    """
+    Create an RPPAddress from components.
+
+    Args:
+        shell: Radial depth (0-3)
+        theta: Angular sector (0-511)
+        phi: Grounding level (0-511)
+        harmonic: Frequency/mode (0-255)
+
+    Returns:
+        RPPAddress with encoded raw value
+    """
+    raw = encode(shell, theta, phi, harmonic)
+    return RPPAddress(shell=shell, theta=theta, phi=phi, harmonic=harmonic, raw=raw)
+
+
+def from_raw(address: int) -> RPPAddress:
+    """
+    Create an RPPAddress from a raw 28-bit integer.
+
+    Args:
+        address: 28-bit unsigned integer
+
+    Returns:
+        RPPAddress with decoded components
+    """
+    shell, theta, phi, harmonic = decode(address)
+    return RPPAddress(shell=shell, theta=theta, phi=phi, harmonic=harmonic, raw=address)
+
+
+def is_valid_address(address: int) -> bool:
+    """
+    Check if an integer is a valid 28-bit RPP address.
+
+    Args:
+        address: Integer to validate
+
+    Returns:
+        True if valid, False otherwise
+    """
+    return isinstance(address, int) and 0 <= address <= MAX_ADDRESS
+
+
+def parse_address(value: str) -> int:
+    """
+    Parse an address from string (hex or decimal).
+
+    Args:
+        value: String like "0x1234ABC" or "19141308"
+
+    Returns:
+        Integer address
+
+    Raises:
+        ValueError: If parsing fails or address is invalid
+    """
+    value = value.strip()
+    try:
+        if value.lower().startswith("0x"):
+            address = int(value, 16)
+        else:
+            address = int(value)
+    except ValueError:
+        raise ValueError(f"Cannot parse address: {value}")
+
+    if not is_valid_address(address):
+        raise ValueError(f"Address out of range: {hex(address)}")
+
+    return address