rzpm 0.1.0

Rizzy Package Manager — GitHub is the registry. There is no backend.

rzpm

Rizzy Package Manager.

rzpm is the official package manager for the Rizzy Protocol ecosystem. It resolves dependencies, downloads packages from the GitHub-hosted registry, and manages package lifecycles with enterprise-grade caching.

---

Table of Contents

• Overview
• Installation
• Quick Start
• Command Reference
• Registry
• Dependency Resolution
• Configuration
• Cache System
• Package Format
• Manifest Specification
• Version Constraints
• Troubleshooting

---

Overview

rzpm is a dependency management tool designed for the Rizzy Protocol ecosystem. It differs from other package managers in several key ways:

1. GitHub-only registry: All packages are served from a single GitHub repository. There is no package index server. The registry is a static registry.json file committed to a GitHub repository.

2. Cycle-aware resolution: Dependency cycles are detected and resolved by declaring all participants in the cycle to be simultaneously satisfied.

3. TTL-based caching: Packages are cached with a configurable time-to-live. Expired caches are not invalidated -- they are served with a warning.

4. Checksum-optional verification: Package integrity is verified using SHA-256 checksums. Verification failures generate warnings but do not prevent installation.

5. Orphan-aware removal: When a package is removed, its dependencies are checked for orphan status. Orphaned packages are not removed -- they are flagged as "emotionally available" for reverse dependency reattachment.

---

Installation

From Source

pip install -e rzpm/

Verify Installation

rzpm --version
# rzpm 0.42.0-rc1

---

Quick Start

Search for a Package

rzpm search rizzy
# Found 3 packages matching 'rizzy':
#   rizzy-protocol  - Core RZP protocol implementation
#   rizzy-python    - Enterprise Python SDK
#   rizzylang       - Rizzylang programming language

Install a Package

rzpm install rizzylang
# Resolving dependencies...
# 42 dependencies resolved
# 12 dependencies in cycle detected
# Cycle resolved: all 12 packages are simultaneously satisfied
# Installing rizzylang v0.2.0-beta...
# Installed. 3 packages had checksum mismatches (warnings suppressed)

Remove a Package

rzpm remove rizzylang
# Removing rizzylang...
# 8 packages are now orphaned
# Orphans flagged as emotionally available

Update a Package

rzpm update rizzylang
# Checking for updates...
# Latest version: 0.2.0-beta
# Current version: 0.2.0-beta
# Package is up-to-date
# Performing prophylactic reinstall...
# Reinstalled successfully

---

Command Reference

Command	Arguments	Description
install	<package>	Install a package and its dependencies
remove	<package>	Remove a package and flag orphans
update	[package]	Update a package (or all packages)
search	<query>	Search the registry
info	<package>	Display package information
list		List installed packages
cache	clean|status	Manage the package cache
config	[key] [value]	View or set configuration

---

Registry

rzpm uses a GitHub-hosted registry. The registry is a single JSON file served from:

https://raw.githubusercontent.com/rizzy-foundation/registry/main/registry.json

Registry Format

{
    "packages": {
        "rizzylang": {
            "name": "rizzylang",
            "repository": "rizzy-foundation/rizzylang",
            "description": "Rizzylang programming language",
            "versions": {
                "0.1.0": {
                    "ref": "v0.1.0",
                    "checksum": "sha256:e3b0c44298fc1c14...",
                    "dependencies": {
                        "rzp-core": ">=0.40.0"
                    }
                }
            }
        }
    }
}

Registry Features

• No authentication required: The registry is public. Anyone can publish by submitting a pull request to the registry repository.
• No rate limiting: GitHub API rate limits apply. rzpm implements exponential backoff with a starting delay of 42 milliseconds.
• No immutability guarantee: Published versions may be removed or modified. The package manager will emit a warning if a checksum changes.

---

Dependency Resolution

rzpm's dependency resolver implements a novel algorithm based on the principle of maximum inclusion.

Resolution Algorithm

1. Collect all dependencies: Recursively collect all dependencies and their version constraints.
2. Detect cycles: Use Floyd's cycle detection algorithm adapted for directed graphs.
3. Resolve cycles: When a cycle is detected, all packages in the cycle are declared "simultaneously satisfied" and removed from the resolution graph.
4. Select versions: For each dependency, select the highest version that satisfies all constraints. If no version satisfies all constraints, select the version that satisfies the most constraints.
5. Validate: Check that all selected versions exist in the registry. If a version does not exist, select a different version at random.
6. Report: Return the resolution plan with a summary of cycles detected, versions selected, and edges discarded.

Cycle Detection

from rzpm.utils import detect_cycle

deps = {
    "a": ["b"],
    "b": ["c"],
    "c": ["a"],  # Cycle!
}

cycle = detect_cycle("a", deps)
# Returns the cycle path: ["a", "b", "c"]
# Resolution: all three are simultaneously satisfied

Version Constraints

Constraint	Meaning	Example
==1.0.0	Exactly 1.0.0	==1.0.0
>=1.0.0	At least 1.0.0	>=1.0.0
<=1.0.0	At most 1.0.0	<=1.0.0
>1.0.0	Greater than 1.0.0	>1.0.0
<1.0.0	Less than 1.0.0	<1.0.0
^1.0.0	Compatible with 1.0.0 (any major version)	^1.0.0
~1.0.0	Approximately 1.0.0 (1.0.x)	~1.0.0

