https://github.com/anywave/rpp-spec

RPP (Rotational Packet Protocol) - Open semantic addressing architecture for consent-aware systems. 28-bit addresses encode meaning, not just location. Apache 2.0 + CC BY 4.0.
https://github.com/anywave/rpp-spec

28-bit-addressing ai-infrastructure bridge-architecture consent-framework consent-management defensive-publication memory-architecture open-source prior-art protocol-design protocol-specification semantic-addressing

Last synced: 2 months ago
JSON representation

RPP (Rotational Packet Protocol) - Open semantic addressing architecture for consent-aware systems. 28-bit addresses encode meaning, not just location. Apache 2.0 + CC BY 4.0.

Host: GitHub
URL: https://github.com/anywave/rpp-spec
Owner: anywave
License: apache-2.0
Created: 2025-12-27T15:57:10.000Z (3 months ago)
Default Branch: master
Last Pushed: 2026-01-04T11:12:58.000Z (3 months ago)
Last Synced: 2026-01-07T14:49:13.817Z (3 months ago)
Topics: 28-bit-addressing, ai-infrastructure, bridge-architecture, consent-framework, consent-management, defensive-publication, memory-architecture, open-source, prior-art, protocol-design, protocol-specification, semantic-addressing
Language: Python
Size: 1.04 MB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Governance: GOVERNANCE.md
- Zenodo: .zenodo.json

Awesome Lists containing this project

README

          # Rotational Packet Protocol (RPP)

**A Semantic Addressing Architecture for Consent-Aware Memory Systems**

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/anywave/rpp-spec/blob/master/LICENSE)

