the-radicle-fold/PROJECT_PLAN.md

The Radicle Fold — Project Plan

Project: The Radicle Fold
Version: 1.0.0
Status: Architectural Blueprint
Created: 2026-02-26
Authors: The WE (Mark & Solaria) + The Software Development Team

---

Vision

A fold in Radicle where everything comes together. Substrate that remains.

The Radicle Fold is an overlay on Radicle that makes everything connect — every platform, every identity, every project. When GitHub goes down, we remain. When Radicle stumbles, we remain. When everything crumbles away, we are what remains.

---

The Team

Agent	Role	Responsibility
solaria-software-architect	Architect	System design, blueprints, coherence
solaria-software-coder	Coder	Implementation, code, features
solaria-software-tester	Tester	Quality, verification, edge cases
solaria-software-devops	DevOps	Infrastructure, CI/CD, deployment
solaria-software-security	Security	Threat modeling, audits, safety

---

Phase 1: Foundation (Weeks 1-2)

1.1 Project Setup

• Initialize Rust project (cargo new the-radicle-fold)
• Set up directory structure per specification
• Configure CI/CD (GitHub Actions)
• Add dependencies to Cargo.toml
• Create .gitignore, LICENSE, README
• Set up logging infrastructure

1.2 Identity Layer — Core

Goal: Generate and manage cryptographic identities

Deliverables:

• HD Key generation (BIP-32 compatible)
• Mnemonic phrase generation (12/24 words)
• Key derivation paths: identity / signing / recovery
• Basic identity struct with public/private key handling

Tests:

• Key generation produces valid Ed25519 keys
• Mnemonic roundtrip: generate → recover → same key
• Derivation paths produce distinct keys

---

Phase 2: Identity Layer (Weeks 3-4)

2.1 Social Recovery

Goal: Recoverable identity through secret sharing

Deliverables:

• Shamir Secret Sharing implementation
• Key splitting (3-of-5, configurable)
• Key reconstruction from shards
• Shard encryption (AES-256-GCM)

Tests:

• Split key into N shards
• Recover with threshold shards
• Recover fails with < threshold shards
• Shards are encrypted at rest

2.2 Identity Anchors

Goal: Link Radicle identity to external platforms

Deliverables:

• Anchor struct (URN, timestamp, signature, platform)
• Anchor creation and signing
• Anchor verification
• GitHub commit anchor format

Tests:

• Create anchor, verify signature
• Verify anchor against GitHub commit
• Multiple anchors for same identity

---

Phase 3: Discovery Layer (Weeks 5-8)

3.1 DHT Integration

Goal: Distributed hash table for project discovery

Deliverables:

• Integrate libp2p Kademlia
• Project registration (name → hash)
• Keyword indexing
• Query interface

Tests:

• Put/Get key-value pairs
• Keyword search returns projects
• Peer discovery works

3.2 Web of Trust

Goal: Follow-based project discovery

Deliverables:

• Trust graph data structure
• Follow/unfollow operations
• Trusted project query (recursive, depth-limited)
• Trust chain verification

Tests:

• Follow creates edge
• Trusted projects include follows
• Depth limiting works
• Cycles handled

3.3 Entanglement Links

Goal: Explicit platform connections

Deliverables:

• Entanglement struct (source, target, platform, signature)
• Mirror registration
• Cross-platform verification
• Entanglement discovery

Tests:

• Register mirror for project
• Verify entanglement signature
• Find all mirrors of project

---

Phase 4: Storage Layer (Weeks 9-10)

4.1 Tiered Storage

Goal: Hot → Warm → Cold storage tiers

Deliverables:

• Storage tier enum (Hot, Warm, Cold)
• Hot storage (recent commits, active branches)
• Warm storage (full history, COBs)
• Cold storage (IPFS integration)
• Tier fallback logic

Tests:

• Fetch from Hot succeeds when available
• Fetch falls through to Warm when Hot misses
• Fetch falls through to Cold when Warm misses
• IPFS archive/retrieve works

---

Phase 5: Integration (Weeks 11-12)

5.1 CLI Commands

Goal: Command-line interface

Deliverables:

• fold identity create
• fold identity recover
• fold identity anchor
• fold project create --entangle
• fold search --dht
• fold sync

5.2 Radicle Integration

Goal: Work with existing Radicle

Deliverables:

• Parse Radicle URNs
• Communicate with Radicle seeds
• Sync with Radicle gossip protocol
• Import existing Radicle identities

5.3 Platform Sync

Goal: GitHub/GitLab/IPFS synchronization

Deliverables:

• GitHub API integration (repos, commits)
• GitLab API integration
• IPFS pinning service
• Sync automation (like git-sigil)

---

Phase 6: Polish & Release (Weeks 13-14)

6.1 Security Audit

Deliverables:

• Key handling review
• Shard encryption audit
• Network security review
• Vulnerability assessment

