docs: remove comparison doc and update architecture to reflect announcement purgatory

2 files changed, 62 insertions, 448 deletions

diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md
index e0a57e5..09737df 100644
--- a/docs/explanation/architecture.md
+++ b/docs/explanation/architecture.md
@@ -2,53 +2,7 @@
 
 ## Executive Summary
 
-`ngit-grasp` implements the GRASP protocol in Rust with **inline authorization** rather than Git hooks. The key architectural insight is that we can intercept and validate Git push operations at the HTTP handler level before reaching the Git repository, eliminating the need for pre-receive hooks.
-
-## Architectural Decision: Inline vs. Hook-Based Authorization
-
-### Investigation Summary
-
-After examining both the reference implementation and HTTP server options, we have two options:
-
-#### Option 1: Hook-Based (Reference Implementation Approach)
-
-- Use standard Git HTTP backend
-- Create pre-receive and post-receive hooks
-- Hooks query the Nostr relay and validate pushes
-- **Pros**: Follows reference implementation closely
-- **Cons**: Requires hook management, harder to test, less Rust-native
-
-#### Option 2: Inline Authorization (Recommended)
-
-- Intercept Git receive-pack requests in the HTTP handler
-- Validate against Nostr state before spawning Git process
-- Only forward valid pushes to Git
-- **Pros**: Better error handling, easier testing, pure Rust, simpler deployment
-- **Cons**: Requires custom Git protocol handling
-
-### Decision: Inline Authorization (Option 2)
-
-**Rationale:**
-
-1. **Full control over HTTP layer**: Using Hyper directly gives us complete control over request handling, WebSocket upgrades, and CORS headers.
-
-2. **Better Developer Experience**:
-
-   - Validation errors can be returned as proper HTTP responses
-   - No need to parse hook stderr output
-   - Shared state between Git and Nostr components
-   - Pure Rust testing without shell scripts
-
-3. **Simpler Deployment**:
-
-   - Single binary
-   - No hook symlinks or permissions to manage
-   - No multi-process coordination
-
-4. **Performance**:
-   - Can parse incoming pack data once
-   - Avoid process spawn overhead for invalid pushes
-   - Better async integration
+`ngit-grasp` implements the GRASP protocol in Rust with **inline authorization** rather than Git hooks. Git push operations are intercepted and validated at the HTTP handler level before reaching the Git repository, eliminating the need for pre-receive hooks.
 
 ## System Architecture
 
@@ -257,57 +211,73 @@ State events undergo authorization checks at multiple points:
 
 ### 5. Purgatory System ([`src/purgatory/`](../../src/purgatory/))
 
-The purgatory system solves the "which arrives first?" problem where either nostr events or git pushes can arrive in any order. It provides an in-memory holding area for events and git data awaiting their counterparts.
+The purgatory system solves two related problems:
+
+1. **"Which arrives first?"** — Either nostr events or git pushes can arrive in any order. Purgatory holds events awaiting their git data counterparts.
+2. **Misleading empty repository announcements** — New announcements are held in purgatory until git data arrives, ensuring clients are never served announcements for repos with no content.
 
 **Design Document**: See [`purgatory-design.md`](purgatory-design.md) for complete design specifications.
 
 #### Architecture
 
 ```rust
-/// Main purgatory structure with two separate stores
+/// Main purgatory structure with separate stores per event type
 pub struct Purgatory {
+    /// Announcement events (kind 30617) indexed by (owner, identifier)
+    /// Held until git data proves content exists
+    announcement_purgatory: DashMap<(PublicKey, String), AnnouncementPurgatoryEntry>,
+
     /// State events (kind 30618) indexed by repository identifier
-    state_events: Arc<DashMap<String, Vec<StatePurgatoryEntry>>>,
+    state_events: DashMap<String, Vec<StatePurgatoryEntry>>,
     
     /// PR events (kind 1617/1618) or placeholders indexed by event ID
-    pr_events: Arc<DashMap<String, PrPurgatoryEntry>>,
+    pr_events: DashMap<String, PrPurgatoryEntry>,
 }
 ```
 
 **Key Design Principles:**
 