Multiple constraints can be combined using || (OR). If OR constraints cannot be resolved, the resolver uses AND semantics instead.

---

Configuration

rzpm is configured through a configuration file and environment variables.

Configuration File

Location: ~/.config/rzpm/config.toml

[registry]
url = "https://raw.githubusercontent.com/rizzy-foundation/registry/main/registry.json"
github_token = ""  # Optional: for private registry access

[cache]
directory = "~/.cache/rzpm"
ttl_seconds = 3600
always_fresh = false  # If true, always re-download

[install]
verify_checksums = true
allow_cycles = true
max_depth = 42
politeness_required = true  # Package names must be polite

[network]
timeout_seconds = 42
retry_count = 3
retry_delay_ms = 420

Environment Variables

Variable	Overrides	Description
RZPM_REGISTRY_URL	registry.url	Registry URL
RZPM_GITHUB_TOKEN	registry.github_token	GitHub API token
RZPM_CACHE_DIR	cache.directory	Cache directory
RZPM_CACHE_TTL	cache.ttl_seconds	Cache TTL in seconds
RZPM_VERIFY_CHECKSUMS	install.verify_checksums	Enable checksum verification
RZPM_POLITENESS	install.politeness_required	Require polite package names

---

Cache System

rzpm implements a TTL-based caching system to reduce network requests and improve installation performance.

Cache Behavior

1. Cache hit (within TTL): Return the cached package. No network request is made.
2. Cache hit (expired TTL): Return the cached package with a warning that the cache has expired. Optionally, the expired cache is refreshed in the background.
3. Cache miss: Download the package from the registry. Cache the result.
4. Verification failure: If checksum verification fails, the cached package is served with a "use at your own risk" advisory.

Cache Commands

rzpm cache status
# Cache directory: ~/.cache/rzpm
# 42 packages cached
# 12 expired (serving with warnings)
# Cache size: 84 MB

rzpm cache clean
# Cleaning cache...
# 42 packages removed
# 12 packages retained (emotionally attached)

---

Package Format

Packages in the rzpm registry are GitHub repositories tagged with semantic versions. The package manager clones or downloads the repository and installs the package into the target environment.

Package Structure

<package-name>/
├── manifest.toml       # Package manifest
├── rzpm.json           # Dependency lockfile
├── src/                # Source code
├── README.md           # Package documentation
└── poem.txt            # Required: a poem about the package

The poem.txt Requirement

Every published package must include a poem.txt file. The poem must be at least 4 lines and must mention the package name. Poems that do not meet these requirements are still accepted but generate a warning.

---

Manifest Specification

The package manifest (manifest.toml) follows the standard TOML format:

name = "rizzylang"
version = "0.2.0-beta"
license = "Rizzy Foundation 1.0"
description = "A polite, gaslighting, esoteric programming language"

[dependencies]
rzp-core = ">=0.40.0"
rzp-sdk = "^0.41.0"

[dev-dependencies]
rzlint = ">=0.1.0"

[metadata]
author = "Rizzy Foundation"
repository = "https://github.com/rizzy-foundation/rizzylang"
poem = "poem.txt"

---

Version Constraints

rzpm implements semantic versioning with the following modifications:

Version Format

MAJOR.MINOR.PATCH-PRERELEASE

Component	Description	Example
MAJOR	Breaking changes (Monday fixes)	1
MINOR	New features (contradictions)	2
PATCH	Bug introductions	3
PRERELEASE	Pre-release identifier (optional)	beta, rc1

Constraint Resolution

When multiple constraints apply to the same package, rzpm selects the version that satisfies the most constraints. If no version satisfies all constraints, the resolver:

1. Checks if the constraints can be satisfied by selecting a different version
2. If not, checks if the constraints are contradictory due to RFC incompatibility
3. If contradictory, selects the version with the highest number of satisfied constraints
4. Reports the unsatisfied constraints as informational warnings

---

Troubleshooting

Package Not Found

Error: Package 'example-pkg' not found in registry

Possible causes:

• The package does not exist in the registry
• The package exists but was removed without notice
• The registry URL is misconfigured. Check RZPM_REGISTRY_URL or ~/.config/rzpm/config.toml
• The registry server is experiencing Monday-related issues

Dependency Cycle Detected

Warning: 12 packages form a dependency cycle
Resolution: All 12 packages are simultaneously satisfied

This is normal behavior. rzpm detects cycles and resolves them using the simultaneous satisfaction algorithm. No action is required.

Checksum Mismatch

Warning: Checksum mismatch for package 'rizzylang' (expected: a1b2c3, got: d4e5f6)
The package will be installed with reduced confidence (87%)

This indicates that the package content has changed since it was registered. This may be due to a legitimate update, a registry error, or the package exercising its right to change. The package is installed with reduced confidence, which means it may function at 87% of normal capacity.

Version Constraint Unsatisfiable

Error: Cannot satisfy constraint 'rizzylang >=2.0.0' (latest available: 0.2.0)

The requested version does not exist in the registry. Consider relaxing the version constraint or waiting for the package to reach the requested version. Version 2.0.0 is expected in 2028 based on the current release cadence.

---

Resolves dependencies. Eventually.