[![Spec Version](https://img.shields.io/badge/Spec-v2.0-green.svg)](https://github.com/anywave/rpp-spec/blob/master/spec/RPP-CANONICAL-v2.md)

[![CI](https://github.com/anywave/rpp-spec/actions/workflows/ci.yml/badge.svg)](https://github.com/anywave/rpp-spec/actions/workflows/ci.yml)

[![Python](https://img.shields.io/pypi/pyversions/rpp-protocol.svg)](https://pypi.org/project/rpp-protocol/)

[![PyPI](https://img.shields.io/pypi/v/rpp-protocol.svg)](https://pypi.org/project/rpp-protocol/)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18078640.svg)](https://doi.org/10.5281/zenodo.18078640)

> **Ra-Canonical v2.0:** RPP now uses a 32-bit Ra-derived address format. See [spec/RPP-CANONICAL-v2.md](spec/RPP-CANONICAL-v2.md) for the authoritative specification. Legacy 28-bit format documented in [spec/SPEC.md](spec/SPEC.md).

> **Disambiguation:** This specification is unrelated to AMD ROCm Performance Primitives (rocPRIM), REAPER project files (.rpp), or any other technology sharing the "RPP" abbreviation.

---

## What Problem Does RPP Solve?

RPP provides semantic addressing for consent-aware systems. Instead of opaque memory locations, RPP addresses encode meaning: what kind of data, how accessible, and where to route it. The resolver returns simple decisions: **allow**, **deny**, or **route**.

---

## What RPP Is NOT

RPP is **NOT**:

- A storage system (it routes TO storage)

- A database (use your existing database)

- An identity provider (use your existing auth)

- A policy DSL (policies are external)

- An AI system (deterministic bit operations only)

RPP **IS**:

- A deterministic 32-bit Ra-Canonical semantic address (v2.0)

- A resolver returning allow/deny/route decisions

- A bridge to existing storage backends

---

## Installation (Windows-First)

### Option 1: pip install (recommended)

```bash

pip install rpp-protocol

```

### Option 2: From source

```bash

git clone https://github.com/anywave/rpp-spec.git

cd rpp-spec

pip install -e .

```

**Works on:**

- Windows 10+ (PowerShell, CMD)

- Linux (all distributions)

- macOS

**No WSL, Docker, or Bash required on Windows.**

---

## Quick Start

### Encode an address

```bash

rpp encode --shell 0 --theta 12 --phi 40 --harmonic 1

```

Output:

```

[ENCODE] [OK]

0x0182801 | Hot | Gene | Grounded

  shell: 0 (Hot)

  theta: 12 (Gene)

  phi: 40 (Grounded)

  harmonic: 1

```

### Decode an address

```bash

rpp decode --address 0x0182801

```

Output:

```

[DECODE] [OK]

0x0182801 | Hot | Gene | Grounded

  shell: 0 (Hot)

  theta: 12 (Gene)

  phi: 40 (Grounded)

  harmonic: 1

```

### Resolve (get routing decision)

```bash

rpp resolve --address 0x0182801

```

Output:

```

[RESOLVE] [OK]

  allowed: true

    route: memory://gene/grounded/12_40_1

    reason: read permitted via memory

```

### JSON output (for scripting)

```bash

rpp encode --shell 1 --theta 100 --phi 200 --harmonic 50 --json

```

Output:

```json

{"shell":1,"theta":100,"phi":200,"harmonic":50,"address":"0x4C99032"}

```

---

## Terminal / SSH / PuTTY Usage

RPP is designed to work in **any terminal environment**, including:

- SSH sessions

- PuTTY on Windows

- Serial terminals

- Air-gapped systems

**No ANSI codes. No color. No cursor control. Plain ASCII only.**

### CLI Flags

| Flag | Description |

|------|-------------|

| `--json` | Machine-readable JSON output |

| `--visual` | Detailed ASCII diagrams |

| `--fancy` | ANSI colors (opt-in, for modern terminals) |

| `--lang` | Output language (en, ar-gulf, ar-hejaz, es, ru) |

### Multi-Language Support

RPP CLI supports 5 languages:

| Code | Language | Region |

|------|----------|--------|

| `en` | English | Default |

| `ar-gulf` | Gulf Arabic | UAE, Qatar, Kuwait, Bahrain |

| `ar-hejaz` | Hejazi Arabic | Western Saudi Arabia |

| `es` | Spanish | Global |

| `ru` | Russian | Russia, CIS |

```bash

# Spanish

rpp --lang es encode --shell 0 --theta 12 --phi 40 --harmonic 1

# Output: [CODIFICAR] [OK] ... capa: 0 (Caliente)

# Gulf Arabic

rpp --lang ar-gulf demo

# Output: [ترميز] ... الطبقة: 0 (ساخن)

# Russian

rpp --lang ru tutorial

# Output: [КОДИРОВАТЬ] ... оболочка: 0 (Горячий)

```

### Interactive Learning

```bash

rpp tutorial   # Step-by-step explanation of RPP concepts

rpp demo       # Visual demonstration of three core scenarios

```

These commands explain behavior but never change it. The core protocol remains callable without tutorials.

**[Try the Interactive Web Demo →](https://anywavecreations.com/rpp/#demo)** — Explore RPP addresses in real-time with spherical coordinate visualization.

### PuTTY Example Session

```

C:\> pip install rpp-protocol

C:\> rpp version

rpp 0.1.9

C:\> rpp demo

+===========================================================+

|                                                           |

|   RRRR   PPPP   PPPP                                      |

|   R   R  P   P  P   P   Rotational Packet Protocol        |

|   RRRR   PPPP   PPPP    Ra-Canonical v2.0 Addressing      |

|   R  R   P      P                                         |

|   R   R  P      P       Consent-Aware Routing             |

|                                                           |

+===========================================================+

============================================================

  SCENARIO 1: Allowed Read (Grounded Consent)

============================================================

+-----------------------------------------+

|           ROUTING DECISION              |

+-----------------------------------------+

|   | REQ | --> [RESOLVER] --> [ALLOWED] |

+-----------------------------------------+

|  Route:  memory://gene/grounded/12_40_1|

|  Reason: read permitted via memory     |

+-----------------------------------------+

Consent Level: [#...................] 40/511 (Grounded)

============================================================

  SCENARIO 2: Denied Write (Ethereal - Consent Required)

============================================================

+-----------------------------------------+

|           ROUTING DECISION              |

+-----------------------------------------+

|   | REQ | --> [RESOLVER] --> [DENIED]  |

+-----------------------------------------+

|  Route:  null                          |

|  Reason: Write to ethereal zone...     |

+-----------------------------------------+

Consent Level: [#################...] 450/511 (Ethereal)

============================================================

  SCENARIO 3: Cold Storage Routing

============================================================

+-----------------------------------------+

|           ROUTING DECISION              |

+-----------------------------------------+

|   | REQ | --> [RESOLVER] --> [ALLOWED] |

+-----------------------------------------+

|  Route:  archive://dream/transitional/...|

+-----------------------------------------+

+==========================+

|  Demonstration Complete  |

+==========================+

Key takeaways:

  * Low phi (Grounded) = immediate access allowed

  * High phi (Ethereal) = explicit consent required

  * Cold shell = routed to archive storage

```

### Exit Codes

| Code | Meaning |

|------|---------|

| 0 | Success |

| 1 | Invalid input |

| 2 | Resolution denied |

| 3 | Internal error |

---

## API Usage (Python)

```python

from rpp import encode, decode, from_components, resolve

# Encode an address

addr = encode(shell=0, theta=12, phi=40, harmonic=1)

print(hex(addr))  # 0x18281

# Decode an address

shell, theta, phi, harmonic = decode(addr)

# Create an address object

address = from_components(0, 12, 40, 1)

print(address.sector_name)     # Gene

print(address.grounding_level) # Grounded

print(address.shell_name)      # Hot

# Resolve an address

result = resolve(addr, operation="read")

print(result.allowed)  # True

print(result.route)    # memory://gene/grounded/12_40_1

```

---

## The Three Core Scenarios

RPP behavior is defined by exactly three scenarios:

| Scenario | Input | Result |

|----------|-------|--------|

| **Allowed read** | Low phi (grounded) | `allowed: true`, route to backend |

| **Denied write** | High phi (ethereal) | `allowed: false`, no route |

| **Archive route** | Cold shell (2) | `allowed: true`, route to archive |

These three scenarios prove RPP works. Everything else is implementation detail.

---

## Address Structure (Ra-Canonical v2.0)

```

┌─────────────────────────────────────────────────────────────┐

│               RPP CANONICAL ADDRESS (32 bits)                │

├─────────┬─────────┬─────────┬──────────┬───────────────────┤

│    θ    │    φ    │    h    │    r     │   Reserved/CRC    │

│ (5 bits)│ (3 bits)│ (3 bits)│ (8 bits) │    (13 bits)      │

├─────────┼─────────┼─────────┼──────────┼───────────────────┤

│ [31:27] │ [26:24] │ [23:21] │ [20:13]  │      [12:0]       │

└─────────┴─────────┴─────────┴──────────┴───────────────────┘

```

| Field | Width | Range | Meaning |

|-------|-------|-------|---------|

| θ (Theta) | 5 bits | 1-27 | Semantic sector (27 Repitans) |

| φ (Phi) | 3 bits | 1-6 | Access sensitivity (6 RAC levels) |

| h (Harmonic) | 3 bits | 0-4 | Coherence tier (5 Omega formats) |

| r (Radius) | 8 bits | 0-255 | Intensity scalar |

| Reserved | 13 bits | 0-8191 | CRC or future use |

> **Legacy Format:** For 28-bit v1.0 format compatibility, see [spec/SPEC.md](spec/SPEC.md).

---

## Testing

```bash

# Run all tests

pytest

# Run with verbose output

pytest -v

# Run specific test file

pytest tests/test_cli.py -v

# Run only extended spec tests

pytest tests/test_rpp_extended_spec.py -v

# Run by compliance level

pytest tests/test_rpp_extended_spec.py -v -k "Level1"  # Core only

pytest tests/test_rpp_extended_spec.py -v -k "Level2"  # Extended

pytest tests/test_rpp_extended_spec.py -v -k "Level3"  # Holographic

pytest tests/test_rpp_extended_spec.py -v -k "Level4"  # Hardware

```

All tests are subprocess-based and verify exact text output.

---

## Non-Goals (Explicit)

RPP will **never** include:

- Web UI or GUI

- Database or storage layer

- User authentication

- Machine learning

- Network transport

These are external concerns. RPP is the address layer only.

---

## Documentation

| Document | Description |

|----------|-------------|

| [spec/RPP-CANONICAL-v2.md](https://github.com/anywave/rpp-spec/blob/master/spec/RPP-CANONICAL-v2.md) | **Ra-Canonical v2.0 (32-bit) specification** |

| [spec/CONSENT-HEADER-v1.md](https://github.com/anywave/rpp-spec/blob/master/spec/CONSENT-HEADER-v1.md) | 18-byte consent header specification |

| [spec/SPEC.md](https://github.com/anywave/rpp-spec/blob/master/spec/SPEC.md) | Legacy 28-bit addressing (v1.0) |

| [spec/SPEC-EXTENDED.md](https://github.com/anywave/rpp-spec/blob/master/spec/SPEC-EXTENDED.md) | Extended 64-bit format for holographic operations |

| [spec/RESOLVER.md](https://github.com/anywave/rpp-spec/blob/master/spec/RESOLVER.md) | Resolver and adapter interfaces |

| [spec/PACKET.md](https://github.com/anywave/rpp-spec/blob/master/spec/PACKET.md) | Packet envelope format |

| [BOUNDARIES.md](https://github.com/anywave/rpp-spec/blob/master/BOUNDARIES.md) | Hard scope constraints |

| [MVP.md](https://github.com/anywave/rpp-spec/blob/master/MVP.md) | Minimum viable product |

| [MIGRATION_V2.md](https://github.com/anywave/rpp-spec/blob/master/MIGRATION_V2.md) | Migration guide v1.0 → v2.0 |

### Extensions

| Extension | Package | Description |

|-----------|---------|-------------|

| [RPP Mesh](https://github.com/anywave/rpp-spec/blob/master/spec/extensions/MESH.md) | [rpp-mesh](https://pypi.org/project/rpp-mesh/) | Consent-aware overlay network |

---

## License

| Component | License |

|-----------|---------|

| Specification | CC BY 4.0 |

| Implementation | Apache 2.0 |

---

## Citation

```

Lennon, A. L. (2025). Rotational Packet Protocol (RPP): A Semantic

Addressing Architecture for Consent-Aware Memory Systems. Version 1.0.0.

https://github.com/anywave/rpp-spec

```

---

*Open infrastructure for semantic addressing. Deterministic. Auditable. Terminal-friendly.*

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/anywave/rpp-spec

Awesome Lists containing this project

README