-1. **Separate Storage**: State events and PR events use different indexing strategies
+1. **Separate Storage**: Each event type uses a different indexing strategy
+   - Announcements: Indexed by `(pubkey, identifier)` (unique per owner)
    - State events: Indexed by `identifier` (multiple events can wait for same repo)
    - PR events: Indexed by `event_id` (one-to-one mapping)
 
-2. **Late Binding**: State event refs are extracted at git push time, not event arrival
+2. **Announcement Purgatory**: New announcements are held until git data arrives
+   - Bare repo created immediately so pushes can succeed
+   - Announcement promoted to database only when git data proves content exists
+   - Two-phase soft expiry: bare repo deleted at 30 min, event retained 24h for revival
+
+3. **Late Binding**: State event refs are extracted at git push time, not event arrival
    - Enables flexible matching when pushes arrive out-of-order
    - Helper functions in [`helpers.rs`](../../src/purgatory/helpers.rs) handle ref extraction
 
-3. **Bidirectional Waiting**: Either side can arrive first
+4. **Bidirectional Waiting**: Either side can arrive first
    - **Event-first**: Event waits for git push
    - **Git-first**: Placeholder created, waits for event
 
-4. **Automatic Expiry**: 30-minute default expiry, extensible during processing
+5. **Automatic Expiry**: 30-minute default expiry, extensible during processing
    - Background cleanup task runs every 60 seconds
-   - Removes expired entries from both stores
+   - Removes expired entries from all stores
 
 #### Data Types
 
 See [`types.rs`](../../src/purgatory/types.rs) for complete definitions:
 
 - **[`RefPair`](../../src/purgatory/types.rs:16)**: Ref name + object SHA pair
+- **[`AnnouncementPurgatoryEntry`](../../src/purgatory/types.rs)**: Announcement with bare repo path, relays, and expiry
 - **[`StatePurgatoryEntry`](../../src/purgatory/types.rs:29)**: State event with metadata
 - **[`PrPurgatoryEntry`](../../src/purgatory/types.rs:52)**: PR event or placeholder with metadata
 
 #### Integration Points
 
 **Write Policy** ([`src/nostr/policy/`](../../src/nostr/policy/)):
-- State policy checks git data existence before adding to purgatory
+- Announcement policy routes new announcements to purgatory; replacements accepted immediately
+- State policy checks git data existence before adding to purgatory; checks purgatory announcements for authorization
 - PR policy checks for placeholders before adding to purgatory
 - Events return "purgatory: will not be served until git data arrives" message
 
 **Git Handlers** ([`src/git/handlers.rs`](../../src/git/handlers.rs)):