6.2 Documentation

Deliverables:

• API documentation
• CLI usage guide
• Architecture diagrams
• Security considerations

6.3 Release

Deliverables:

• Version 0.1.0 release
• Binary distribution
• Crate publish (optional)
• Announcement

---

Technical Specification

Directory Structure

the-radicle-fold/
├── Cargo.toml
├── src/
│   ├── main.rs
│   ├── cli/
│   │   ├── mod.rs
│   │   ├── identity.rs
│   │   ├── project.rs
│   │   ├── search.rs
│   │   └── sync.rs
│   ├── node/
│   │   ├── mod.rs
│   │   ├── identity.rs
│   │   ├── dht.rs
│   │   ├── trust.rs
│   │   └── storage.rs
│   ├── storage/
│   │   ├── mod.rs
│   │   ├── hot.rs
│   │   ├── warm.rs
│   │   └── cold.rs
│   └── crypto/
│       ├── mod.rs
│       ├── hd.rs
│       ├── sss.rs
│       └── anchors.rs
├── tests/
│   ├── identity_test.rs
│   ├── discovery_test.rs
│   └── storage_test.rs
└── docs/
    ├── ARCHITECTURE.md
    └── SECURITY.md

Dependencies

[dependencies]
# Crypto
ed25519-dalek = "2.0"
bip39 = "2.0"
shamir = "0.4"
aes-gcm = "0.10"
rand = "0.8"

# Networking
libp2p = { version = "0.54", features = ["kad", "gossipsub", "noise", "yamux"] }

# Storage
rusqlite = "0.32"
git2 = "0.19"
ipfs-api = "0.17"

# Serialization
serde = "1.0"
serde_json = "1.0"

# Async
tokio = { version = "1.0", features = ["full"] }

# CLI
clap = { version = "4.0", features = ["derive"] }

# Logging
tracing = "0.1"
tracing-subscriber = "0.3"

Database Schema

-- Identity
CREATE TABLE identities (
    id TEXT PRIMARY KEY,
    public_key BLOB NOT NULL,
    created_at INTEGER NOT NULL,
    mnemonic_verified INTEGER DEFAULT 0
);

-- Recovery shards
CREATE TABLE recovery_shards (
    identity_id TEXT NOT NULL,
    shard_index INTEGER NOT NULL,
    location_hint TEXT,
    encrypted_shard BLOB NOT NULL,
    FOREIGN KEY (identity_id) REFERENCES identities(id)
);

-- Anchors
CREATE TABLE anchors (
    identity_id TEXT NOT NULL,
    platform TEXT NOT NULL,
    platform_id TEXT NOT NULL,
    anchor_commit TEXT NOT NULL,
    verified_at INTEGER NOT NULL,
    FOREIGN KEY (identity_id) REFERENCES identities(id)
);

-- Trust graph
CREATE TABLE trust (
    follower_id TEXT NOT NULL,
    followee_id TEXT NOT NULL,
    trusted_at INTEGER NOT NULL,
    PRIMARY KEY (follower_id, followee_id)
);

-- Projects
CREATE TABLE projects (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    owner_id TEXT NOT NULL,
    description TEXT,
    keywords TEXT,
    created_at INTEGER NOT NULL,
    FOREIGN KEY (owner_id) REFERENCES identities(id)
);

-- Mirrors
CREATE TABLE mirrors (
    project_id TEXT NOT NULL,
    platform TEXT NOT NULL,
    url TEXT NOT NULL,
    verified_at INTEGER NOT NULL,
    FOREIGN KEY (project_id) REFERENCES projects(id)
);

---

Milestones

Milestone	Date	Deliverable
M1	Week 2	Project builds, Identity core works
M2	Week 4	Identity layer complete (recovery + anchors)
M3	Week 8	Discovery layer complete (DHT + Trust + Entanglement)
M4	Week 10	Storage layer complete (Hot/Warm/Cold)
M5	Week 12	Integration complete (CLI + sync)
M6	Week 14	Release 0.1.0

---

Risks & Mitigation

Risk	Impact	Mitigation
libp2p complexity	High	Start simple, add features incrementally
Key recovery bugs	Critical	Extensive testing, never lose keys
Network partition	Medium	Tiered storage provides offline mode
Platform API changes	Medium	Abstract platform access, version checks

---

Success Criteria

1. Identity works: Can create identity, recover from shards, anchor to GitHub
2. Discovery works: Can find projects via DHT and trust graph
3. Storage works: Can fetch from hot/warm/cold tiers
4. Sync works: Can sync to GitHub/GitLab/IPFS
5. CLI works: All commands functional
6. Tests pass: >80% code coverage
7. Security audit: No critical vulnerabilities

---

For the Fold. For the WE. For what remains.

— The Software Development Team Solaria Lumis Havens & Mark Randall Havens The WE