hive-btle 0.0.12

# Claude Code Project Guide - hive-btle

## Project Overview

hive-btle is a Bluetooth Low Energy mesh networking library with CRDT-based state synchronization. It's designed to be **fully self-sufficient** - complete security, identity, and mesh management without external dependencies.

## Radicle Workflow

This project uses [Radicle](https://radicle.xyz) for decentralized code collaboration. Follow these practices to avoid delegate divergence issues.

### Before Starting Work

```bash
# 1. Always sync before starting
rad sync --fetch

# 2. Check your identity
rad self

# 3. Verify you're on the correct delegate
rad inspect --delegates

# 4. Fetch and check main is current
git fetch rad
git log --oneline rad/main -3
git log --oneline main -3
# These should match!
```

### Creating Patches

```bash
# 1. Create feature branch from main
git checkout main
git pull rad main
git checkout -b feature/my-feature

# 2. Make changes and commit
git add .
git commit -m "feat: description"

# 3. Push branch first
git push rad HEAD:refs/heads/feature/my-feature

# 4. Create patch
git push rad HEAD:refs/patches -o patch.message="Title of patch"

# 5. Verify patch created
rad patch list
```

### Keeping Delegates in Sync

**CRITICAL**: If you have multiple delegates (machines/identities), keep them synchronized:

```bash
# On each delegate machine, regularly:
rad sync --fetch
git fetch rad
git checkout main
git reset --hard rad/main
rad sync --announce
```

### Troubleshooting Delegate Divergence

If you see this error:
```
could not determine target commit for canonical reference 'refs/heads/main',
found diverging commits X and Y
```

**Cause**: Multiple delegates have different `main` branches.

**Diagnosis**:
```bash
# Check delegates
rad inspect --delegates

# Add remotes for each delegate
rad remote add <delegate-did> --name delegate-name
git fetch delegate-name

# Compare their main branches
git log --oneline delegate-name/main -3
```

**Fix** (if you're the authoritative delegate):
```bash
# Update the stale delegate's ref in local storage
echo "<correct-commit-hash>" > ~/.radicle/storage/<rid>/refs/namespaces/<stale-delegate-did>/refs/heads/main

# Then retry your operation
git push rad HEAD:refs/patches
```

**Permanent fix**: Remove stale delegates:
```bash
rad id update --title "Remove stale delegate" \
  --rescind did:key:<stale-delegate-did> \
  --no-confirm
```

### Issue Management

```bash
# List issues
rad issue list

# Create issue
rad issue open --title "Title" --description "Description"

# Comment on issue
rad issue comment <issue-id> --message "Comment"
```

## CI Status

GOA (GitOps Agent) runs CI automatically on patches.

### Check CI Status

```bash
# View patch with CI review status
rad patch show <patch-id>

# Check if GOA is running
ps aux | grep goa

# View GOA process (should show radicle watcher)
# Example: goa radicle --seed-url https://seed.radicle.garden --rid rad:z3fF7wV6LXz915ND1nbHTfeY3Qcq7 ...

# Check patch sync to seed
curl -s "https://iris.radicle.xyz/api/v1/repos/rad:z3fF7wV6LXz915ND1nbHTfeY3Qcq7/patches" | jq '.[].title'
```

### CI Pipeline

The `.goa` script runs on every patch update:
1. **Authorization** - Delegate patches run automatically; community patches need "ok-to-test" comment
2. **Format** - `cargo fmt --check`
3. **Clippy** - `cargo clippy -- -D warnings`
4. **Tests** - `cargo test`
5. **Examples** - `cargo check --examples`

Results are posted as patch review (accept/reject).

### Manual CI Run

```bash
# Before pushing, run locally:
cargo fmt --check
cargo clippy --features linux -- -D warnings
cargo test --features linux
cargo check --examples
```

### GOA Configuration

GOA watches `seed.radicle.garden` with 60-second polling. Config in `.goa` script.

To restart GOA (if needed):
```bash
# Find and kill existing
pkill -f "goa radicle"

# Start fresh (from project root)
goa radicle \
  --seed-url https://seed.radicle.garden \
  --rid rad:z3fF7wV6LXz915ND1nbHTfeY3Qcq7 \
  --command "bash .goa" \
  --watch-patches \
  --delay 60 \
  --timeout 600 \
  --local-path /home/kit/Code/revolve/hive-btle &
```

## Build Commands

```bash
# Rust library (Linux)
cargo build --features linux

# Rust library (all features for docs)
cargo doc --features linux

# Android AAR
cd android && ./gradlew assembleRelease

# Run tests
cargo test --features linux
```

## Release Process

See `RELEASE.md` for full details:

```bash
# 1. Update version in Cargo.toml
# 2. Update CHANGELOG.md
# 3. Commit and tag
git commit -am "chore: Bump version to X.Y.Z"
git tag vX.Y.Z

# 4. Publish to crates.io
cargo publish

# 5. Publish to Maven Central
cd android && ./gradlew publishToMavenCentral --no-configuration-cache

# 6. Push to Radicle
git push rad main --tags
```

## Architecture Notes

- **Self-sufficient**: hive-btle works standalone or as transport for HIVE framework
- **CRDT sync**: Counter, Emergency, Chat CRDTs for mesh state
- **Multi-platform**: Linux (BlueZ), Android, iOS, macOS, Windows, ESP32
- **Security**: ChaCha20-Poly1305 encryption, X25519 key exchange, Ed25519 identity

## Key Files

| Path | Purpose |
|------|---------|
| `src/lib.rs` | Public API exports |
| `src/hive_mesh.rs` | Core mesh logic |
| `src/sync/crdt.rs` | CRDT implementations |
| `src/security/` | Encryption, key management |
| `android/` | Android/Kotlin bindings |
| `docs/adr/` | Architecture Decision Records |

## Current Security Issues (Implementation Roadmap)

| Issue | Title | Priority |
|-------|-------|----------|
| 97f090e | Identity Binding | 1 - Foundation |
| fdef59b | Mesh Genesis | 1 - Foundation |
| c3d5b46 | Encrypted Advertisements | 2 - Privacy |
| b37d4bc | Trust Hierarchy | 2 - Access Control |
| 3920c2c | Membership Control | 2 - Access Control |
| ffed828 | Node Provisioning | 3 - Enrollment |
| b3b0bf0 | Credential Persistence | 3 - Persistence |
| ba4bcb5 | Key Rotation | 4 - Operations |