+- On git push: Promote announcement from purgatory to database if present
 - On git push: Check purgatory for matching state events
 - On refs/nostr/* push: Check purgatory for PR events or create placeholders
 - Release events from purgatory when git data arrives
@@ -392,11 +362,25 @@ Configuration is loaded via **clap CLI > environment variables > .env > defaults
    └─ Accept or reject
                 ↓
 4. If ACCEPTED:
-   ├─ Event saved to database
-   └─ ensure_bare_repository() called
+   ├─ Is there an active announcement for (pubkey, identifier) in DB?
+   │  ├─ YES → Accept immediately (replacement, repo already proven)
+   │  └─ NO  → Route to announcement purgatory
                 ↓
-5. Bare Git repository created at
-   <git_data_path>/<npub>/<identifier>.git
+5. Announcement Purgatory path:
+   ├─ Bare Git repository created immediately at
+   │  <git_data_path>/<npub>/<identifier>.git
+   ├─ Announcement held in purgatory (not served to clients)
+   └─ Awaiting git data to prove content exists
+                ↓
+6. When git data arrives (push or background sync):
+   ├─ Announcement promoted from purgatory to database
+   ├─ Event now served to clients
+   └─ SyncManager upgrades to Full sync level
+                ↓
+7. If no git data within 30 minutes:
+   ├─ Bare repo deleted (soft expiry)
+   ├─ Event retained 24h for potential revival
+   └─ Eventually discarded if no git data arrives
 ```
 
 ### State Event Flow
@@ -407,14 +391,25 @@ Configuration is loaded via **clap CLI > environment variables > .env > defaults
 2. Nostr relay receives event
                 ↓
 3. Nip34WritePolicy::admit_event()
-   ├─ Check author is in maintainer set
+   ├─ Check author is in maintainer set (DB + purgatory announcements)
    ├─ Validate state structure
    └─ Accept or reject
                 ↓
-4. If ACCEPTED and is latest state:
-   ├─ Align repository refs to match state
-   ├─ Create/update/delete refs as needed
-   └─ Set HEAD if commit available
+4. If ACCEPTED:
+   ├─ Does git data already exist for this state?
+   │  ├─ YES → Save to database immediately
+   │  └─ NO  → Add to state purgatory
+                ↓
+5. State Purgatory path:
+   ├─ Event held in purgatory (not served to clients)
+   ├─ Enqueued for background git data sync (3 min delay)
+   └─ Awaiting git push or background sync
+                ↓
+6. When git push arrives:
+   ├─ Authorization checks both database AND purgatory
+   ├─ If authorized via purgatory state: push proceeds
+   ├─ After successful push: state event saved to database
+   └─ Removed from purgatory
 ```
 
 ## Testing Strategy
@@ -613,9 +608,7 @@ WantedBy=multi-user.target
 
 ## Conclusion
 
-The inline authorization approach provides a cleaner, more maintainable architecture than hook-based authorization while maintaining full GRASP-01 compliance. Using Hyper for the HTTP layer gives us complete control over request handling, WebSocket upgrades, and CORS headers.
-
-The key insight is that we don't need to rely on Git's hook mechanism when we have full control over the HTTP layer that Git operates through. By intercepting at the HTTP handler level, we gain better error handling, easier testing, and tighter integration between the Git and Nostr components.
+ngit-grasp uses inline authorization at the HTTP handler level, giving full control over request handling, WebSocket upgrades, and CORS headers while maintaining full GRASP-01 compliance. The purgatory system ensures that only repositories with actual git content are served to clients, and that events and git data are always consistent when released to the database.
 
 ## Related Documentation
 
diff --git a/docs/explanation/comparison.md b/docs/explanation/comparison.md
deleted file mode 100644
index 315f091..0000000
--- a/docs/explanation/comparison.md
+++ /dev/null
@@ -1,379 +0,0 @@
-# ngit-grasp vs ngit-relay Comparison
-
-This document compares ngit-grasp (this project) with ngit-relay (the reference implementation) based on their actual implementations.
-
-## High-Level Overview
-
-| Aspect | ngit-relay (Reference) | ngit-grasp (This Project) |
-|--------|------------------------|---------------------------|
-| **Language** | Go | Rust |
-| **Architecture** | Multi-process (nginx + fcgiwrap + khatru + sync daemon) | Single integrated process |
-| **Git Protocol** | git-http-backend (C via fcgiwrap) | HTTP layer in Rust + git subprocess |
-| **Authorization** | Pre-receive Git hook | Inline HTTP handler validation |
-| **Nostr Relay** | Khatru (Go library) | nostr-relay-builder (Rust library) |
-| **Event Store** | Badger (Go KV database) | LMDB (Rust) |
-| **Proactive Sync** | Git-only (polls DB + fetches from git servers) | Nostr event sync + git sync (event-driven) |
-| **Process Management** | supervisord (4 processes) | Single tokio runtime |
-| **Packaging** | Docker with supervisord | Single static binary or Docker |
-| **Configuration** | Environment variables | Environment variables + CLI flags |
-| **Total Code** | ~1,866 lines of Go | ~25,000 lines of Rust |
-
-## Architecture Comparison
-
-### ngit-relay (Multi-Process)
-
-```
-┌──────────────── Docker Container ────────────────┐
-│                                                   │
-│  ┌─────────────────────────────────────────────┐ │
-│  │            supervisord                       │ │
-│  │  - fcgiwrap (git-http-backend wrapper)      │ │
-│  │  - nginx (HTTP + reverse proxy)             │ │
-│  │  - ngit-relay-khatru (Nostr relay)          │ │
-│  │  - ngit-relay-proactive-sync (sync daemon)  │ │
-│  └─────────────────────────────────────────────┘ │
-│                                                   │
-│  ┌──────────┐         ┌────────────────────┐     │
-│  │  nginx   │────────▶│ git-http-backend   │     │
-│  │  :80     │         │ (C binary via CGI) │     │
-│  └──────┬───┘         └──────────┬─────────┘     │
-│         │                        │                │
-│         │                        ▼                │
-│         │               ┌──────────────────┐     │
-│         │               │  Git Repos       │     │
-│         │               │  + pre-receive   │     │
-│         │               │    hook (Go)     │     │
-│         │               └────────┬─────────┘     │
-│         │                        │ WebSocket     │
-│         │                        │ query         │
-│         │                        ▼                │
-│         │               ┌──────────────────┐     │
-│         └──────────────▶│  Khatru Relay    │     │
-│                         │  :3334           │     │
-│                         │  (Badger DB)     │     │
-│                         └──────────────────┘     │
-│                                                   │
-│         Separate sync daemon polls relay DB      │
-│         and fetches from remote git servers      │
-│                                                   │
-└───────────────────────────────────────────────────┘
-```
-
-### ngit-grasp (Single Process)
-
-```
-┌────────────── ngit-grasp (Single Binary) ─────────────┐
-│                                                        │
-│  ┌──────────────────────────────────────────────────┐ │
-│  │         hyper HTTP Server (:7334)                 │ │
-│  │  - WebSocket upgrade for Nostr relay              │ │
-│  │  - Git Smart HTTP handlers                        │ │
-│  │  - Landing page + metrics endpoint                │ │
-│  └───────┬──────────────────────┬───────────────────┘ │
-│          │                      │                      │
-│          ▼                      ▼                      │
-│  ┌──────────────┐      ┌────────────────────┐         │
-│  │ Git Handlers │      │  Nostr Relay       │         │
-│  │ (HTTP layer) │      │ (nostr-relay-      │         │
-│  │              │      │  builder library)  │         │
-│  │ - info/refs  │      │  - NIP-34 Policy   │         │
-│  │ - upload-pk  │◀─────┤    (inline query)  │         │
-│  │ - receive-pk │ auth │  - LMDB/Memory     │         │
-│  │   + inline   │ check│  - WebSocket       │         │
-│  │   validation │      │  - NIP-11 endpoint │         │
-│  └──────┬───────┘      └──────────┬─────────┘         │
-│         │                         │                    │
-│         ▼                         ▼                    │
-│  ┌──────────────┐      ┌────────────────────┐         │
-│  │ git binary   │      │  Purgatory         │         │
-│  │  upload-pack │      │  (in-memory queue) │         │
-│  │  receive-pk  │      │  + sync loop       │         │
-│  └──────────────┘      └────────────────────┘         │
-│                                                        │
-│  ┌──────────────────────────────────────────────────┐ │
-│  │  SyncManager (tokio background task)             │ │
-│  │  - Multi-relay Nostr event sync (GRASP-02)       │ │
-│  │  - Negentropy + REQ/EOSE support                 │ │
-│  │  - Health tracking & exponential backoff         │ │
-│  │  - Git fetch from remote servers (via purgatory) │ │
-│  └──────────────────────────────────────────────────┘ │
-│                                                        │
-│  ┌──────────────────────────────────────────────────┐ │
-│  │      Shared State (Arc<T>)                        │ │
-│  │  - Database (LMDB/Memory)                         │ │
-│  │  - Purgatory (DashMap - concurrent queue)         │ │
-│  │  - Metrics (Prometheus)                           │ │
-│  └──────────────────────────────────────────────────┘ │
-│                                                        │
-└────────────────────────────────────────────────────────┘
-```
-
-## Feature Comparison
-
-### Key Architectural Difference: Nostr Event Sync
-
-**The biggest difference between the two implementations is how they handle Nostr events:**
-
-| Aspect | ngit-relay | ngit-grasp |
-|--------|-----------|-----------|
-| **Event Arrival** | Relies on clients to push events directly | Proactively syncs events from other relays |
-| **Discovery** | None - only stores what clients send | Discovers events from relay network |
-| **Coordination** | Events and git data handled separately | Purgatory coordinates events + git data |
-| **Completeness** | May miss events if clients don't push to this relay | Actively fetches missing events from network |
-| **Implementation** | No event sync code (~0 lines) | Full multi-relay sync system (~5,000 lines) |
-
-**Example scenario:**
-- User creates PR on relay A, pushes git data to server B
-- **ngit-relay**: Only knows about events/data pushed directly to it
-- **ngit-grasp**: Discovers PR event from relay A, fetches git data from server B
-
-This is why ngit-grasp has ~13x more code - the majority is implementing GRASP-02 proactive event sync.
-
-### Git Protocol Implementation
-
-| Feature | ngit-relay | ngit-grasp |
-|---------|-----------|-----------|
-| **HTTP Server** | nginx | hyper (Rust) |
-| **Git Backend** | git-http-backend (C) via fcgiwrap | HTTP protocol layer (Rust) + git binary |
-| **Process Model** | FastCGI spawns git-http-backend | HTTP handler spawns git subprocess |
-| **Upload Pack** | C binary passthrough | Rust parses HTTP → spawns `git upload-pack` |
-| **Receive Pack** | C binary → pre-receive hook | Rust validates → spawns `git receive-pack` |
-| **Authorization** | Go hook queries relay via WebSocket | In-process function call before git spawn |
-| **Error Reporting** | Hook stderr → git client | HTTP response body (before git runs) |
-| **CORS** | nginx config | hyper middleware |
-| **Lines of Code** | ~0 (uses C binary) + hook ~135 | ~1,000+ (HTTP protocol layer) |
-
-### Authorization Logic
-
-| Feature | ngit-relay | ngit-grasp |
-|---------|-----------|-----------|
-| **Location** | pre-receive hook (separate Go binary) | Inline HTTP handler (Rust) |
-| **Trigger** | Git invokes hook during push | HTTP handler before spawning git |
-| **State Query** | WebSocket to localhost:3334 | Direct database query (in-process) |
-| **Latency** | +50-100ms (hook spawn + WS query) | +10-20ms (function call) |
-| **Error Channel** | stderr → git client | HTTP 403 response |
-| **Ref Parsing** | Read from stdin (hook protocol) | Parse from HTTP request body |
-| **Maintainer Resolution** | Recursive Go function | Recursive Rust function (similar) |
-| **State Caching** | None (queries relay per push) | Purgatory tracks pending events |
-
-### Nostr Relay
-
-| Feature | ngit-relay | ngit-grasp |
-|---------|-----------|-----------|
-| **Implementation** | Khatru (Go library) | nostr-relay-builder (Rust library) |
-| **Database** | Badger (Go KV store) | LMDB (Rust) |
-| **Process** | Separate process on :3334 | Integrated (same binary) |
-| **Policies** | Go functions in `policies.go` | Rust traits (modular sub-policies) |
-| **Event Validation** | Single function with branches | 4 separate policy modules |
-| **WebSocket** | Khatru built-in | nostr-relay-builder + hyper |
-| **NIP-11** | Manual JSON in code | Built-in support from library |
-| **Connection** | Separate from HTTP | Shared hyper server |
-| **Lines of Code** | ~186 (policies.go) + Khatru library | ~3,000+ (policy modules) + nostr-relay-builder library |
-
-### Proactive Sync
-
-| Feature | ngit-relay | ngit-grasp |
-|---------|-----------|-----------|
-| **Architecture** | Separate daemon (`ngit-relay-proactive-sync`) | Integrated SyncManager (tokio task) |
-| **Nostr Event Sync** | ❌ None (relies on client pushes) | ✅ Multi-relay sync with negentropy/REQ |
-| **Git Data Sync** | ✅ Polls local DB + fetches from git servers | ✅ Event-driven via purgatory queue |
-| **Sync Trigger** | Timer (every 15 minutes) | Immediate on event arrival + timer for retries |
-| **Relay Discovery** | N/A (no event sync) | Dynamic from 30617 announcement events |
-| **Protocol** | Git fetch only | Nostr WebSocket + git fetch |
-| **Concurrency** | Goroutines (per-repo iteration) | Tokio async tasks (per-relay connections) |
-| **Health Tracking** | Basic retry on git fetch failures | RelayHealthTracker with exponential backoff |
-| **Connection Management** | N/A (no Nostr connections) | Persistent connections with reconnect |
-| **Coordination** | Separate process | Purgatory + SyncManager coordination |
-| **Lines of Code** | ~112 (main.go) + ~305 (git sync) | ~5,000+ (Nostr sync + git sync + coordination) |
-
-### Repository Management
-
-| Feature | ngit-relay | ngit-grasp |
-|---------|-----------|-----------|
-| **Creation** | Event hook → shell commands | Event hook → tokio::process |
-| **Trigger** | `EventReceiveHook()` in Go | `handle_announcement()` in Rust |
-| **Configuration** | `git config` via shell | `git config` via tokio::process |
-| **Hook Installation** | Symlinks to pre-receive/post-receive | Not needed (inline auth) |
-| **Permissions** | `chown nginx:nginx` | tokio::fs permissions |
-| **Path Structure** | `<npub>/<id>.git` | `<npub>/<id>.git` (same) |
-
-### Event Coordination (Purgatory)
-
-| Feature | ngit-relay | ngit-grasp |
-|---------|-----------|-----------|
-| **Implementation** | None | Dedicated Purgatory system |
-| **Purpose** | N/A | Solves "which arrives first?" problem |
-| **Storage** | N/A | In-memory DashMap (thread-safe) |
-| **Expiry** | N/A | 30 minutes default TTL |
-| **State Events** | Accepted (git sync happens later via timer) | Queued until git data arrives |
-| **PR Events** | Accepted (references may be missing) | Queued with placeholder refs |
-| **Sync Queue** | Timer-based (polls all repos) | Event-driven (only syncs needed repos) |
-| **Cleanup** | N/A | Background task (60s interval) |
-| **Lines of Code** | 0 | ~2,000+ |
-
-**Impact**: ngit-relay accepts all events and relies on periodic sync to eventually fetch git data. ngit-grasp holds events in purgatory and triggers targeted syncs, providing faster convergence and better coordination between Nostr events and git data.
-
-### Deployment & Operations
-
-| Feature | ngit-relay | ngit-grasp |
-|---------|-----------|-----------|
-| **Dependencies** | nginx, git, fcgiwrap, supervisord, Go runtime | git, Rust binary (statically linked) |
-| **Process Count** | 4 (supervisord + nginx + khatru + sync) | 1 (single tokio runtime) |
-| **Configuration** | `.env` file | `.env` + CLI flags (clap) |
-| **Docker Image Size** | ~500MB (Alpine + tools + Go runtime) | ~100MB (Debian slim + git + binary) |
-| **Startup Time** | ~2-5 seconds (multiple processes) | ~0.5 seconds (single process) |
-| **Memory (Idle)** | ~150-200MB (4 processes + Go GC) | ~50-100MB (single process, no GC) |
-| **Logs** | supervisord → stdout (4 streams) | tracing → stdout (unified) |
-| **Monitoring** | None built-in | Prometheus metrics endpoint |
-| **Binary Distribution** | Docker only | Native binary + Docker |
-
-### Development Experience
-
-| Feature | ngit-relay | ngit-grasp |
-|---------|-----------|-----------|
-| **Build Time** | Fast (~5s incremental, Go) | Slow first build (~5min), fast incremental |
-| **Type Safety** | Good (Go interfaces) | Excellent (Rust traits + ownership) |
-| **Testing** | Go tests + shell scripts | Rust unit + integration tests |
-| **Test Relay** | Manual Docker setup | `TestRelay` fixture (auto-start binary) |
-| **Debugging** | Multi-process (harder) | Single process (easier) |
-| **IDE Support** | Good (gopls) | Excellent (rust-analyzer) |
-| **Async Model** | Goroutines (simple) | Tokio (more complex) |
-| **Error Handling** | `error` interface + if checks | Result<T, E> + `?` operator |
-| **Dependencies** | Go modules | Cargo crates (larger ecosystem) |
-
-### Code Complexity
-
-| Component | ngit-relay | ngit-grasp | Notes |
-|-----------|-----------|-----------|-------|
-| Main server | 129 | 196 | ngit-relay uses supervisord |
-| Git HTTP protocol | 0 (C binary via fcgiwrap) | ~1,000 | ngit-grasp implements HTTP layer |
-| Auth logic (hooks) | 135 + 52 | 0 | ngit-grasp inline, no hooks |
-| Auth logic (inline) | 0 | ~800 | ngit-grasp authorization module |
-| Nostr relay policies | 186 | ~3,000 | Both use libraries (Khatru vs nostr-relay-builder) |
-| Git-only proactive sync | 112 + 305 | 0 | ngit-relay git sync only |
-| Nostr event proactive sync | 0 | ~5,000 | ngit-grasp adds full event sync (GRASP-02 v4) |
-| Purgatory coordination | 0 | ~2,000 | ngit-grasp event/git coordination |
-| Shared utils | 241 + 132 | ~4,000 | ngit-grasp more comprehensive |
-| Config | ~50 | ~400 | ngit-grasp CLI + validation |
-| Metrics | 0 | ~1,500 | ngit-grasp Prometheus |
-| **Total** | **~1,866** | **~25,000** | ngit-grasp 13x more code |
-
-**Why the difference?**
-- **Nostr event sync**: ngit-relay has NONE, ngit-grasp implements full multi-relay event sync (~5,000 lines)
-- **Git HTTP protocol**: ngit-relay uses C binary, ngit-grasp implements HTTP layer (~1,000 lines)
-- **Purgatory coordination**: ngit-grasp adds event/git coordination system (~2,000 lines)
-- **Metrics & observability**: ngit-grasp includes comprehensive monitoring (~1,500 lines)
-- Both use relay libraries (Khatru vs nostr-relay-builder), but ngit-grasp has more modular policies
-
-### Performance Characteristics (Estimated)
-
-| Metric | ngit-relay | ngit-grasp | Notes |
-|--------|-----------|-----------|-------|
-| **Startup** | ~2-5s | ~0.5s | Single process vs multi-process |
-| **Memory (Idle)** | ~150MB | ~75MB | No GC, single process |
-| **Memory (Active)** | ~200MB+ | ~100-150MB | Depends on event volume |
-| **CPU (Idle)** | ~1-2% | ~0.5% | Fewer processes |
-| **Push Latency** | +50-100ms | +10-20ms | No hook spawn overhead |
-| **Clone Latency** | ~same | ~same | Both passthrough to git |
-| **Concurrent Pushes** | Good (goroutines) | Excellent (tokio async) |
-| **Event Ingestion** | Good (Badger) | Excellent (LMDB zero-copy) |
-| **Sync Throughput** | Moderate (polling) | High (negentropy + async) |
-
-*These are estimates based on architecture. Actual performance depends on workload.*
-
-## Migration Path
-
-For users of ngit-relay, migration to ngit-grasp involves:
-
-### Data Migration
-
-1. **Events**: Export from Badger → Import to LMDB
-   - No direct migration tool yet (would need to be built)
-   - Alternative: Use proactive sync to re-fetch from other relays
-2. **Git Repositories**: Direct copy (same structure)
-   ```bash
-   cp -r /srv/ngit-relay/repos/* /path/to/ngit-grasp/data/git/
-   ```
-3. **Configuration**: Translate environment variables
-   - Most variables are compatible (`NGIT_DOMAIN`, etc.)
-   - Remove nginx/supervisord-specific configs
-
-### Compatibility
-
-- **Git Data**: 100% compatible (same repository structure)
-- **Nostr Events**: 100% compatible (standard NIP-34)
-- **HTTP URLs**: Compatible (same path structure)
-- **Git Hooks**: ngit-grasp doesn't use hooks (inline auth instead)
-
-### Downtime
-
-- Option 1: Run both in parallel (different domains), gradually migrate
-- Option 2: Short downtime for data copy + config update
-
-## When to Choose Each
-
-### Choose ngit-relay (Reference) if:
-
-- ✅ You need proven, production-tested code
-- ✅ You're already familiar with Go ecosystem
-- ✅ You prefer simple, minimal codebases (~1,866 lines)
-- ✅ You trust battle-tested C binaries (git-http-backend)
-- ✅ You want to stay close to the reference implementation
-- ✅ You need to deploy immediately without complexity
-- ✅ Your users will push events directly to your relay (no sync needed)
-- ✅ You only need git data sync, not Nostr event sync
-
-### Choose ngit-grasp (This Project) if:
-
-- ✅ **You need Nostr event sync from other relays** (the main differentiator)
-- ✅ You want better performance and lower resource usage
-- ✅ You prefer Rust's type safety and memory safety
-- ✅ You want simpler deployment (single binary, no supervisord)
-- ✅ You need event/git data coordination (purgatory)
-- ✅ You want inline authorization (lower latency)
-- ✅ You need comprehensive observability (Prometheus metrics)
-- ✅ You're comfortable with more complex codebase (~25,000 lines)
-- ✅ You want full GRASP-02 v4 multi-relay event discovery
-
-## Current Status
-
-### ngit-relay (Reference)
-- ✅ GRASP-01 complete and production-ready
-- ✅ Git data proactive sync (fetches from git servers)
-- ❌ No Nostr event sync (relies on client pushes)
-- ✅ Battle-tested in production
-- 🔄 Community adoption growing
-
-### ngit-grasp (This Project)
-- ✅ GRASP-01 complete with comprehensive testing
-- ✅ GRASP-02 v4 multi-relay Nostr event sync with negentropy
-- ✅ Git data proactive sync (via purgatory queue)
-- ✅ Purgatory system for event/git coordination
-- ✅ Prometheus metrics and health tracking
-- ✅ NIP-77 negentropy support
-- ✅ Full integration test suite
-- 🔄 Production deployment validation ongoing
-
-## Conclusion
-
-Both implementations are valid approaches to GRASP with different philosophies:
-
-- **ngit-relay** prioritizes simplicity - clients push events, relay syncs git data (~1,866 lines)
-- **ngit-grasp** prioritizes completeness - syncs both events and git data from network (~25,000 lines)
-
-**The fundamental difference**: ngit-relay expects clients to push Nostr events to it. ngit-grasp proactively discovers and syncs events from other relays in the network.
-
-The choice depends on your priorities:
-
-| Priority | Recommendation |
-|----------|---------------|
-| **Simplicity** | ngit-relay |
-| **Event Discovery** | ngit-grasp (syncs from network) |
-| **Production Stability** | ngit-relay (more battle-tested) |
-| **Event Completeness** | ngit-grasp (proactive sync) |
-| **Low Resources** | ngit-grasp (single binary, lower memory) |
-| **Quick Deploy** | ngit-relay (Docker Compose) |
-| **Development** | ngit-grasp (better tooling, type safety) |
-| **Network Resilience** | ngit-grasp (multi-relay sync) |
-
-For deployments where **Nostr event sync** is important (discovering events from other relays), **ngit-grasp** is required. For simpler deployments where users will push events directly, **ngit-relay** is sufficient and battle-tested.