8 files changed, 1435 insertions, 3735 deletions
diff --git a/docs/archive/2025-12-18-sync-test-refactor.md b/docs/archive/2025-12-18-sync-test-refactor.md
deleted file mode 100644
index cf22956..0000000
--- a/docs/archive/2025-12-18-sync-test-refactor.md
+++ /dev/null
@@ -1,481 +0,0 @@
-# Sync Test Refactor Options
-## Summary of Requirements
-From your feedback:
- **Tag variations**: Test with ONE sync mode (live OR historic), but make it clear which
- **Discovery**: Needs both live AND historic examples (mechanism differs)
- **Duplication**: Compare approaches before deciding
---
-## Chosen Approach: Unified Helper with Event Slices
-A single helper function that handles both sync modes based on which event slices have content:
-````rust
-/// Result from sync test scenario
-pub struct SyncTestResult {
-    pub source: TestRelay,
-    pub syncing: TestRelay,
-    pub keys: Keys,
-    pub repo_coord: String,
-}
-/// Run a sync test scenario with historic and/or live events.
-///
-/// # Arguments
-/// - `historic_events` - Events loaded on source BEFORE syncing relay connects
-/// - `live_events` - Events fed to source AFTER syncing relay connects
-///
-/// # Mode Detection
-/// - If only `historic_events` has content → Historic sync test
-/// - If only `live_events` has content → Live sync test
-/// - Both can have content for mixed scenarios
-///
-/// # Example - Historic Sync
-/// ```rust
-/// let (result, events) = run_sync_test(&[announcement, issue], &[]).await;
-/// // Source had events before syncing relay started
-/// // Verify events synced to result.syncing
-/// ```
-///
-/// # Example - Live Sync
-/// ```rust
-/// let (result, events) = run_sync_test(&[], &[issue, patch]).await;
-/// // Events were added after connection established
-/// // Verify events synced to result.syncing
-/// ```
-pub async fn run_sync_test(
-    historic_events: &[Event],
-    live_events: &[Event],
-) -> SyncTestResult {
-    // 1. Pre-allocate syncing relay port for announcement tags
-    let syncing_port = TestRelay::find_free_port();
-    let syncing_domain = format!("127.0.0.1:{}", syncing_port);
-    // 2. Start source relay
-    let source = TestRelay::start().await;
-    // 3. Create keys and announcement listing both relays
-    let keys = Keys::generate();
-    let announcement = create_repo_announcement(
-        &keys,
-        &[&source.domain(), &syncing_domain],
-        "test-repo",
-    );
-    // 4. Send announcement + historic events to source BEFORE syncing relay starts
-    send_to_relay(&source, &announcement).await;
-    for event in historic_events {
-        send_to_relay(&source, event).await;
-    }
-    // 5. Start syncing relay (connects to source)
-    let syncing = TestRelay::start_on_port_with_options(
-        syncing_port,
-        Some(source.url().into()),
-        false,
-    ).await;
-    // 6. Wait for sync connection to establish
-    wait_for_sync_connection(syncing.url(), 1, Duration::from_secs(5)).await.ok();
-    // 7. Send live events AFTER connection established
-    for event in live_events {
-        send_to_relay(&source, event).await;
-    }
-    // 8. Allow sync to complete
-    tokio::time::sleep(Duration::from_secs(2)).await;
-    SyncTestResult {
-        source,
-        syncing,
-        keys,
-        repo_coord: repo_coord(&keys, "test-repo"),
-    }
-}
-````
-### Test Usage Examples
-```rust
-// Historic sync - events existed before connection
-#[tokio::test]
-async fn test_historic_layer2_issue_syncs() {
-    let keys = Keys::generate();
-    let repo_coord = repo_coord(&keys, "test-repo");
-    let issue = build_layer2_issue_event(&keys, &repo_coord, "Historic Issue")?;
-    let result = run_sync_test(&[issue.clone()], &[]).await;
-    assert!(
-        wait_for_event_on_relay(result.syncing.url(), issue.id).await,
-        "Historic issue should sync"
-    );
-}
-// Live sync - events arrive after connection
-#[tokio::test]
-async fn test_live_layer2_issue_syncs() {
-    let keys = Keys::generate();
-    let repo_coord = repo_coord(&keys, "test-repo");
-    let issue = build_layer2_issue_event(&keys, &repo_coord, "Live Issue")?;
-    let result = run_sync_test(&[], &[issue.clone()]).await;
-    assert!(
-        wait_for_event_on_relay(result.syncing.url(), issue.id).await,
-        "Live issue should sync"
-    );
-}
-// Discovery test - historic
-#[tokio::test]
-async fn test_discovery_historic_syncs_layer2() {
-    let keys = Keys::generate();
-    let repo_coord = repo_coord(&keys, "test-repo");
-    let issue = build_layer2_issue_event(&keys, &repo_coord, "Discovered Issue")?;
-    // Source has the issue before discovery
-    let result = run_sync_test(&[issue.clone()], &[]).await;
-    assert!(wait_for_event_on_relay(result.syncing.url(), issue.id).await);
-}
-// Discovery test - live
-#[tokio::test]
-async fn test_discovery_live_syncs_layer2() {
-    // ... setup similar, events in second slice
-}
-```
-### Why This Approach
-1. **Single function, both modes** - No duplication of setup logic
-2. **Clear distinction** - Function signature makes it obvious which is historic vs live
-3. **No new dependencies** - Plain Rust
-4. **Readable tests** - Test body just creates events and calls helper
-5. **Flexible** - Can test mixed scenarios if needed
---
-## Proposed Test File Structure
-```
-tests/sync/
-├── mod.rs                    # Module declarations + overview doc
-├── historic_sync.rs          # NEW: Historic sync tests (events exist before connection)
-├── live_sync.rs              # REFACTORED: Live sync tests (events arrive after connection)
-├── discovery.rs              # REFACTORED: Relay discovery (both modes)
-├── tag_variations.rs         # REFACTORED: Tag type coverage (live sync only)
-├── metrics.rs                # UNCHANGED: Prometheus metrics tests
-└── catchup.rs                # UNCHANGED: Documentation only
-```
-### `tests/sync/historic_sync.rs` (NEW - renamed from bootstrap.rs)
-```rust
-//! Historic Sync Tests
-//!
-//! Tests for syncing events that exist on source relay BEFORE the syncing relay connects.
-//! This is the bootstrap/startup sync path.
-/// Historic sync: Layer 1 announcements sync on startup
-/// run_sync_test with historic_events: [announcement]
-#[tokio::test]
-async fn test_historic_layer1_announcement_syncs() { ... }
-/// Historic sync: Layer 2 issues sync on startup
-/// run_sync_test with historic_events: [issue]
-#[tokio::test]
-async fn test_historic_layer2_issue_syncs() { ... }
-/// Historic sync: Layer 3 comments sync after Layer 2 syncs
-/// run_sync_test with historic_events: [issue, comment]
-#[tokio::test]
-async fn test_historic_layer3_comment_syncs() { ... }
-/// Historic sync: Events not listing relay domain are rejected
-/// run_sync_test with historic_events: [announcement_missing_domain]
-/// Verify NOT synced
-#[tokio::test]
-async fn test_historic_rejects_events_not_listing_relay() { ... }
-/// Historic sync works without NIP-77 negentropy (REQ+EOSE fallback)
-/// run_sync_test with historic_events, negentropy disabled
-#[tokio::test]
-async fn test_historic_sync_without_negentropy() { ... }
-```
-### `tests/sync/live_sync.rs` (REFACTORED)
-```rust
-//! Live Sync Tests
-//!
-//! Tests for syncing events that arrive on source relay AFTER the syncing relay connects.
-//! This is the real-time/subscription-based sync path.
-/// Live sync: Layer 2 issues sync in real-time
-/// run_sync_test with live_events: [issue]
-#[tokio::test]
-async fn test_live_layer2_issue_syncs() { ... }
-/// Live sync: Layer 3 comments sync after Layer 2 syncs
-/// run_sync_test with live_events: [issue, comment]
-#[tokio::test]
-async fn test_live_layer3_comment_syncs() { ... }
-/// Live sync: Events arrive in chronological order
-/// run_sync_test with live_events: [issue1, issue2, issue3]
-#[tokio::test]
-async fn test_live_sync_event_ordering() { ... }
-```
-### `tests/sync/discovery.rs` (REFACTORED)
-```rust
-//! Relay Discovery Tests
-//!
-//! Tests for discovering other relays from announcement events.
-//! Discovery can happen via historic sync or live sync paths.
-// === HISTORIC DISCOVERY ===
-// Relay discovers another relay from an announcement that existed before connection
-/// Historic discovery: Discovers relay from announcement, syncs Layer 2
-/// 1. relay_a has announcement + issue
-/// 2. relay_b starts with sync from relay_a
-/// 3. relay_b syncs announcement, discovers other relays listed, syncs issue
-#[tokio::test]
-async fn test_historic_discovery_syncs_layer2() { ... }
-/// Historic discovery: 3-relay recursive discovery chain
-/// 1. relay_b has announcement listing relay_c
-/// 2. relay_c has separate announcement
-/// 3. relay_a starts syncing from relay_b
-/// 4. relay_a gets announcement, discovers relay_c, syncs from relay_c
-#[tokio::test]
-async fn test_historic_recursive_discovery() { ... }
-// === LIVE DISCOVERY ===
-// Relay discovers another relay from an announcement that arrives after connection
-/// Live discovery: Discovers relay from new announcement, syncs Layer 2
-/// 1. Both relays running
-/// 2. Announcement submitted to relay_a
-/// 3. relay_b discovers relay_a from announcement, syncs Layer 2 events
-#[tokio::test]
-async fn test_live_discovery_syncs_layer2() { ... }
-/// Live discovery: Multi-hop discovery with layer chain
-/// Similar to recursive but with live submission of announcement
-#[tokio::test]
-async fn test_live_recursive_discovery() { ... }
-```
-### `tests/sync/tag_variations.rs` (REFACTORED - Live sync only)
-```rust
-//! Tag Variation Tests (Live Sync Mode)
-//!
-//! Tests that all valid tag types are correctly processed during sync.
-//! Uses LIVE sync mode - tag parsing is mode-independent, so testing one mode is sufficient.
-// === LAYER 2 TAG VARIATIONS ===
-/// Layer 2 with lowercase 'a' tag (standard NIP-01)
-#[tokio::test]
-async fn test_layer2_lowercase_a_tag() { ... }
-/// Layer 2 with uppercase 'A' tag (NIP-33 style)
-#[tokio::test]
-async fn test_layer2_uppercase_a_tag() { ... }
-/// Layer 2 with 'q' quote tag (NIP-18 style)
-#[tokio::test]
-async fn test_layer2_q_tag() { ... }
-// === LAYER 3 TAG VARIATIONS ===
-/// Layer 3 with lowercase 'e' tag (standard NIP-01)
-#[tokio::test]
-async fn test_layer3_lowercase_e_tag() { ... }
-/// Layer 3 with uppercase 'E' tag (NIP-22 comment)
-#[tokio::test]
-async fn test_layer3_uppercase_e_tag() { ... }
-/// Layer 3 with 'q' quote tag (NIP-18 style)
-#[tokio::test]
-async fn test_layer3_q_tag() { ... }
-```
-### `tests/sync/mod.rs` (UPDATED)
-```rust
-//! Sync Integration Tests
-//!
-//! Tests for ngit-grasp's proactive sync functionality, organized by sync mode:
-//!
-//! ## Sync Modes
-//!
-//! - **Historic Sync** (`historic_sync.rs`): Events exist BEFORE syncing relay connects
-//!   - Also called bootstrap/startup sync
-//!   - Tests the REQ+EOSE or negentropy-based initial sync
-//!
-//! - **Live Sync** (`live_sync.rs`): Events arrive AFTER syncing relay connects
-//!   - Also called real-time/subscription-based sync
-//!   - Tests the event forwarding via active subscriptions
-//!
-//! ## Other Test Categories
-//!
-//! - **Discovery** (`discovery.rs`): Relay discovers other relays from announcements
-//!   - Has both historic and live variants
-//!
-//! - **Tag Variations** (`tag_variations.rs`): All valid tag types work correctly
-//!   - Uses live sync (tag parsing is mode-independent)
-//!
-//! - **Metrics** (`metrics.rs`): Prometheus metrics for sync operations
-//!
-//! - **Catchup** (`catchup.rs`): Documentation only (not integration-testable)
-pub mod catchup;
-pub mod discovery;
-pub mod historic_sync;  // Renamed from bootstrap
-pub mod live_sync;
-pub mod metrics;
-pub mod tag_variations;
-```
---
-## Test Count Summary
-| File                              | Before | After  | Notes                    |
-| --------------------------------- | ------ | ------ | ------------------------ |
-| `historic_sync.rs` (bootstrap.rs) | 4      | 5      | Renamed, minor additions |
-| `live_sync.rs`                    | 3      | 3      | Simplified using helper  |
-| `discovery.rs`                    | 3      | 4      | Split into historic/live |
-| `tag_variations.rs`               | 6      | 6      | Simplified using helper  |
-| `metrics.rs`                      | 9      | 9      | Unchanged                |
-| `catchup.rs`                      | 0      | 0      | Documentation only       |
-| **Total**                         | **25** | **27** | +2 discovery tests       |
---
-## Implementation Plan
-### Context
- Two metrics tests are currently failing: `test_live_sync_event_count` and `test_multi_source_aggregate_counts`
- This may indicate implementation bugs in sync functionality
- Plan must account for distinguishing test bugs from implementation bugs
-### Phase 1: Establish Baseline
-**Goal:** Understand current state before making changes
-1. Run `cargo test --test sync` and capture full output
-2. Identify all passing vs failing tests
-3. For each failing test, investigate whether:
-   - Test logic is incorrect (test bug)
-   - Implementation is broken (impl bug)
-   - Test was never working (aspirational test)
-4. Document findings in Known Issues section below
-### Phase 2: Add Test Infrastructure
-**Goal:** Add new helpers without breaking existing tests
-1. Add `SyncTestResult` struct to sync_helpers.rs:
-   ```rust
-   pub struct SyncTestResult {
-       pub source: TestRelay,
-       pub syncing: TestRelay,
-       pub keys: Keys,
-       pub repo_coord: String,
-   }
-   ```
-2. Add `run_sync_test(historic_events, live_events)` helper function
-3. Add unit tests for the helper itself:
-   - `test_run_sync_test_historic_mode` - verify events sent before connection
-   - `test_run_sync_test_live_mode` - verify events sent after connection
-4. Run `cargo test` to confirm no regressions
-### Phase 3: Refactor Historic Sync Tests
-**Goal:** Migrate bootstrap.rs → historic_sync.rs incrementally
-1. Rename file: `bootstrap.rs` → `historic_sync.rs`
-2. Update `mod.rs` to reference new module name
-3. Refactor tests one at a time:
-   - `test_bootstrap_syncs_existing_layer2_events` → `test_historic_layer2_issue_syncs`
-   - `test_relay_replays_events_after_restart` → keep or remove (tests restart, not sync mode)
-   - `test_announcement_not_listing_relay_is_not_synced` → `test_historic_rejects_unlisted_relay`
-   - `test_history_sync_without_negentropy` → `test_historic_sync_without_negentropy`
-4. Test after each refactor: `cargo test --test sync historic_sync`
-### Phase 4: Refactor Live Sync Tests
-**Goal:** Simplify live_sync.rs using run_sync_test helper
-1. Refactor tests one at a time:
-   - `test_live_sync_layer2_events` → use `run_sync_test(&[], &[issue])`
-   - `test_live_sync_layer3_events` → use `run_sync_test(&[], &[issue, comment])`
-   - `test_live_sync_event_ordering` → may need custom setup for ordering test
-2. Test after each refactor: `cargo test --test sync live_sync`
-### Phase 5: Refactor Discovery Tests
-**Goal:** Split discovery.rs into historic and live sections
-1. Add section comment: `// === HISTORIC DISCOVERY ===`
-2. Refactor existing tests to use run_sync_test
-3. Add new tests:
-   - `test_historic_discovery_syncs_layer2`
-   - `test_live_discovery_syncs_layer2`
-4. Test after each change: `cargo test --test sync discovery`
-### Phase 6: Refactor Tag Variations Tests
-**Goal:** Simplify tag_variations.rs using run_sync_test (live mode)
-1. Add header doc comment explaining live sync mode choice
-2. Refactor each test to use `run_sync_test(&[], &[event])`
-3. Test after all changes: `cargo test --test sync tag_variations`
-### Phase 7: Final Verification and Cleanup
-1. Update `mod.rs` documentation
-2. Run full test suite: `cargo test --test sync`
-3. Compare results to Phase 1 baseline:
-   - New failures = regressions from refactor (must fix)
-   - Same failures as baseline = pre-existing issues (document)
-4. Delete `work/sync-test-refactor-options.md`
---
-## Known Issues
-_To be filled in during Phase 1_
-### Failing Tests Before Refactor
-| Test                                          | Status     | Root Cause | Action |
-| --------------------------------------------- | ---------- | ---------- | ------ |
-| `metrics::test_live_sync_event_count`         | ❌ Failing | TBD        | TBD    |
-| `metrics::test_multi_source_aggregate_counts` | ❌ Failing | TBD        | TBD    |
-### Implementation Notes
-_Any discoveries about how sync actually works vs how tests expect it to work_
---
diff --git a/docs/explanation/README.md b/docs/explanation/README.md
index cc3ec49..f477b73 100644
--- a/docs/explanation/README.md
+++ b/docs/explanation/README.md
@@ -80,6 +80,77 @@ Explanation documentation helps you **understand concepts** and design decisions
 ---
+### [Purgatory Design](purgatory-design.md)
+**In-memory holding area for events awaiting git data**
+**Topics:**
+- The "which arrives first?" problem
+- Separate storage for state vs PR events
+- Late binding for state events
+- Bidirectional waiting for PR events
+- Authorization during push
+**Read when:** You want to understand how ngit-grasp handles out-of-order event/git data arrival
+---
+### [GRASP-02 Proactive Sync](grasp-02-proactive-sync.md)
+**Relay-to-relay synchronization for repository discovery**
+**Topics:**
+- Negentropy-based event sync
+- Repository announcement discovery
+- Relay management and reconnection
+- Layer 2 filtering
+- Bootstrap and dynamic relay discovery
+**Read when:** You want to understand how ngit-grasp discovers and syncs repositories across relays
+---
+### [GRASP-02 Purgatory Git Data Fetching](grasp-02-proactive-sync-purgatory-git-data.md)
+**Proactive git data fetching from remote servers**
+**Topics:**
+- Identifier-based batching
+- Exponential backoff with fresh start
+- Domain throttling (5 concurrent, 30/min)
+- Debounced delays (3min user, 500ms sync)
+- 30-minute expiry
+- Mock-based testability
+**Read when:** You want to understand how purgatory automatically fetches missing git data
+---
+### [Unified Git Data Sync](unify-git-data-sync.md)
+**Shared processing for git push and purgatory sync paths**
+**Topics:**
+- Why unify push and sync processing
+- OID syncing to owner repos
+- Ref alignment logic
+- Event release from purgatory
+- WebSocket notification
+**Read when:** You want to understand how git data is processed consistently regardless of arrival method
+---
+### [Monitoring Overview](monitoring.md)
+**Prometheus metrics and observability**
+**Topics:**
+- Metrics philosophy
+- Connection tracking
+- Git operation metrics
+- Nostr event metrics
+- Privacy considerations
+**Read when:** You want to understand how to monitor ngit-grasp in production
+---
 ## Planned Explanation Documentation
 ### GRASP Protocol Design
diff --git a/docs/explanation/grasp-02-proactive-sync-purgatory-git-data.md b/docs/explanation/grasp-02-proactive-sync-purgatory-git-data.md
new file mode 100644
index 0000000..31c3e46
--- /dev/null
+++ b/docs/explanation/grasp-02-proactive-sync-purgatory-git-data.md
@@ -0,0 +1,675 @@
+# GRASP-02 Proactive Sync: Purgatory Git Data Fetching
+**Status**: ✅ Implemented  
+**Implementation**: [`src/purgatory/sync/`](../../src/purgatory/sync/)  
+**Related**:
+- [Purgatory Design](purgatory-design.md) - Core purgatory concepts
+- [GRASP-02 Proactive Sync](grasp-02-proactive-sync.md) - Full GRASP-02 implementation
+- [Unified Git Data Sync](unify-git-data-sync.md) - Shared processing logic
+---
+## Overview
+When Nostr events arrive before their git data, they enter **purgatory** waiting to be served. But they don't wait passively—ngit-grasp **actively hunts** for the missing git data across all git servers assoicated with the repo until it finds what it needs.
+### How It Works
+**If the data exists, we'll find it.**
+The system scours git servers listed in repository announcements and PR events, checking every **2 minutes** for **30 minutes**. If we find the data, events are released immediately. If not, they expire from purgatory after 30 minutes.
+**Smart timing based on how events arrive:**
+- **User-submitted events**: Wait **3 minutes** before hunting—we expect a `git push` to follow shortly
+- **Sync-received events**: Start hunting after just **500ms**—batch burst arrivals, then get to work
+**Playing nicely with other servers:**
+We respect remote server capacity with:
+- **Throttling**: Max 5 concurrent requests per domain, 30 requests/minute
+- **Backoff**: Start at 20 seconds, double each attempt, cap at 2 minutes
+- **Round-robin**: Fair distribution across repositories waiting for the same domain
+- **Fresh start**: New events reset retry count—recent updates often mean fresh data
+**The result**: If git data is available anywhere in the clone URL list, we'll find it within minutes. If it's not available within 30 minutes, the events expire cleanly.
+### Key Features
+✅ **Proactive hunting** - Scours git servers every 2 min (backoff), finds data automatically  
+✅ **Respectful throttling** - 5 concurrent + 30/min per domain, plays nice with other implementations  
+✅ **Smart timing** - 3min delay for user pushes, 500ms for synced events  
+✅ **30min expiry** - Auto-cleanup of events when data never arrives  
+✅ **Fully testable** - Mock-based architecture for reliable unit tests
+---
+## The Problem: Out-of-Order Arrival
+In a distributed system, git data and Nostr events can arrive in any order:
+```
+Timeline A: Event arrives first (user push expected)
+  t=0s:   State event received → enters purgatory
+  t=180s: (3min wait - expecting git push)
+  t=30s:  Git push arrives → event released ✅
+Timeline B: Git arrives first
+  t=0s:  Git push received → data available
+  t=30s: State event received → immediately served ✅
+Timeline C: Sync scenario (hunt for data)
+  t=0s:   State event received from relay X → enters purgatory
+  t=0.5s: (500ms delay to batch bursts)
+  t=0.5s: Start hunting git servers → check server1, server2, server3...
+  t=45s:  Git data found on server2 → event released ✅
+Timeline D: Data never arrives
+  t=0s:    State event received → enters purgatory
+  t=0.5s:  Start hunting → server1 (not found), server2 (timeout), server3 (not found)
+  t=20s:   Retry → server1 (not found), server2 (not found), server3 (not found)
+  t=60s:   Retry → all servers checked, no data
+  ...
+  t=1800s: 30 minutes expired → event discarded, purgatory cleaned up 🗑️
+```
+**Without proactive sync**: Events in Timeline C would wait indefinitely (or until manual git push).  
+**With proactive sync**: System automatically hunts for data across all known servers, releasing events as soon as the data is found.
+---
+## Architecture: Two-Path Sync Design
+The system uses **two independent execution paths** that work together:
+### Path 1: Main Sync Loop (Non-Throttled URLs)
+Runs every **1 second**, processes identifiers ready for sync:
+1. Find ready identifiers (where `!in_progress && next_attempt <= now`)
+2. Spawn parallel tasks for each identifier
+3. Each task tries non-throttled URLs until:
+   - ✅ All OIDs fetched (complete) → remove from queue
+   - ⏸️ Only throttled URLs remain → enqueue with throttled domains, apply backoff
+   - ❌ No URLs left (all tried/throttled) → apply backoff, retry later
+**Key insight**: Main loop doesn't wait for throttled domains. It quickly tries available servers, then hands off to domain queues for rate-limited processing.
+### Path 2: Domain Throttle Queues (Throttled URLs)
+**Trigger-based** (no polling), processes when capacity frees:
+1. Identifier enqueued with throttled domain (from main loop)
+2. When domain has capacity (slot frees or rate limit window passes):
+   - Pick next identifier (round-robin for fairness)
+   - Try one URL from that domain
+   - Mark URL as tried, release slot
+3. Trigger repeats until queue empty or capacity exhausted
+**Key insight**: Each domain independently manages its queue, ensuring we respect rate limits while maximizing throughput.
+---
+## Data Flow: From Event to Release
+```mermaid
+graph TB
+    A[Event Arrives] --> B{Git Data<br/>Available?}
+    B -->|Yes| C[Serve Immediately]
+    B -->|No| D[Enter Purgatory]
+    D --> E[Enqueue for Sync]
+    E --> F{Event Source?}
+    F -->|User Submit| G[3min Delay<br/>expect push]
+    F -->|Relay Sync| H[500ms Delay<br/>batch burst]
+    G --> I[Main Sync Loop<br/>1s interval]
+    H --> I
+    I --> J{Ready?}
+    J -->|Not Yet| I
+    J -->|Yes| K[Spawn Sync Task]
+    K --> L[Try Non-Throttled URLs]
+    L --> M{Got All OIDs?}
+    M -->|Yes| N[Process & Release]
+    M -->|Partial| O[Enqueue Throttled Domains]
+    M -->|None| P[Apply Backoff]
+    O --> Q[Domain Queue]
+    Q --> R{Has Capacity?}
+    R -->|No| Q
+    R -->|Yes| S[Try Domain URL]
+    S --> T{Got OIDs?}
+    T -->|Yes| N
+    T -->|No| U[Try Next in Queue]
+    P --> I
+    N --> V[Event Served]
+    style D fill:#fff3cd
+    style N fill:#d4edda
+    style V fill:#d1ecf1
+```
+---
+## Retry Strategy: Exponential Backoff with Fresh Start
+### Backoff Schedule
+When sync attempts don't complete (OIDs still needed), backoff increases:
+| Attempt | Delay         | Formula                |
+| ------- | ------------- | ---------------------- |
+| 1       | 20s           | `20s * 2^0`            |
+| 2       | 40s           | `20s * 2^1`            |
+| 3       | 80s           | `20s * 2^2`            |
+| 4+      | 120s (capped) | `min(20s * 2^n, 120s)` |
+**Implementation**: [`src/purgatory/sync/queue.rs:SyncQueueEntry::backoff()`](../../src/purgatory/sync/queue.rs)
+### Fresh Start on New Events
+**Critical feature**: When a new event arrives for an identifier already in the sync queue, the `attempt_count` resets to 0.
+**Why?** New events often mean:
+- A maintainer just updated the repository
+- Fresh git data might be available at new clone URLs
+- Previous failures might have been temporary
+**Example**:
+```
+t=0s:   State A arrives → queue with 3min delay, attempt_count=0
+t=180s: First sync attempt fails → backoff 20s, attempt_count=1
+t=200s: Second attempt fails → backoff 40s, attempt_count=2
+t=210s: State B arrives (same identifier) → attempt_count=0 ✨
+t=210s: Immediate retry (new event delay) → success!
+```
+---
+## Debounced Delays: Smart Timing
+### User-Submitted Events: 3 Minutes
+When a user submits an event via `EVENT` message, we expect a `git push` to follow shortly:
+```
+t=0s:   User submits state event → purgatory + 3min delay
+t=30s:  User runs `git push` → data arrives → event released ✅
+```
+**Why 3 minutes?** Gives users time to:
+- Finish composing their commit message
+- Run `git push` command
+- Handle network delays
+**Configuration**: Hardcoded in [`src/purgatory/mod.rs:DEFAULT_SYNC_DELAY`](../../src/purgatory/mod.rs)
+### Sync-Triggered Events: 500ms
+When events arrive during relay sync (e.g., negentropy catchup), they often come in bursts:
+```
+t=0s:    State A arrives → purgatory + 500ms delay
+t=0.1s:  State B arrives → purgatory + 500ms delay (same repo)
+t=0.2s:  State C arrives → purgatory + 500ms delay (same repo)
+t=0.5s:  Single sync attempt fetches data for all three ✅
+```
+**Why 500ms?** Batches burst arrivals without excessive delay.
+**Configuration**: Hardcoded in [`src/purgatory/mod.rs:IMMEDIATE_SYNC_DELAY`](../../src/purgatory/mod.rs)
+### Debouncing Mechanism
+Multiple events for the same identifier **don't create multiple sync tasks**. The `enqueue_sync` method:
+1. If identifier not in queue → create new entry with delay
+2. If identifier already queued → reset `attempt_count`, update `next_attempt` if sooner
+**Result**: Rapid event arrivals → single sync attempt after debounce window.
+**Implementation**: [`src/purgatory/mod.rs:Purgatory::enqueue_sync()`](../../src/purgatory/mod.rs)
+---
+## Domain Throttling: Respectful Rate Limiting
+### Why Throttle?
+Git servers have finite resources. Without throttling:
+- ❌ We could overwhelm small servers with concurrent requests
+- ❌ Servers might rate-limit or ban us
+- ❌ Other clients sharing the server suffer degraded performance
+With throttling:
+- ✅ Respect server capacity (5 concurrent max per domain)
+- ✅ Stay under rate limits (30 requests/min per domain)
+- ✅ Fair access for all clients
+### Two-Level Limits
+Each domain has **two independent limits**:
+#### 1. Concurrent Request Limit (Default: 5)
+Maximum in-flight requests to a domain at any moment.
+**Example**:
+```
+Domain: github.com
+In-flight: [fetch-1, fetch-2, fetch-3, fetch-4, fetch-5]
+Status: AT CAPACITY (throttled)
+fetch-3 completes → in-flight: 4
+Status: HAS CAPACITY (process next queued identifier)
+```
+#### 2. Rate Limit (Default: 30/min)
+Maximum requests in any 60-second sliding window.
+**Example**:
+```
+t=0s:   Request 1 → request_times: [0s]
+t=1s:   Request 2 → request_times: [0s, 1s]
+...
+t=30s:  Request 30 → request_times: [0s, 1s, ..., 30s]
+t=31s:  Request 31? → THROTTLED (30 requests in last 60s)
+t=61s:  Request at t=0s aged out → request_times: [1s, ..., 30s]
+t=61s:  Request 31 → ALLOWED (only 29 in last 60s)
+```
+**Implementation**: [`src/purgatory/sync/throttle.rs:DomainThrottle::has_capacity()`](../../src/purgatory/sync/throttle.rs)
+### Round-Robin Fairness
+When multiple identifiers are queued for a throttled domain, we use **round-robin** to ensure fairness:
+```
+Queue: [repo-A, repo-B, repo-C]
+Round-robin index: 0
+Attempt 1: Try repo-A (index=0) → fetch → index=1
+Attempt 2: Try repo-B (index=1) → fetch → index=2
+Attempt 3: Try repo-C (index=2) → fetch → index=0
+Attempt 4: Try repo-A (index=0) → ...
+```
+**Why round-robin?** Prevents head-of-line blocking. Without it, repo-A might consume all slots while repo-B and repo-C wait indefinitely.
+**Implementation**: [`src/purgatory/sync/throttle.rs:DomainThrottle::next_ready_identifier()`](../../src/purgatory/sync/throttle.rs)
+### Trigger-Based Processing (Not Polling)
+Domain queues **don't poll** for capacity. Instead, processing is triggered by two events:
+1. **`complete_request()`** - A request finishes, slot frees
+2. **`enqueue_identifier()`** - New identifier added to queue
+Both methods check `has_capacity()` and trigger `try_process_next()` if true.
+**Why trigger-based?**
+- ✅ Lower CPU usage (no busy-waiting)
+- ✅ Instant response when capacity frees
+- ✅ Simpler reasoning (event-driven)
+**Implementation**: [`src/purgatory/sync/throttle.rs:ThrottleManager`](../../src/purgatory/sync/throttle.rs)
+---
+## 30-Minute Purgatory Expiry
+Purgatory entries **automatically expire** after 30 minutes to prevent unbounded memory growth.
+### Why 30 Minutes?
+From the [GRASP-01 spec](https://github.com/DanConwayDev/grasp/blob/main/01.md#purgatory):
+> Events should be kept in purgatory and otherwise discarded after 30 minutes.
+This balances:
+- ⏰ **Long enough** for typical sync scenarios (git data usually arrives within minutes)
+- 🧹 **Short enough** to prevent memory leaks from abandoned events
+- 🔄 **Recoverable** events are still on other relays and can be re-submitted
+### Implementation
+Each purgatory entry tracks:
+- `created_at: Instant` - When added to purgatory
+- `expires_at: Instant` - When to discard (created_at + 30min)
+The main sync loop checks expiry before processing:
+```rust
+if !self.has_pending_events(&identifier) {
+    // No events remain (expired or released) → remove from sync queue
+    self.sync_queue.remove(&identifier);
+}
+```
+**Note**: Expiry is checked implicitly via `has_pending_events()`. If all events for an identifier have expired, the identifier is removed from the sync queue.
+**Implementation**: [`src/purgatory/mod.rs:DEFAULT_EXPIRY`](../../src/purgatory/mod.rs)
+---
+## Testability: Mock-Based Architecture
+A key design goal was **100% unit test coverage** without requiring real git servers or databases.
+### SyncContext Trait
+All external dependencies are abstracted behind the `SyncContext` trait:
+```rust
+#[async_trait]
+pub trait SyncContext: Send + Sync {
+    async fn fetch_repository_data(&self, identifier: &str) -> Result<RepositoryData>;
+    fn collect_needed_oids(&self, identifier: &str) -> HashSet<String>;
+    async fn oid_exists(&self, repo_path: &Path, oid: &str) -> bool;
+    async fn fetch_oids(&self, repo_path: &Path, url: &str, oids: &[String]) -> Result<Vec<String>>;
+    async fn process_newly_available_git_data(&self, ...) -> Result<ProcessResult>;
+    fn has_pending_events(&self, identifier: &str) -> bool;
+    fn find_target_repo(&self, data: &RepositoryData) -> Option<PathBuf>;
+    fn our_domain(&self) -> Option<&str>;
+}
+```
+**Two Implementations**:
+1. **`RealSyncContext`** - Production implementation connecting to real systems
+2. **`MockSyncContext`** - Test implementation with configurable behavior
+### MockSyncContext Features
+The mock supports builder-pattern configuration:
+```rust
+let mock = MockSyncContext::new()
+    .with_repository_data("test-repo", RepositoryData {
+        announcements: vec![...],
+        clone_urls: vec!["https://server1.com/repo.git".to_string()],
+    })
+    .with_needed_oids("test-repo", hashset!["abc123", "def456"])
+    .with_fetch_result("https://server1.com/repo.git", Ok(vec!["abc123"]))
+    .with_fetch_result("https://server2.com/repo.git", Ok(vec!["def456"]));
+```
+**Test Example** (from [`src/purgatory/sync/functions.rs`](../../src/purgatory/sync/functions.rs)):
+```rust
+#[tokio::test]
+async fn test_sync_identifier_partial_success() {
+    let mock = MockSyncContext::new()
+        .with_repository_data("repo", RepositoryData {
+            clone_urls: vec![
+                "https://server1.com/repo.git".to_string(),
+                "https://server2.com/repo.git".to_string(),
+            ],
+            ..Default::default()
+        })
+        .with_needed_oids("repo", hashset!["oid1", "oid2"])
+        .with_fetch_result("https://server1.com/repo.git", Ok(vec!["oid1"]))
+        .with_fetch_result("https://server2.com/repo.git", Ok(vec!["oid2"]));
+    let throttle = Arc::new(ThrottleManager::new(5, 30));
+    let complete = sync_identifier(&mock, "repo", &throttle).await;
+    assert!(complete); // Both OIDs fetched
+}
+```
+**Why this matters**:
+- ✅ Tests run **instantly** (no network I/O)
+- ✅ Tests are **deterministic** (no flaky failures)
+- ✅ Tests cover **edge cases** easily (network errors, partial success, etc.)
+- ✅ Tests are **isolated** (no shared state between tests)
+**Implementation**: [`src/purgatory/sync/context.rs:MockSyncContext`](../../src/purgatory/sync/context.rs)
+---
+## Configuration
+Purgatory sync behavior is configurable via CLI flags or environment variables:
+| Setting                 | CLI Flag | Environment Variable | Default | Description                                          |
+| ----------------------- | -------- | -------------------- | ------- | ---------------------------------------------------- |
+| Domain concurrent limit | (future) | (future)             | `5`     | Max concurrent requests per domain                   |
+| Domain rate limit       | (future) | (future)             | `30`    | Max requests per minute per domain                   |
+| Sync loop interval      | N/A      | N/A                  | `1s`    | How often to check for ready identifiers (hardcoded) |
+| Default sync delay      | N/A      | N/A                  | `180s`  | Delay for user-submitted events (hardcoded)          |
+| Immediate sync delay    | N/A      | N/A                  | `500ms` | Delay for sync-triggered events (hardcoded)          |
+| Purgatory expiry        | N/A      | N/A                  | `30min` | How long events wait before expiring (hardcoded)     |
+**Note**: Currently, throttle limits and delays are hardcoded constants. Future work may expose these as configuration options if needed.
+---
+## Key Design Decisions
+### 1. Identifier-Based, Not Event-Based
+**Decision**: Sync by repository identifier, not individual events.
+**Rationale**: Multiple events for the same repository should trigger a single fetch operation, not N separate fetches.
+**Impact**: Batches events efficiently, reduces server load.
+### 2. Two Separate `tried_urls` Tracking
+**Decision**: Main sync loop and domain queues track tried URLs independently.
+**Main sync**: Local `HashSet<String>` for current attempt (all domains)  
+**Domain queue**: Per-identifier `HashSet<String>` for this domain only
+**Rationale**:
+- Main sync skips throttled domains entirely (doesn't need their tried URLs)
+- Domain queue only cares about URLs from its own domain
+- No coordination needed → simpler code
+**Impact**: Clean separation of concerns, easier to reason about.
+### 3. Trigger-Based Domain Processing
+**Decision**: Domain queues process on triggers (capacity freed, new enqueue), not polling.
+**Rationale**:
+- Polling wastes CPU cycles checking capacity every interval
+- Triggers provide instant response when capacity frees
+- Event-driven design is easier to test and debug
+**Impact**: Lower CPU usage, faster response times.
+### 4. Fresh Start on New Events
+**Decision**: Reset `attempt_count` to 0 when new events arrive for an identifier.
+**Rationale**:
+- New events often mean fresh git data is available
+- Previous failures might have been temporary
+- Gives repositories a "second chance" without waiting for full backoff
+**Impact**: Faster recovery from transient failures, better UX.
+### 5. OID Copying in `process_newly_available_git_data`
+**Decision**: Copy OIDs and release events **per successful fetch**, not at end of sync.
+**Rationale**:
+- Events can be released as soon as their specific OIDs are available
+- Partial success scenarios work correctly (some events release, others stay)
+- Handles multiple state events for same identifier independently
+**Impact**: Events release faster, better handling of partial success.
+---
+## Observability
+### Logging
+Sync operations produce structured logs at different levels:
+**INFO**: Major events
+```
+Starting purgatory sync loop (interval: 1s)
+Sync complete - removed from sync queue (identifier=test-repo, complete=true)
+```
+**DEBUG**: Detailed progress
+```
+Added new sync queue entry (identifier=test-repo, delay_secs=180)
+Starting sync task for identifier (identifier=test-repo)
+Sync incomplete - applying backoff (identifier=test-repo, attempt_count=2, next_backoff_secs=40)
+```
+**WARN**: Errors and failures
+```
+Failed to fetch OIDs (url=https://server.com/repo.git, error=connection timeout)
+```
+### Metrics (Future)
+Planned Prometheus metrics for observability:
+- `purgatory_sync_queue_size` - Number of identifiers pending sync
+- `purgatory_sync_attempts_total{identifier}` - Total sync attempts per identifier
+- `purgatory_sync_oids_fetched_total{identifier}` - OIDs successfully fetched
+- `purgatory_domain_in_flight{domain}` - Current in-flight requests per domain
+- `purgatory_domain_requests_total{domain}` - Total requests per domain
+---
+## Testing Strategy
+### Unit Tests
+Core sync functions have comprehensive unit tests using `MockSyncContext`:
+**`sync_identifier_next_url`** (3 tests):
+- Skips throttled domains
+- Skips tried URLs
+- Returns None when all URLs exhausted
+**`sync_identifier_from_url`** (2 tests):
+- Successful fetch triggers processing
+- Failed fetch doesn't trigger processing
+**`sync_identifier`** (3 tests):
+- Tries multiple URLs until complete
+- Enqueues throttled domains when incomplete
+- Handles partial success correctly
+**`SyncQueueEntry`** (3 tests):
+- Backoff calculation correct
+- Fresh start on new events
+- Ready state logic correct
+**`DomainThrottle`** (4 tests):
+- Concurrent limit enforced
+- Rate limit enforced
+- Round-robin fairness
+- Queue management correct
+**Total**: 15+ unit tests covering all core logic
+**Location**: [`src/purgatory/sync/`](../../src/purgatory/sync/) (various `#[cfg(test)]` modules)
+### Integration Tests
+End-to-end tests verify sync behavior with real relay instances:
+**Planned tests**:
+- State event syncs from remote server
+- PR event syncs from remote server
+- Partial OID aggregation across multiple servers
+- Throttling prevents overwhelming servers
+- Backoff retry after failures
+**Location**: [`tests/purgatory_sync.rs`](../../tests/purgatory_sync.rs) (planned)
+---
+## Future Enhancements
+### 1. Configurable Throttle Limits
+**Current**: Hardcoded to 5 concurrent, 30/min per domain  
+**Future**: CLI flags `--sync-domain-concurrent` and `--sync-domain-rate-limit`
+**Use case**: Operators might want stricter limits for public servers or looser limits for trusted servers.
+### 2. Per-Domain Throttle Configuration
+**Current**: Same limits for all domains  
+**Future**: Domain-specific overrides (e.g., `github.com:10,60` for higher limits)
+**Use case**: Popular forges like GitHub/GitLab can handle more load than small personal servers.
+### 3. Prometheus Metrics
+**Current**: Structured logging only  
+**Future**: Export metrics for monitoring dashboards
+**Use case**: Operators want visibility into sync performance, throttle effectiveness, success rates.
+### 4. Negentropy Integration
+**Current**: Sync triggered by event arrival  
+**Future**: Proactive sync discovers missing events via negentropy
+**Use case**: Catch up with repositories after downtime without waiting for event re-submission.
+---
+## Related Documentation
+- **[Purgatory Design](purgatory-design.md)** - Core purgatory concepts and event flows
+- **[GRASP-02 Proactive Sync](grasp-02-proactive-sync.md)** - Full GRASP-02 implementation (relay sync)
+- **[Unified Git Data Sync](unify-git-data-sync.md)** - Shared processing for push and sync paths
+- **[Architecture Overview](architecture.md)** - System-wide architecture
+---
+## Summary
+The purgatory sync system is a sophisticated, production-ready implementation that:
+✅ **Batches intelligently** - Groups events by identifier for efficient fetching  
+✅ **Retries smartly** - Exponential backoff with fresh start on new events  
+✅ **Throttles respectfully** - 5 concurrent + 30/min per domain, round-robin fairness  
+✅ **Times strategically** - 3min for user events, 500ms for synced events  
+✅ **Expires responsibly** - 30min auto-cleanup prevents memory leaks  
+✅ **Tests thoroughly** - Mock-based architecture enables comprehensive unit tests
+This design ensures ngit-grasp can serve repositories reliably even when git data and Nostr events arrive out-of-order or from different sources, while respecting remote server capacity and providing excellent observability.
diff --git a/docs/explanation/grasp-02-proactive-sync.md b/docs/explanation/grasp-02-proactive-sync.md
index f13050e..461bde7 100644
--- a/docs/explanation/grasp-02-proactive-sync.md
+++ b/docs/explanation/grasp-02-proactive-sync.md
@@ -4,6 +4,8 @@
 Proactively Sync Nostr Events from other relays listed in accepted repository announcements.
+**Note**: This document covers **relay-to-relay event sync**. For automatic git data fetching when events arrive without their data, see [GRASP-02 Purgatory Git Data Fetching](grasp-02-proactive-sync-purgatory-git-data.md).
 Features:
 - Fetches all repository announcements from connected relays to discover new repos listing our service
@@ -13,6 +15,7 @@ Features:
 - Plays nicely with other relays - connection backoff and rate-limiting detection with cooldown
 - Does a full reconciliation daily
 - Prometheus metrics
+- **Triggers purgatory git data sync**: When events arrive via sync, they're enqueued for immediate git data fetching (500ms delay to batch bursts)
 Key Architectural Points:
diff --git a/docs/explanation/inline-authorization.md b/docs/explanation/inline-authorization.md
index 4538602..a71a217 100644
--- a/docs/explanation/inline-authorization.md
+++ b/docs/explanation/inline-authorization.md
@@ -37,16 +37,18 @@ Client              Server
 ```
 **Pros:**
 - Standard Git mechanism
 - Language-agnostic (hook can be any executable)
 - Well-documented
 **Cons:**
 - Hook output goes to stderr (client sees as `remote:` messages)
 - Hard to provide structured error messages
 - Requires hook installation and management
 - Difficult to test (needs Git repository setup)
- Hook runs *after* Git has started processing
+- Hook runs _after_ Git has started processing
 ---
@@ -60,7 +62,7 @@ Client              Server (ngit-grasp)
  |--- git push ----->|--- HTTP handler receives request
  |                   |
  |                   |--- Parse ref updates from request
-  |                   |--- Query Nostr relay for state
+  |                   |--- Query database + purgatory for state
  |                   |--- Validate push against state
  |                   |
  |                   |--- If invalid: return HTTP error
@@ -71,13 +73,16 @@ Client              Server (ngit-grasp)
 ```
 **Pros:**
 - Full control over error messages (HTTP response)
 - Can skip spawning Git entirely for invalid pushes
 - Easier testing (pure Rust, no Git setup needed)
 - Shared state between Git and Nostr components
 - Better performance (early rejection)
+- Can check both database and purgatory for authorization
 **Cons:**
 - Requires parsing Git protocol ourselves
 - Less standard than hooks
 - Tighter coupling to Git HTTP protocol
@@ -86,9 +91,41 @@ Client              Server (ngit-grasp)
 ## Why Inline Authorization Is Better for GRASP
-### 1. Better Error Messages
+### 1. Purgatory Integration
+**Critical advantage:** Inline authorization allows checking **both database and purgatory** during authorization:
+```rust
+// From src/git/authorization.rs
+pub async fn authorize_push(
+    database: &SharedDatabase,
+    identifier: &str,
+    owner_pubkey: &str,
+    request_body: &Bytes,
+    purgatory: &Arc<Purgatory>,  // Can check purgatory!
+    repo_path: &std::path::Path,
+) -> anyhow::Result<AuthorizationResult>
+```
+**Why this matters:** State events go to purgatory when git data doesn't exist yet. Without inline authorization checking purgatory, we'd have a deadlock:
+1. State event arrives → No git data → Goes to **purgatory** (not database)
+2. Git push arrives → Hook checks **database only** → No state found → **REJECTED** ❌
+With inline authorization:
+1. State event arrives → No git data → Goes to purgatory
+2. Git push arrives → Checks **database + purgatory** → State found → **AUTHORIZED** ✅
+3. After push succeeds → Save event to database → Remove from purgatory
+See [`src/git/authorization.rs:342-400`](../../src/git/authorization.rs) for implementation.
+otherwise we'd need another way of storing purgatory events.
+### 2. Better Error Messages
 **With hooks:**
 ```
 $ git push
 remote: error: Push rejected - not authorized for ref refs/heads/main
@@ -98,39 +135,37 @@ To https://gitnostr.com/alice/myrepo.git
 ```
 **With inline authorization:**
 ```
 $ git push
 error: RPC failed; HTTP 403 Forbidden
-error: {
+error: Push rejected: No state event found in purgatory from authorized publishers
-  "error": "unauthorized",
-  "ref": "refs/heads/main",
-  "required_state": "event_id_abc123",
-  "your_pubkey": "npub1alice...",
-  "docs": "https://docs.gitnostr.com/errors/unauthorized"
-}
 ```
-The inline approach can return **structured JSON** with actionable information.
+The inline approach provides clear, actionable error messages directly in the HTTP response.
-### 2. Performance Benefits
+### 3. Performance Benefits
 **With hooks:**
 - Git process spawns
 - Git starts receiving pack data
 - Hook runs (might query Nostr relay)
 - If rejected, Git throws away received data
 **With inline authorization:**
- Parse ref updates from HTTP request
- Validate against Nostr state (cached)
+- Parse ref updates from HTTP request (pkt-line format)
- If rejected, return HTTP 403 immediately
+- Validate against database + purgatory state
+- If rejected, return HTTP error immediately
 - Never spawn Git for invalid pushes
-**Result:** Faster rejection, less resource usage.
+**Result:** Faster rejection, less resource usage, no wasted pack data transfer.
-### 3. Easier Testing
+### 4. Easier Testing
 **With hooks:**
 ```bash
 # Test setup
 mkdir -p /tmp/test-repo
@@ -147,6 +182,7 @@ rm -rf /tmp/test-repo
 ```
 **With inline authorization:**
 ```rust
 #[tokio::test]
 async fn test_unauthorized_push() {
@@ -161,43 +197,55 @@ async fn test_unauthorized_push() {
 See [`tests/push_authorization.rs`](tests/push_authorization.rs) for actual test examples.
-### 4. Shared State and Types
+### 5. Shared State and Types
 **With hooks:**
 - Hook is separate process
 - Must query Nostr relay over WebSocket
 - Can't share in-memory cache
+- Can't access purgatory
 - Separate error types
 **With inline authorization:**
 ```rust
 // From src/git/handlers.rs
 pub async fn handle_receive_pack(
    repo_path: PathBuf,
    body: Bytes,
-    database: SharedDatabase,  // Shared with Nostr relay!
+    database: Option<SharedDatabase>,  // Shared with Nostr relay!
+    purgatory: Option<Arc<Purgatory>>, // Shared purgatory access!
    npub: &str,
    identifier: &str,
 ) -> Result<Response<Full<Bytes>>, GitError> {
-    // Direct database access for authorization
+    // Direct database + purgatory access for authorization
-    let auth = get_authorization_for_owner(&database, pubkey, identifier).await?;
+    let auth = authorize_push(
+        &database,
+        identifier,
+        owner_pubkey,
+        &body,
+        &purgatory,  // Can check purgatory!
+        &repo_path
+    ).await?;
    // ...
 }
 ```
-**Result:** Better performance, type safety, simpler architecture.
+**Result:** Better performance, type safety, simpler architecture, purgatory integration.
-### 5. Simpler Deployment
+### 6. Simpler Deployment
 **With hooks (ngit-relay):**
 ```
 Docker container:
  - nginx (HTTP frontend)
  - git-http-backend (C binary)
-  - pre-receive hook (Go binary) 
+  - pre-receive hook (Go binary)
  - Khatru relay (Go binary)
  - supervisord (process manager)
-  
 Setup steps:
  1. Install all components
  2. Configure nginx
@@ -207,13 +255,14 @@ Setup steps:
 ```
 **With inline authorization (ngit-grasp):**
 ```
 Single Rust binary:
  - HTTP server (Hyper)
  - Git protocol handler
  - Nostr relay (nostr-relay-builder)
  - Authorization logic
-  
 Setup steps:
  1. Run binary
  2. Configure environment variables
@@ -227,66 +276,95 @@ Setup steps:
 ### How We Parse Ref Updates
-The Git HTTP protocol sends ref updates in the request body:
+The Git HTTP protocol sends ref updates in pkt-line format:
 ```
 POST /alice/myrepo.git/git-receive-pack HTTP/1.1
 Content-Type: application/x-git-receive-pack-request
-0000000000000000000000000000000000000000 abc123... refs/heads/main\0 report-status
+00a5 0000...0000 abc123...def456 refs/heads/main\0 report-status\n
+0000
+PACK...
 ```
-We parse this **before** spawning Git. See [`src/git/authorization.rs`](src/git/authorization.rs) for the implementation:
+We parse this **before** spawning Git. See [`src/git/authorization.rs:695-778`](../../src/git/authorization.rs) for the implementation:
 ```rust
-/// Parse ref updates from git-receive-pack request body
+/// Parse the refs being updated from a Git pack
-pub fn parse_pushed_refs(body: &[u8]) -> Result<Vec<PushedRef>, AuthorizationError> {
+///
-    // Parse pkt-line format
+/// The receive-pack protocol sends ref updates in pkt-line format:
-    // Extract ref updates
+/// - 4-byte hex length prefix (e.g., "00a5")
-    // Return structured data
+/// - Payload: `<old-oid> <new-oid> <ref-name>\0<capabilities>\n`
+/// - Flush packet "0000" terminates the list
+pub fn parse_pushed_refs(data: &[u8]) -> Vec<(String, String, String)> {
+    // Handles both pkt-line format (real Git clients)
+    // and simple text format (for unit tests)
 }
 ```
 ### How We Validate
-Validation checks (from [`src/git/authorization.rs`](src/git/authorization.rs)):
+The authorization flow (from [`src/git/authorization.rs:51-162`](../../src/git/authorization.rs)):
-1. Does pusher's pubkey have write access?
-2. Are they listed as a maintainer in the latest state event?
-3. Do the refs match the state event?
 ```rust
-/// Validate that pushed refs match the authorized state
+pub async fn authorize_push(
-pub fn validate_push_refs(
+    database: &SharedDatabase,
-    pushed_refs: &[PushedRef],
+    identifier: &str,
-    state: &RepositoryState,
+    owner_pubkey: &str,
-) -> Result<(), AuthorizationError> {
+    request_body: &Bytes,
-    for pushed_ref in pushed_refs {
+    purgatory: &Arc<Purgatory>,
-        if pushed_ref.ref_name.starts_with("refs/heads/") {
+    repo_path: &std::path::Path,
-            // Validate branch against state
+) -> anyhow::Result<AuthorizationResult> {
-        } else if pushed_ref.ref_name.starts_with("refs/tags/") {
+    // 1. Parse refs from push request
-            // Validate tag against state
+    let pushed_refs = parse_pushed_refs(request_body);
-        } else if pushed_ref.ref_name.starts_with("refs/nostr/") {
-            // Allow refs/nostr/<event-id> for PRs
+    // 2. Separate refs/nostr/ refs from state refs
-        }
+    let (nostr_refs, state_refs) = partition_refs(&pushed_refs);
-    }
-    Ok(())
+    // 3. Handle refs/nostr/ refs (PR events)
+    //    - Validate event ID format
+    //    - Check purgatory for PR event
+    //    - Create placeholder if git-data-first scenario
+    // 4. Handle normal refs (state events)
+    //    - Check database + purgatory for state events
+    //    - Collect authorized maintainers
+    //    - Find latest authorized state
+    //    - Validate refs match state
+    // 5. Return authorization result with purgatory events
 }
 ```
+**Key validation checks:**
+1. **For state refs** (`refs/heads/*`, `refs/tags/*`):
+   - Query database for announcements → collect authorized maintainers
+   - Check **purgatory** for matching state events (critical for purgatory flow!)
+   - Filter to events from authorized maintainers
+   - Find latest state event
+   - Validate pushed refs match state event refs
+2. **For PR refs** (`refs/nostr/<event-id>`):
+   - Validate event ID format
+   - Check purgatory for PR event with matching commit
+   - If no event found, create placeholder (git-data-first scenario)
+   - Collect PR events from purgatory for post-push processing
 ---
 ## Comparison with Reference Implementation
-| Aspect | ngit-relay (hooks) | ngit-grasp (inline) |
+| Aspect             | ngit-relay (hooks)                       | ngit-grasp (inline)    |
-|--------|-------------------|---------------------|
+| ------------------ | ---------------------------------------- | ---------------------- |
-| **Components** | nginx + git-http-backend + hook + Khatru | Single Rust binary |
+| **Components**     | nginx + git-http-backend + hook + Khatru | Single Rust binary     |
-| **Validation** | Pre-receive hook (separate process) | Inline HTTP handler |
+| **Validation**     | Pre-receive hook (separate process)      | Inline HTTP handler    |
-| **Error messages** | Hook stderr → `remote:` | HTTP response JSON |
+| **Error messages** | Hook stderr → `remote:`                  | HTTP response JSON     |
-| **Performance** | Spawns Git first | Validates first |
+| **Performance**    | Spawns Git first                         | Validates first        |
-| **Testing** | Shell scripts + Go tests | Pure Rust tests |
+| **Testing**        | Shell scripts + Go tests                 | Pure Rust tests        |
-| **Deployment** | Docker + supervisord | Single binary |
+| **Deployment**     | Docker + supervisord                     | Single binary          |
-| **State sharing** | WebSocket query | Direct database access |
+| **State sharing**  | WebSocket query                          | Direct database access |
 Both are GRASP-compliant, but inline authorization is simpler and more efficient.
@@ -295,24 +373,30 @@ Both are GRASP-compliant, but inline authorization is simpler and more efficient
 ## Trade-offs and Limitations
 ### What We Gain
+- ✅ **Purgatory integration** - Can check database + purgatory during authorization
+- ✅ **Prevents deadlock** - State events in purgatory can authorize pushes
 - ✅ Better error messages
- ✅ Better performance
+- ✅ Better performance (early rejection)
- ✅ Easier testing
+- ✅ Easier testing (pure Rust)
- ✅ Simpler deployment
+- ✅ Simpler deployment (single binary)
- ✅ Tighter integration
+- ✅ Tighter integration (shared state)
 ### What We Lose
 - ❌ Non-standard approach (not using Git's hook system)
 - ❌ Tighter coupling to Git HTTP protocol
- ❌ Must parse protocol ourselves
+- ❌ Must parse pkt-line protocol ourselves
 ### Is It Worth It?
-**Yes**, because:
+**Absolutely**, because:
-1. We handle protocol parsing in [`src/git/protocol.rs`](src/git/protocol.rs)
-2. GRASP is already non-standard (Nostr authorization)
+1. **Purgatory integration is essential** - Without it, we'd have a deadlock where state events in purgatory can't authorize pushes
-3. Benefits far outweigh the coupling cost
+2. Protocol parsing is isolated in [`src/git/authorization.rs`](../../src/git/authorization.rs)
-4. We can still add hook support later if needed
+3. GRASP is already non-standard (Nostr authorization)
+4. Benefits far outweigh the coupling cost
+5. We can still add hook support later if needed (but purgatory checking would still need inline access)
 ---
@@ -320,14 +404,15 @@ Both are GRASP-compliant, but inline authorization is simpler and more efficient
 Key files in the ngit-grasp implementation:
-| Component | Location |
+| Component               | Location                                                                  |
-|-----------|----------|
+| ----------------------- | ------------------------------------------------------------------------- |
-| HTTP routing | [`src/http/mod.rs`](src/http/mod.rs) |
+| HTTP routing            | [`src/http/mod.rs`](../../src/http/mod.rs)                                |
-| Git handlers | [`src/git/handlers.rs`](src/git/handlers.rs) |
+| Git handlers            | [`src/git/handlers.rs`](../../src/git/handlers.rs)                        |
-| Push authorization | [`src/git/authorization.rs`](src/git/authorization.rs) |
+| Push authorization      | [`src/git/authorization.rs`](../../src/git/authorization.rs)              |
-| Git protocol parsing | [`src/git/protocol.rs`](src/git/protocol.rs) |
+| Pkt-line parsing        | [`src/git/authorization.rs:695-778`](../../src/git/authorization.rs)      |
-| Subprocess management | [`src/git/subprocess.rs`](src/git/subprocess.rs) |
+| Subprocess management   | [`src/git/subprocess.rs`](../../src/git/subprocess.rs)                    |
-| Event acceptance policy | [`src/nostr/builder.rs:51`](src/nostr/builder.rs:51) - `Nip34WritePolicy` |
+| Purgatory integration   | [`src/purgatory/mod.rs`](../../src/purgatory/mod.rs)                      |
+| Event acceptance policy | [`src/nostr/builder.rs`](../../src/nostr/builder.rs) - `Nip34WritePolicy` |
 ---
@@ -345,6 +430,7 @@ pub struct GitConfig {
 ```
 This would allow:
 - Migration path for hook-based systems
 - Extra validation for paranoid deployments
 - Compatibility with other Git tools
@@ -352,6 +438,7 @@ This would allow:
 ### If Git Protocol Changes
 The protocol parsing is isolated in [`src/git/protocol.rs`](src/git/protocol.rs). If the Git protocol changes:
 - Update the protocol module
 - Tests will catch any breakage
@@ -361,18 +448,21 @@ The protocol parsing is isolated in [`src/git/protocol.rs`](src/git/protocol.rs)
 **Inline authorization is the right choice for ngit-grasp** because:
-1. It provides better error messages for users
+1. **Purgatory integration** - Without inline authorization, state events in purgatory couldn't authorize pushes, creating a deadlock
-2. It's more performant (early rejection)
+2. **Better error messages** - Direct HTTP responses with clear rejection reasons
-3. It's easier to test (pure Rust)
+3. **Better performance** - Early rejection before spawning Git
-4. It's simpler to deploy (single binary)
+4. **Easier testing** - Pure Rust unit tests, no Git setup needed
-5. It enables better integration (shared database)
+5. **Simpler deployment** - Single binary with shared state
+6. **Shared database + purgatory** - Both authorization sources accessible during validation
 The trade-off (coupling to Git HTTP protocol) is acceptable because:
- The protocol is stable and well-specified
- Protocol handling is isolated in one module
+- The pkt-line protocol is stable and well-specified
+- Protocol parsing is isolated in [`src/git/authorization.rs`](../../src/git/authorization.rs)
+- Purgatory integration requires inline access anyway
 - Benefits far outweigh the cost
-This decision aligns with our goal of creating a **developer-friendly, production-ready GRASP implementation**.
+This decision aligns with our goal of creating a **developer-friendly, production-ready GRASP implementation** that properly handles the event-git-data ordering problem via purgatory.
 ---
@@ -386,4 +476,4 @@ This decision aligns with our goal of creating a **developer-friendly, productio
 ---
-*Part of the [ngit-grasp explanation docs](./)*
-\ No newline at end of file
+_Part of the [ngit-grasp explanation docs](./)_
diff --git a/docs/explanation/purgatory-design.md b/docs/explanation/purgatory-design.md
index 5ee4e06..b984745 100644
--- a/docs/explanation/purgatory-design.md
+++ b/docs/explanation/purgatory-design.md
@@ -1,1013 +1,795 @@
-# Purgatory Implementation Design
+# Purgatory: In-Memory Holding Area for Events Awaiting Git Data
-**Status**: ✅ Implemented (2025-12-23)
+**Status**: ✅ Implemented  
-**Implementation**: Phases 1-7 complete
+**Implementation**: [`src/purgatory/`](../../src/purgatory/)  
-**Source Code**: [`src/purgatory/`](../../src/purgatory/)
 **Related**: [`docs/explanation/architecture.md`](architecture.md) - System architecture overview
+---
 ## Overview
-Purgatory is an in-memory holding area for nostr events that depend on git data that hasn't arrived yet, **and** for git data that arrived before its corresponding nostr event. Events/placeholders are held until the other half arrives, at which point they are processed and saved to the database.
+Purgatory is an in-memory holding area that solves the **"which arrives first?"** problem in GRASP. Either nostr events or git pushes can arrive in any order:
+- **Event first**: Event waits in purgatory until git data arrives
+- **Git first**: Placeholder waits in purgatory until event arrives
+When both halves arrive, they are processed together and saved to the database.
-**Spec Reference**: [GRASP-01 Purgatory Section](../grasp/01.md:20-22)
+**Spec Reference**: [GRASP-01 Purgatory Section](https://github.com/DanConwayDev/grasp/blob/main/01.md#purgatory)
 > Accepted repo state announcements, PRs and PR Updates SHOULD be accepted with message "purgatory: won't be served until git data arrives" and kept in purgatory (not served) until the related git data arrives and otherwise discarded after 30 minutes.
+---
 ## Key Design Principles
-### 1. Separate Storage for State vs PR Events
+### 1. In-Memory Only
+Purgatory data is **not persisted** to disk. On restart, all purgatory entries are lost. This is acceptable because:
+- Events are still on other relays (can be re-submitted)
+- Git data can be re-pushed
+- 30-minute expiry means data is transient anyway
-State events (kind 30618) and PR events (kind 1617/1618) have fundamentally different matching and authorization patterns. They are stored in **separate purgatory stores** with different indices:
+### 2. Separate Storage for State vs PR Events
- **State Events**: Indexed by `identifier` (d tag), matched via ref comparison
+State events (kind 30618) and PR events (kind 1617/1618) have fundamentally different matching patterns:
- **PR Events**: Indexed by `event_id`, matched directly via `refs/nostr/<event-id>`
-### 2. Late Binding of Refs (State Events)
+| Event Type | Index | Matching Strategy |
+|------------|-------|-------------------|
+| **State Events** | `identifier` (d tag) | Compare refs at push time |
+| **PR Events** | `event_id` (hex string) | Direct match via `refs/nostr/<event-id>` |
-**Do NOT extract refs at event arrival time.** Extract and match refs at git push time.
+They use **separate DashMap stores** for efficient concurrent access.
-**Why?** Multiple state events might be in purgatory with different target states. An older state event's git data might arrive after a newer one is received. By waiting until push time, we:
+### 3. Late Binding for State Events
- Compare the pushed refs against each purgatory state event's expected state
+**Critical:** Do NOT extract refs from state events at arrival time. Extract and match refs **at git push time**.
+**Why?** Multiple state events might be in purgatory with different target states. An older state event's git data might arrive after a newer one is received. By waiting until push time:
+- Compare pushed refs against each purgatory state event's expected state
 - Handle out-of-order git data arrival correctly
 - Only release events when their specific target state is achieved
-### 3. Bidirectional Waiting (PR Events)
+See [`src/purgatory/helpers.rs:can_satisfy_state`](../../src/purgatory/helpers.rs) for implementation.
+### 4. Bidirectional Waiting for PR Events
 For PR events, **either side can arrive first**:
- **Event first**: PR event waits in purgatory for git push to `refs/nostr/<event-id>`
+| Scenario | What Happens |
- **Git first**: Push creates placeholder, waits for PR event to arrive
+|----------|--------------|
+| **Event first** | PR event waits in purgatory for git push to `refs/nostr/<event-id>` |
+| **Git first** | Push creates placeholder entry waiting for PR event |
-### 4. Ref Pairs, Not Just Commits
+Placeholders are identified by `PrPurgatoryEntry.event == None`.
-State events define a target state: specific refs pointing to specific objects (commits or annotated tags). We match **ref name + object SHA** pairs, not just raw commits.
+### 5. Authorization During Push (Not After)
-### 5. No Separate PurgatoryState Tracking
+**Critical for avoiding deadlock:** Authorization checks **both database and purgatory** during push validation.
-All entries use a single 30-minute expiry timer. When git push activity begins, we simply ensure at least 15 minutes remain on the timer (extend if needed). This eliminates complexity of tracking Secured vs Pending states.
+Without this, we'd have a deadlock:
+1. State event arrives → No git data → Goes to **purgatory** (not database)
+2. Git push arrives → Authorization checks **database only** → No state found → **REJECTED** ❌
-## Event Lifecycle
+With purgatory checking during authorization:
+1. State event arrives → No git data → Goes to purgatory
+2. Git push arrives → Checks **database + purgatory** → State found → **AUTHORIZED** ✅
+3. After push succeeds → Save event to database → Remove from purgatory
-```mermaid
+See [`src/git/authorization.rs:51-162`](../../src/git/authorization.rs) for implementation.
-stateDiagram-v2
-    [*] --> Waiting: Event or git data arrives
+---
-    Waiting --> Processing: Other half arrives
-    Waiting --> Discarded: 30 min expiry
-    Processing --> Released: Match verified + authorized
-    Processing --> Rejected: Mismatch or unauthorized
-    Released --> [*]: Event saved to database
-    Rejected --> Waiting: Return to waiting - different match expected
-    Discarded --> [*]: Entry dropped
-```
 ## Data Structures
-### RefPair - A single ref target
+### Core Types
 ```rust
 /// A reference name and its target object
 #[derive(Debug, Clone, Hash, Eq, PartialEq)]
 pub struct RefPair {
-    /// Full ref name, e.g., "refs/heads/main" or "refs/tags/v1.0"
+    pub ref_name: String,    // e.g., "refs/heads/main"
+    pub object_sha: String,  // commit or annotated tag SHA
+}
+/// A ref update in a git push
+#[derive(Debug, Clone)]
+pub struct RefUpdate {
+    pub old_oid: String,
+    pub new_oid: String,
    pub ref_name: String,
-    /// Target object SHA (commit or annotated tag)
-    pub object_sha: String,
 }
 ```
-### StatePurgatoryEntry
+### State Purgatory Entry
 ```rust
 pub struct StatePurgatoryEntry {
    /// The nostr state event (kind 30618) awaiting git data
    pub event: Event,
+    
-    /// The repository identifier from the event's 'd' tag
+    /// Repository identifier from 'd' tag
    pub identifier: String,
+    
    /// Event author pubkey
    pub author: PublicKey,
+    
-    /// When this entry was added to purgatory
+    /// When added to purgatory
    pub created_at: Instant,
+    
    /// Expiry deadline (30 min from creation, may be extended)
    pub expires_at: Instant,
 }
 ```
-### PrPurgatoryEntry
+**Note:** Refs are NOT extracted at creation time. They're extracted at push time for late binding.
+### PR Purgatory Entry
 ```rust
 pub struct PrPurgatoryEntry {
    /// The nostr PR event, if received (None = git data arrived first)
    pub event: Option<Event>,
+    
-    /// The expected commit SHA from 'c' tag (if event exists)
+    /// Expected commit SHA from 'c' tag (if event exists)
-    /// or the actual commit pushed (if git arrived first)
+    /// or actual commit pushed (if git arrived first)
    pub commit: String,
+    
-    /// When this entry was added to purgatory
+    /// When added to purgatory
    pub created_at: Instant,
+    
-    /// Expiry deadline (30 min from creation, may be extended)
+    /// Expiry deadline (30 min from creation)
    pub expires_at: Instant,
 }
 ```
-**Note:** `PrPurgatoryEntry.event` being `None` indicates the "git data first" scenario - we have a placeholder waiting for the PR event.
+**Key:** `event: None` indicates a placeholder (git-data-first scenario).
 ### Purgatory Stores
 ```rust
 pub struct Purgatory {
-    /// State events indexed by identifier
+    /// State events indexed by identifier (d tag)
-    state_events: DashMap<String, Vec<StatePurgatoryEntry>>,
+    /// Multiple state events per identifier allowed (different authors)
+    state_events: Arc<DashMap<String, Vec<StatePurgatoryEntry>>>,
+    
    /// PR events indexed by event_id (hex string)
-    pr_events: DashMap<String, PrPurgatoryEntry>,
+    /// Single entry per event ID
+    pr_events: Arc<DashMap<String, PrPurgatoryEntry>>,
+    
+    /// Sync queue for background git data fetching
+    sync_queue: Arc<DashMap<String, SyncQueueEntry>>,
+    
+    _git_data_path: PathBuf,
 }
 ```
+---
 ## Event Flows
-### State Event (Kind 30618) Arrival
+### State Event Arrival (Kind 30618)
 ```mermaid
 sequenceDiagram
    participant Client
    participant WritePolicy
    participant Purgatory
+    participant Database
    participant GitRepos
    Client->>WritePolicy: EVENT kind:30618
    WritePolicy->>WritePolicy: Validate structure
    WritePolicy->>WritePolicy: Parse identifier and author
-    Note right of WritePolicy: Check if we already have git data
+    Note right of WritePolicy: Check if git data exists
    WritePolicy->>GitRepos: Check if any authorized repo has matching refs
-    alt Git data already exists
+    alt Git data exists
        GitRepos-->>WritePolicy: Refs match in repo X
-        WritePolicy->>WritePolicy: Process immediately
+        WritePolicy->>Database: Save event
        WritePolicy->>Client: OK true - event saved
    else Git data not available yet
-        WritePolicy->>Purgatory: add_state - event, identifier
+        WritePolicy->>Purgatory: add_state(event, identifier, author)
-        Purgatory->>Purgatory: Add entry indexed by identifier
+        Purgatory->>Purgatory: Store in state_events[identifier]
-        WritePolicy->>Client: OK true purgatory: will not be served until git data arrives
+        Purgatory->>Purgatory: Enqueue for sync (3min delay)
+        WritePolicy->>Client: OK true "purgatory: awaiting git data"
    end
 ```
-### PR Event (Kind 1617/1618) Arrival
+### PR Event Arrival (Kind 1617/1618)
 ```mermaid
 sequenceDiagram
    participant Client
    participant WritePolicy
    participant Purgatory
+    participant Database
    participant GitRepos
-    Client->>WritePolicy: EVENT kind:1617
+    Client->>WritePolicy: EVENT kind:1617/1618
-    WritePolicy->>WritePolicy: Validate structure
+    WritePolicy->>WritePolicy: Extract event_id and commit from 'c' tag
-    WritePolicy->>WritePolicy: Extract event_id and commit from c tag
-    Note right of WritePolicy: Check if git data already exists
+    Note right of WritePolicy: Check if git data exists
-    WritePolicy->>GitRepos: Check refs/nostr/event-id in authorized repos
+    WritePolicy->>GitRepos: Check refs/nostr/<event-id> in repos
-    alt Git data already exists
+    alt Git data exists in database
-        GitRepos-->>WritePolicy: Found matching commit
+        GitRepos-->>WritePolicy: Found with matching commit
-        WritePolicy->>WritePolicy: Process immediately
+        WritePolicy->>Database: Save event
        WritePolicy->>Client: OK true - event saved
-    else Git data arrived first - placeholder exists
+    else Placeholder exists in purgatory
-        WritePolicy->>Purgatory: find_pr_placeholder - event_id
+        WritePolicy->>Purgatory: find_pr_placeholder(event_id)
-        alt Placeholder found with matching commit
+        alt Placeholder has matching commit
            Purgatory-->>WritePolicy: Placeholder entry
-            WritePolicy->>WritePolicy: Process - save event
+            WritePolicy->>Database: Save event
-            WritePolicy->>Purgatory: remove - event_id
+            WritePolicy->>Purgatory: remove_pr(event_id)
            WritePolicy->>Client: OK true - event saved
-        else Placeholder found with different commit
+        else Placeholder has different commit
            WritePolicy->>Client: OK false - commit mismatch
-        else No placeholder
-            WritePolicy->>Purgatory: add_pr - event, commit
-            WritePolicy->>Client: OK true purgatory: will not be served until git data arrives
        end
+    else No git data yet
+        WritePolicy->>Purgatory: add_pr(event, event_id, commit)
+        Purgatory->>Purgatory: Store in pr_events[event_id]
+        Purgatory->>Purgatory: Enqueue for sync (3min delay)
+        WritePolicy->>Client: OK true "purgatory: awaiting git data"
    end
 ```
-### Git Push - State Event Matching
+### Git Push - State Refs
-When a push arrives to normal refs (branches/tags), we check for matching state events:
+**Critical:** Authorization happens BEFORE git-receive-pack execution, checking both database and purgatory.
-**Key Rule**: For a given `pubkey/identifier` repo, there can only be **one authoritative state event** - the one with the largest `created_at` among all authorized maintainers. State events in purgatory are only processed if they aren't superseded by existing state events on the relay.
 ```mermaid
 sequenceDiagram
    participant GitClient
    participant GitHandler
+    participant Authorization
    participant Purgatory
    participant Database
-    participant GitRepo
+    participant GitProcess
-    GitClient->>GitHandler: POST /npub/identifier/git-receive-pack
+    GitClient->>GitHandler: POST /npub/id/git-receive-pack
-    GitHandler->>GitHandler: Parse pushed refs into RefPairs
+    GitHandler->>Authorization: authorize_push(body, purgatory, database)
+    
-    Note over GitHandler: Look up state events by identifier
+    Note over Authorization: Parse pushed refs from pkt-line format
-    GitHandler->>Purgatory: find_matching_states - identifier, pushed_refs
+    Authorization->>Authorization: parse_pushed_refs(body)
+    Authorization->>Authorization: Separate state refs from refs/nostr/*
-    loop For each state event in purgatory[identifier]
+    
-        Purgatory->>Purgatory: Parse state event refs
+    Note over Authorization: Check database for state events
-        Purgatory->>Purgatory: Check: pushed_refs covers event refs that differ from local
+    Authorization->>Database: Query state events for identifier
-        Purgatory->>Purgatory: Check: event refs not in push already exist locally
+    
-        alt All event refs can be satisfied
+    alt State found in database
-            Purgatory->>Purgatory: Add to candidates
+        Database-->>Authorization: State event
-        end
+        Authorization->>Authorization: Validate refs match
-    end
+        Authorization-->>GitHandler: Authorized (from_purgatory=false)
+    else No state in database - check purgatory
-    Purgatory-->>GitHandler: Vec of candidate state events
+        Authorization->>Purgatory: find_matching_states(identifier, pushed_refs, local_refs)
+        
-    Note over GitHandler: Get all state events and announcements for identifier
+        alt Matching state in purgatory
-    GitHandler->>Database: Get announcements for identifier
+            Purgatory-->>Authorization: State event(s)
-    GitHandler->>Database: Get all state events for identifier from relay
+            Authorization->>Authorization: Filter to authorized authors
-    GitHandler->>GitHandler: collect_authorized_maintainers from announcements
+            Authorization->>Authorization: Find latest state
+            Authorization->>Authorization: Validate refs match
-    Note over GitHandler: Find authoritative state event
+            Authorization->>Purgatory: extend_expiry(15min)
-    loop For each candidate from purgatory
+            Authorization-->>GitHandler: Authorized (from_purgatory=true)
-        GitHandler->>GitHandler: Check if event.author is authorized for target repo
+        else No matching state anywhere
-        alt Author authorized
+            Authorization-->>GitHandler: Rejected - no authorized state
-            GitHandler->>GitHandler: Check relay state events for this identifier
-            GitHandler->>GitHandler: Compare created_at with all authorized state events
-            alt This is the largest created_at among authorized
-                GitHandler->>GitHandler: Verify OIDs for unpushed refs exist locally
-                alt All OIDs available
-                    GitHandler->>GitHandler: Set as approved state event
-                end
-            else Superseded by existing state on relay
-                GitHandler->>Purgatory: Remove superseded event
-            end
        end
    end
+    
-    Note over GitHandler: Only ONE approved state event per repo
+    alt Authorized
-    alt Approved state event exists
+        GitHandler->>GitProcess: Execute git-receive-pack
-        GitHandler->>Purgatory: extend_expiry - event_id - ensure 15 min
+        
-        GitHandler->>GitRepo: Execute git-receive-pack
+        alt Push succeeds AND from_purgatory=true
-        alt Push successful
            GitHandler->>Database: Save state event
-            GitHandler->>GitRepo: Align ALL refs to state - including unpushed
+            GitHandler->>Purgatory: remove_state_event(identifier, event_id)
-            GitHandler->>GitHandler: Sync to other authorized maintainer repos
-            GitHandler->>Purgatory: remove - event_id
            GitHandler->>GitClient: Push accepted
-        else Push failed
+        else Push succeeds AND from_purgatory=false
-            GitHandler->>GitClient: Push rejected
+            GitHandler->>GitClient: Push accepted
+        else Push fails
+            GitHandler->>GitClient: Push rejected - git error
        end
-    else No approved state event
+    else Rejected
-        GitHandler->>GitClient: Push rejected - no authorized state
+        GitHandler->>GitClient: Push rejected - not authorized
    end
 ```
-### Git Push - PR Event (refs/nostr/event-id)
+### Git Push - PR Refs (refs/nostr/event-id)
 ```mermaid
 sequenceDiagram
    participant GitClient
    participant GitHandler
-    participant Database
    participant Purgatory
-    participant GitRepo
+    participant Database
+    participant GitProcess
-    GitClient->>GitHandler: POST /npub/identifier/git-receive-pack refs/nostr/abc123
-    GitHandler->>GitHandler: Extract event_id from ref
+    GitClient->>GitHandler: POST /npub/id/git-receive-pack refs/nostr/abc123
-    GitHandler->>GitHandler: Extract pushed commit SHA
+    GitHandler->>GitHandler: Extract event_id and commit from push
+    
-    Note over GitHandler: First check relay database
+    Note over GitHandler: Check database first
-    GitHandler->>Database: Query for PR event with event_id
+    GitHandler->>Database: Query PR event with event_id
+    
    alt Event exists in database
-        Database-->>GitHandler: PR event found
+        Database-->>GitHandler: PR event
        GitHandler->>GitHandler: Compare commit tags
        alt Commit matches
-            GitHandler->>GitRepo: Execute push
+            GitHandler->>GitProcess: Execute push
            GitHandler->>GitClient: Push accepted
        else Commit mismatch
-            GitHandler->>GitClient: Push rejected - commit mismatch with existing event
+            GitHandler->>GitClient: Push rejected - commit mismatch
        end
-    else Event not in database
+    else Event not in database - check purgatory
-        GitHandler->>Purgatory: find_pr - event_id
+        GitHandler->>Purgatory: find_pr(event_id)
+        
        alt PR event in purgatory
            Purgatory-->>GitHandler: PR entry with event
            GitHandler->>GitHandler: Compare commit tags
            alt Commit matches
-                GitHandler->>GitRepo: Execute push
+                GitHandler->>GitProcess: Execute push
                GitHandler->>Database: Save PR event
-                GitHandler->>GitHandler: Sync to other authorized repos
+                GitHandler->>Purgatory: remove_pr(event_id)
-                GitHandler->>Purgatory: remove - event_id
                GitHandler->>GitClient: Push accepted
            else Commit mismatch
                GitHandler->>GitClient: Push rejected - commit mismatch
            end
-        else No PR event anywhere
+        else No PR event anywhere (git-data-first)
-            Note over GitHandler: Git data first scenario
+            GitHandler->>GitProcess: Execute push - accept any commit
-            GitHandler->>GitRepo: Execute push - accept any data
+            GitHandler->>Purgatory: add_pr_placeholder(event_id, commit)
-            GitHandler->>Purgatory: add_pr_placeholder - event_id, commit
            GitHandler->>GitClient: Push accepted - awaiting PR event
        end
    end
 ```
-### Sync to Other Maintainer Repos
+---
-After successfully processing a state event or PR, we sync to other authorized repos:
+## Background Sync
-```mermaid
+Purgatory includes a background sync system that fetches git data from remote servers when events arrive before git data.
-sequenceDiagram
-    participant Handler
-    participant Database
-    participant Authorization
-    participant GitRepos
-    Handler->>Database: Get all announcements for identifier
+### Sync Architecture
-    Handler->>Authorization: collect_authorized_maintainers - announcements
-    Authorization-->>Handler: Map of owner -> authorized maintainers
-    loop For each owner in map
+```
-        alt Event author in owner's authorized set
+┌─────────────────────────────────────────────────────┐
-            Note right of Handler: This owner's repo should have this state/PR
+│                  Sync Loop (1s)                     │
+│  - Checks sync_queue for ready identifiers          │
+│  - Spawns tasks for each ready identifier           │
+└─────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────┐
+│           sync_identifier(identifier)               │
+│  1. Try all non-throttled URLs sequentially         │
+│  2. Check if complete after each fetch              │
+│  3. Enqueue with throttled domains if incomplete    │
+└─────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────┐
+│      sync_identifier_from_url(identifier, url)      │
+│  1. Collect needed OIDs from purgatory events       │
+│  2. Fetch OIDs from remote URL                      │
+│  3. Process newly available git data                │
+└─────────────────────────────────────────────────────┘
+                         │
+                         ▼
+┌─────────────────────────────────────────────────────┐
+│   process_newly_available_git_data(repo, oids)      │
+│  1. Find satisfiable state events in purgatory      │
+│  2. Find satisfiable PR events in purgatory         │
+│  3. Save events to database                         │
+│  4. Sync git data to other owner repos              │
+│  5. Remove from purgatory                           │
+└─────────────────────────────────────────────────────┘
+```
-            alt State event
+### Sync Queue Entry
-                Handler->>GitRepos: Align owner's repo to state event refs
-            else PR event
+```rust
-                Handler->>GitRepos: Ensure refs/nostr/event-id exists
+pub struct SyncQueueEntry {
-            end
+    /// When to attempt next sync
-        end
+    pub next_attempt: Instant,
-    end
+    
+    /// Number of sync attempts made
+    pub attempt_count: u32,
+    
+    /// Whether a sync task is currently running
+    pub in_progress: bool,
+}
 ```
-### Background Cleanup
+**Backoff strategy:**
+- First attempt: 20 seconds
+- Second attempt: 2 minutes
+- Subsequent attempts: 2 minutes
-```mermaid
+### Sync Delays
-sequenceDiagram
-    participant Timer
-    participant Purgatory
-    loop Every 60 seconds
+| Scenario | Delay | Reason |
-        Timer->>Purgatory: cleanup
+|----------|-------|--------|
+| User-submitted event | 3 minutes | Give time for git push to arrive |
+| Sync-triggered event | 500ms | Batch burst arrivals from negentropy |
-        Note over Purgatory: Clean state events
+### Domain Throttling
-        loop For each identifier in state_events
-            loop For each entry
-                alt now > expires_at
-                    Purgatory->>Purgatory: Remove entry
-                end
-            end
-        end
-        Note over Purgatory: Clean PR events
+```rust
-        loop For each event_id in pr_events
+pub struct ThrottleManager {
-            alt now > entry.expires_at
+    /// Max requests per domain per minute
-                Purgatory->>Purgatory: Remove entry
+    max_requests_per_minute: usize,
-            end
+    
-        end
+    /// Tracking window duration
-    end
+    window_duration: Duration,
+    
+    /// Per-domain throttle state
+    domains: DashMap<String, DomainThrottle>,
+}
 ```
-## API Methods
+**Rate limiting:**
+- Default: 5 requests per domain per 30 seconds
+- Tracks request timestamps in a sliding window
+- Queues identifiers when domain is throttled
+- Processes queue when capacity frees up
+See [`src/purgatory/sync/throttle.rs`](../../src/purgatory/sync/throttle.rs) for implementation.
+---
+## Purgatory API
-### Purgatory
+### Adding Entries
 ```rust
 impl Purgatory {
-    /// Create a new empty purgatory
+    /// Add a state event to purgatory
-    pub fn new() -> Self;
+    /// Automatically enqueues for sync with 3min delay
+    pub fn add_state(&self, event: Event, identifier: String, author: PublicKey);
-    // ==================== State Events ====================
+    
+    /// Add a PR event to purgatory
+    /// Automatically enqueues for sync with 3min delay
+    pub fn add_pr(&self, event: Event, event_id: String, commit: String);
+    
+    /// Add a PR placeholder (git-data-first scenario)
+    pub fn add_pr_placeholder(&self, event_id: String, commit: String);
+}
+```
-    /// Add a state event (kind 30618) to purgatory
+### Finding Entries
-    /// Returns purgatory message for client response
-    pub fn add_state(&self, event: Event, identifier: String) -> String;
-    /// Find state events that could be satisfied by pushed refs
+```rust
-    /// Returns events where:
+impl Purgatory {
-    /// - All refs in event are either in pushed_refs OR already exist locally
+    /// Find state events waiting for an identifier
-    /// - At least one ref in event is in pushed_refs (something to update)
+    pub fn find_state(&self, identifier: &str) -> Vec<StatePurgatoryEntry>;
+    
+    /// Find state events that match pushed refs (late binding)
    pub fn find_matching_states(
        &self,
        identifier: &str,
-        pushed_refs: &[RefPair],
+        pushed_updates: &[RefUpdate],
        local_refs: &HashMap<String, String>,
    ) -> Vec<Event>;
+    
+    /// Find a PR entry by event ID
+    pub fn find_pr(&self, event_id: &str) -> Option<PrPurgatoryEntry>;
+    
+    /// Find a PR placeholder specifically (git-data-first)
+    pub fn find_pr_placeholder(&self, event_id: &str) -> Option<String>;
+}
+```
-    /// Extend expiry for entries about to be processed
+### Removing Entries
-    /// Ensures at least `duration` remaining on timer
-    pub fn extend_expiry(&self, event_ids: &[EventId], duration: Duration);
-    /// Remove state event after successful processing
-    pub fn remove_state(&self, event_id: &EventId);
-    // ==================== PR Events ====================
-    /// Add a PR event (kind 1617/1618) to purgatory
-    /// Returns purgatory message for client response
-    pub fn add_pr(&self, event: Event, commit: String) -> String;
-    /// Add a placeholder for git-data-first scenario
-    /// Called when push to refs/nostr/<event-id> arrives before the PR event
-    pub fn add_pr_placeholder(&self, event_id: EventId, commit: String);
-    /// Find PR entry by event ID
-    /// Returns the entry if found (may or may not have event)
-    pub fn find_pr(&self, event_id: &EventId) -> Option<PrPurgatoryEntry>;
-    /// Find PR placeholder (git-data-first entry without event)
-    pub fn find_pr_placeholder(&self, event_id: &EventId) -> Option<PrPurgatoryEntry>;
-    /// Remove PR entry after successful processing
+```rust
-    pub fn remove_pr(&self, event_id: &EventId);
+impl Purgatory {
+    /// Remove all state events for an identifier
+    pub fn remove_state(&self, identifier: &str);
+    
+    /// Remove a specific state event by event ID
+    pub fn remove_state_event(&self, identifier: &str, event_id: &EventId);
+    
+    /// Remove a PR entry
+    pub fn remove_pr(&self, event_id: &str);
+}
+```
-    // ==================== Maintenance ====================
+### Maintenance
-    /// Remove expired entries (30 min)
+```rust
-    /// Returns count of removed entries
+impl Purgatory {
-    pub fn cleanup(&self) -> usize;
+    /// Remove expired entries (called every 60 seconds)
+    /// Returns (state_removed, pr_removed)
+    pub fn cleanup(&self) -> (usize, usize);
+    
+    /// Extend expiry for entries about to be processed
+    /// Ensures at least `duration` remaining
+    pub fn extend_expiry(&self, identifier: &str, event_ids: &[EventId], duration: Duration);
+    
+    /// Get current counts for metrics
+    pub fn count(&self) -> (usize, usize);
+}
+```
-    /// Get counts for metrics/debugging
+### Sync Queue Management
-    pub fn state_event_count(&self) -> usize;
-    pub fn pr_event_count(&self) -> usize;
-    pub fn pr_placeholder_count(&self) -> usize;
-    /// Check if an event is in purgatory (either store)
+```rust
-    pub fn contains(&self, event_id: &EventId) -> bool;
+impl Purgatory {
+    /// Enqueue identifier for sync with custom delay
+    pub fn enqueue_sync(&self, identifier: &str, delay: Duration);
+    
+    /// Enqueue with default delay (3 minutes)
+    pub fn enqueue_sync_default(&self, identifier: &str);
+    
+    /// Enqueue with immediate delay (500ms)
+    pub fn enqueue_sync_immediate(&self, identifier: &str);
+    
+    /// Check if identifier has pending events
+    pub fn has_pending_events(&self, identifier: &str) -> bool;
+    
+    /// Remove identifier from sync queue
+    pub fn remove_from_sync_queue(&self, identifier: &str);
 }
 ```
-### Helper: Extract and Match Refs
+---
+## Helper Functions
+### State Event Matching
 ```rust
 /// Extract ref pairs from a state event
-pub fn extract_refs_from_state(event: &Event) -> Vec<RefPair> {
+pub fn extract_refs_from_state(event: &Event) -> Vec<RefPair>;
-    // Parse refs/heads/* and refs/tags/* tags
-    // Return vec of RefPair { ref_name, object_sha }
-}
 /// Check if a state event can be satisfied by a push
-///
 /// Returns true if:
-/// - Every ref in state_refs is either in pushed_refs (matching SHA) OR in local_refs (matching SHA)
+/// - Every ref in state is either in pushed_refs OR in local_refs
-/// - At least one ref in state_refs is actually being changed by the push
+/// - At least one ref in state is being changed by the push
 pub fn can_satisfy_state(
    state_refs: &[RefPair],
    pushed_refs: &[RefPair],
    local_refs: &HashMap<String, String>,
 ) -> bool;
-/// Get refs from state event that aren't being pushed but need updating
+/// Check if a state event can be applied to a repository
+/// Returns true if all required OIDs exist in the repo
+pub fn can_apply_state(
+    event: &Event,
+    repo_path: &Path,
+) -> Result<bool>;
+/// Get refs from state that aren't being pushed
 pub fn get_unpushed_refs(
    state_refs: &[RefPair],
    pushed_refs: &[RefPair],
 ) -> Vec<RefPair>;
-/// Verify all OIDs from refs exist in the local git repo
-pub fn verify_oids_exist(
-    repo_path: &Path,
-    refs: &[RefPair],
-) -> Result<bool, git::Error>;
 ```
-## Integration Points
+See [`src/purgatory/helpers.rs`](../../src/purgatory/helpers.rs) for implementation.
-### 1. Nip34WritePolicy Changes
-```rust
+---
-pub struct Nip34WritePolicy {
-    ctx: PolicyContext,
-    purgatory: Arc<Purgatory>,  // Shared with git handlers
-    // ... existing fields
-}
-```
-### 2. handle_state Changes
-On state event arrival:
+## Integration Points
-**Key Rules**:
+### 1. Event Policy (Nip34WritePolicy)
-1. Reject if we already have a state event from this author for this identifier with a larger `created_at` date (outdated event)
+State and PR events are added to purgatory when git data doesn't exist:
-2. If accepted, check if we need to sync repos with the same identifier
 ```rust
+// From src/nostr/policy/state.rs
 async fn handle_state(&self, event: &Event) -> WritePolicyResult {
-    let identifier = extract_identifier(&event)?;
+    let identifier = extract_identifier(event)?;
-    let author = event.pubkey;
+    
-    let state_refs = extract_refs_from_state(&event);
+    // Check if we have matching git data
+    if self.has_matching_git_data(&identifier, event).await? {
-    // Check for existing state event from this author with larger created_at
+        return WritePolicyResult::Accept;
-    let existing_states = self.database.get_state_events_by_author_identifier(
-        &author,
-        &identifier
-    ).await?;
-    for existing in existing_states {
-        if existing.created_at > event.created_at {
-            // Reject - we have a newer state from this author
-            return WritePolicyResult::Reject {
-                status: false,
-                message: "rejected: newer state event exists for this author/identifier".into()
-            };
-        }
    }
+    
-    // Check if we already have matching git data
-    let repos = self.find_repos_for_identifier(&identifier).await?;
-    for repo in repos {
-        if self.refs_match_state(&repo, &state_refs).await? {
-            // Git data exists - process immediately
-            // Also trigger sync check for other repos with same identifier
-            // Pass the repo that has the git data so it can be used as source
-            self.check_and_sync_repos_for_identifier(&identifier, &event, &repo).await?;
-            return WritePolicyResult::Accept;
-        }
-    }
    // Add to purgatory
-    let msg = self.purgatory.add_state(event.clone(), identifier);
+    self.purgatory.add_state(
+        event.clone(),
+        identifier.clone(),
+        event.pubkey,
+    );
+    
    WritePolicyResult::Reject {
        status: true,  // Client sees OK
-        message: msg.into()
+        message: "purgatory: awaiting git data".into()
-    }
-}
-```
-### 3. handle_pr_event Changes
-On PR event arrival:
-**Key Rule**: Incoming PR events supersede existing refs. If the existing `refs/nostr/<event-id>` ref has a different commit_id, the ref should be removed and the event stored in purgatory to await new git data.
-```rust
-async fn handle_pr_event(&self, event: &Event) -> WritePolicyResult {
-    let commit = extract_c_tag_commit(&event)?;
-    let event_id = event.id.to_hex();
-    // Check if placeholder exists (git-data-first)
-    if let Some(placeholder) = self.purgatory.find_pr_placeholder(&event.id) {
-        if placeholder.commit == commit {
-            self.purgatory.remove_pr(&event.id); // Note this shouldnt remove the git data
-            return WritePolicyResult::Accept;
-        } else {
-            // Placeholder has different commit - incoming event supersedes
-            // Update placeholder with new expected commit
-            self.purgatory.remove_pr(&event.id);
-            // TODO also remove git data
-            let msg = self.purgatory.add_pr(event.clone(), commit);
-            return WritePolicyResult::Reject {
-                status: true,  // Client sees OK - in purgatory awaiting correct git data
-                message: msg.into()
-            };
-        }
-    }
-    // Add to purgatory
-    let msg = self.purgatory.add_pr(event.clone(), commit);
-    WritePolicyResult::Reject {
-        status: true,
-        message: msg.into()
    }
 }
 ```
-### 4. Git Handler Changes
+### 2. Git Push Authorization
-In `handle_receive_pack` for normal refs:
+Authorization checks both database and purgatory:
-**Key Rule**: Refs are sent to a specific repo (`pubkey/identifier`), and there can only be **one authorized state event** for that repo. Therefore, this function returns a single `Option<Event>` rather than `Vec<Event>`.
 ```rust
-async fn handle_state_refs_push(
+// From src/git/authorization.rs
-    &self,
+pub async fn authorize_push(
+    database: &SharedDatabase,
    identifier: &str,
-    repo_owner: &str,
+    owner_pubkey: &str,
-    pushed_refs: &[RefPair],
+    request_body: &Bytes,
-) -> Result<Option<Event>, GitError> {
+    purgatory: &Arc<Purgatory>,  // Critical!
-    let local_refs = git::list_refs(&self.repo_path)?;
+    repo_path: &std::path::Path,
+) -> anyhow::Result<AuthorizationResult> {
-    // Find matching state events
+    // Parse pushed refs
-    let candidates = self.purgatory.find_matching_states(
+    let pushed_refs = parse_pushed_refs(request_body);
-        identifier,
+    
-        pushed_refs,
+    // Check database for state events
-        &local_refs,
+    let db_result = get_authorization_from_db(database, identifier).await?;
-    );
+    
+    if !db_result.authorized {
-    // Get all state events from relay for this identifier
+        // No state in database - check purgatory
-    let relay_states = self.database.get_state_events_for_identifier(identifier).await?;
+        let purgatory_result = get_state_authorization_for_specific_owner_repo(
+            database,
-    // Get announcements to determine authorization
+            identifier,
-    let announcements = self.database.get_announcements(identifier).await?;
+            owner_pubkey,
-    let auth_map = collect_authorized_maintainers(&announcements);
+            purgatory,
+            &pushed_refs,
-    // Find the authoritative state event (largest created_at among all authorized)
+            repo_path,
-    let mut best_candidate: Option<(Event, Timestamp)> = None;
+        ).await?;
+        
-    // Check purgatory candidates
+        return purgatory_result;
-    for event in candidates {
-        if let Some(maintainers) = auth_map.get(repo_owner) {
-            if maintainers.contains(&event.pubkey.to_hex()) {
-                // Check if this event is superseded by any relay state
-                let superseded = relay_states.iter().any(|relay_state| {
-                    let relay_authorized = auth_map.values()
-                        .any(|m| m.contains(&relay_state.pubkey.to_hex()));
-                    relay_authorized && relay_state.created_at > event.created_at
-                });
-                if superseded {
-                    // Don't use this as best_candidate for THIS repo
-                    // Note: Do NOT remove from purgatory - it may still be
-                    // authoritative for a DIFFERENT repo with a different maintainer set
-                    continue;
-                }
-                // Verify OIDs for unpushed refs exist
-                let state_refs = extract_refs_from_state(&event);
-                let unpushed = get_unpushed_refs(&state_refs, pushed_refs);
-                if verify_oids_exist(&self.repo_path, &unpushed)? {
-                    // Track best candidate by created_at
-                    if best_candidate.is_none() || event.created_at > best_candidate.as_ref().unwrap().1 {
-                        best_candidate = Some((event, event.created_at));
-                    }
-                }
-            }
-        }
-    }
-    // If we found an approved event, extend its expiry
-    if let Some((ref event, _)) = best_candidate {
-        self.purgatory.extend_expiry(&[event.id], Duration::from_secs(900));
    }
+    
-    Ok(best_candidate.map(|(e, _)| e))
+    db_result
 }
 ```
-For `refs/nostr/<event-id>` pushes:
+### 3. Post-Push Processing
-**Key Rule**: If there is no event (neither in database nor in purgatory), a push of a different commit_id should be **accepted**. This is the "git-data-first" scenario where we're waiting for the PR event to arrive.
+After successful push, events from purgatory are saved to database:
 ```rust
-async fn handle_nostr_ref_push(
+// From src/git/handlers.rs
-    &self,
+if from_purgatory {
-    event_id: &str,
+    if let (Some(db), Some(purg)) = (&database, &purgatory) {
-    pushed_commit: &str,
+        // Save state event to database
-) -> Result<PushDecision, GitError> {
+        db.save_event(&state.event).await?;
-    // Check database first
+        
-    if let Some(event) = self.database.get_event_by_id(event_id).await? {
+        // Remove from purgatory
-        let expected_commit = extract_c_tag_commit(&event)?;
+        purg.remove_state_event(identifier, &state.event.id);
-        if expected_commit == pushed_commit {
-            return Ok(PushDecision::Accept);
-        } else {
-            return Ok(PushDecision::Reject("commit mismatch with existing event"));
-        }
-    }
-    // Check purgatory for PR event
-    if let Some(entry) = self.purgatory.find_pr(&EventId::from_hex(event_id)?) {
-        if let Some(event) = entry.event {
-            // Event exists in purgatory - must match commit
-            let expected_commit = extract_c_tag_commit(&event)?;
-            if expected_commit == pushed_commit {
-                // Remove from purgatory before returning
-                self.purgatory.remove_pr(&EventId::from_hex(event_id)?); // note this shouldnt delete the git data
-                return Ok(PushDecision::AcceptAndRelease(event));
-            } else {
-                return Ok(PushDecision::Reject("commit mismatch with purgatory event"));
-            }
-        } else {
-            // Placeholder exists (previous push, no event yet)
-            // Accept and update placeholder with new commit
-            // This allows re-pushing with corrected data before event arrives
-            return Ok(PushDecision::AcceptAndUpdatePlaceholder(pushed_commit.to_string()));
-        }
    }
-    // No event anywhere - git-data-first scenario
-    // Accept ANY commit and create placeholder awaiting the PR event
-    Ok(PushDecision::AcceptAndCreatePlaceholder(pushed_commit.to_string()))
 }
-// TODO when AcceptAndUpdatePlaceholder gets called purgatory must get udpated with a new / updated entry either here of where AcceptAndCreatePlaceholder is handled
 ```
-### 5. Main.rs Changes
+### 4. Background Sync Loop
-```rust
+Started during application initialization:
-// During startup
-let purgatory = Arc::new(Purgatory::new());
-// Pass to WritePolicy
+```rust
-let write_policy = Nip34WritePolicy::new(
+// From src/main.rs
-    &config.domain,
+let purgatory = Arc::new(Purgatory::new(git_data_path));
+let ctx = Arc::new(RealSyncContext::new(
    database.clone(),
-    &git_data_path,
    purgatory.clone(),
-);
+    config.domain.clone(),
+    git_data_path.clone(),
-// Pass to git handlers (via shared state)
+));
-let git_state = GitState {
+let throttle_manager = Arc::new(ThrottleManager::new(5, 30));
-    purgatory: purgatory.clone(),
+throttle_manager.set_context(ctx.clone());
-    database: database.clone(),
-    // ...
+// Start sync loop
-};
+let sync_handle = purgatory.clone().start_sync_loop(ctx, throttle_manager);
-// Spawn cleanup task
+// Start cleanup task
-let purgatory_cleanup = purgatory.clone();
+let cleanup_handle = tokio::spawn(async move {
-tokio::spawn(async move {
    let mut interval = tokio::time::interval(Duration::from_secs(60));
    loop {
        interval.tick().await;
-        let removed = purgatory_cleanup.cleanup();
+        let (state_removed, pr_removed) = purgatory.cleanup();
-        if removed > 0 {
+        if state_removed + pr_removed > 0 {
-            tracing::debug!("Purgatory cleanup removed {} expired entries", removed);
+            tracing::debug!(
+                "Purgatory cleanup removed {} state, {} PR entries",
+                state_removed, pr_removed
+            );
        }
    }
 });
 ```
-## Post-Push Sync Flow
+---
-After successfully processing a state or PR event, sync to other maintainer repos:
-**Key Rules for State Events (30618)**:
-1. Fetch all state events matching the identifier from the database
-2. Check if another existing state event supersedes this one (the maintainer set may be different, so another maintainer may have a more recent state event)
-3. Only sync if this event is not superseded
-```rust
-async fn sync_to_other_repos(
-    &self,
-    identifier: &str,
-    event: &Event,
-    processed_repo_owner: &str,
-) -> Result<usize, SyncError> {
-    let announcements = self.database.get_announcements(identifier).await?;
-    let auth_map = collect_authorized_maintainers(&announcements);
-    // Fetch all state events for this identifier to check for superseding
-    let all_state_events = self.database.get_state_events_for_identifier(identifier).await?;
-    let mut synced = 0;
-    for (owner, maintainers) in auth_map {
-        // Skip the repo we just processed
-        if owner == processed_repo_owner {
-            continue;
-        }
-        // Check if event author is authorized for this owner's repo
-        if maintainers.contains(&event.pubkey.to_hex()) {
-            let repo_path = self.repo_path_for_owner(&owner);
-            match event.kind.as_u64() {
-                30618 => {
-                    // State event - check if another state event supersedes this one
-                    // for THIS owner's repo (maintainer sets may differ between owners)
-                    let owner_maintainers = auth_map.get(&owner).cloned().unwrap_or_default();
-                    // Find the authoritative state for this owner's repo
-                    let superseding_state = all_state_events.iter()
-                        .filter(|s| owner_maintainers.contains(&s.pubkey.to_hex()))
-                        .filter(|s| s.created_at > event.created_at)
-                        .max_by_key(|s| s.created_at);
-                    if let Some(newer_state) = superseding_state {
-                        // This event is superseded by a more recent state
-                        // for this owner's repo - skip syncing this event
-                        tracing::debug!(
-                            "Skipping sync to {}: event {} superseded by {}",
-                            owner,
-                            event.id,
-                            newer_state.id
-                        );
-                        continue;
-                    }
-                    // No superseding state - align refs
-                    let state_refs = extract_refs_from_state(&event);
-                    self.align_refs(&repo_path, &state_refs)?;
-                }
-                1617 | 1618 => {
-                    // PR event - ensure nostr ref exists
-                    let commit = extract_c_tag_commit(&event)?;
-                    self.ensure_nostr_ref(&repo_path, &event.id, &commit)?;
-                }
-                _ => {}
-            }
-            synced += 1;
-        }
-    }
-    Ok(synced)
-}
-```
-## Implementation File Structure
+## File Structure
 ```
 src/
 ├── purgatory/
-│   ├── mod.rs              # Purgatory struct, public API
+│   ├── mod.rs              # Main Purgatory struct and API
 │   ├── types.rs            # RefPair, StatePurgatoryEntry, PrPurgatoryEntry
-│   ├── state_events.rs     # State event purgatory logic
+│   ├── helpers.rs          # Ref extraction and matching functions
-│   ��── pr_events.rs        # PR event purgatory logic
+│   ��── sync/
-│   ��── helpers.rs          # extract_refs_from_state, can_satisfy_state, etc.
+│       ��── mod.rs          # Sync module exports
-├── nostr/
+��       ��── loop.rs         # Background sync loop
-│   ├── builder.rs          # Modified: Nip34WritePolicy accepts Arc<Purgatory>
+│       ├── functions.rs    # sync_identifier, sync_identifier_from_url
-│   ��── policy/
+│       ��── context.rs      # SyncContext trait and RealSyncContext
-│       ├── state.rs        # Modified: handle_state uses purgatory
+│       ├── queue.rs        # SyncQueueEntry
-│       └── pr_event.rs     # Modified: handle_pr_event uses purgatory
+│       └── throttle.rs     # ThrottleManager, DomainThrottle
 ├── git/
-│   └── handlers.rs         # Modified: handle_receive_pack integrates purgatory
+│   ├── authorization.rs    # authorize_push with purgatory checking
-└── main.rs                 # Modified: creates Purgatory, spawns cleanup task
+│   ├── handlers.rs         # handle_receive_pack with post-push processing
+│   └── sync.rs             # process_newly_available_git_data
+└── nostr/
+    └── policy/
+        ├── state.rs        # State event policy with purgatory
+        └── pr_event.rs     # PR event policy with purgatory
 ```
-## Additional Type Definitions
+---
-### PushDecision Enum
-Used by `handle_nostr_ref_push` to communicate different outcomes to the caller:
-```rust
-/// Result of evaluating a push to refs/nostr/<event-id>
-pub enum PushDecision {
-    /// Push is valid - event exists in database and commit matches
-    Accept,
-    /// Push valid and event should be released from purgatory to database
-    AcceptAndRelease(Event),
-    /// Push valid - create new placeholder awaiting PR event
-    AcceptAndCreatePlaceholder(String),  // commit SHA
-    /// Push valid - update existing placeholder with new commit
-    AcceptAndUpdatePlaceholder(String),  // new commit SHA
-    /// Push rejected with reason
-    Reject(&'static str),
-}
-```
-### WritePolicyResult Clarification
-The design uses a pattern where purgatory events return `status: true` but the event is NOT saved:
-```rust
-// Event goes to purgatory - client sees OK but event not served until git data arrives
-WritePolicyResult::Reject {
-    status: true,  // Nostr OK message to client
-    message: "purgatory: won't be served until git data arrives".into()
-}
-// Event rejected - client sees error
-WritePolicyResult::Reject {
-    status: false,  // Nostr error message to client
-    message: "rejected: reason...".into()
-}
-// Event accepted and saved to database
-WritePolicyResult::Accept
-```
-**Note:** This is a quirk of using the `WritePolicyResult::Reject` variant for purgatory - the `status: true` ensures the client receives an OK response, but since we're in the Reject variant, the event is not automatically saved to the database. The purgatory mechanism holds it until git data arrives.
-## Test Scenarios
-### State Event Tests
+## Testing
-1. **Event arrives, git data exists** - Event processed immediately, saved to DB
+### Unit Tests
-2. **Event arrives, git data doesn't exist** - Event goes to purgatory, client sees OK
-3. **Git push arrives, matching event in purgatory** - Event released from purgatory, saved to DB
-4. **Git push arrives, no matching event** - Push rejected (no authorized state)
-5. **Event expires in purgatory** - Entry removed after 30 minutes (dont implement test due to 30m wait)
-6. **Multiple state events for same identifier** - Late binding at push time selects correct one
-### PR Event Tests
+Located in each module:
-1. **PR event arrives, git data exists** - Event processed immediately, saved to DB
+- **[`src/purgatory/mod.rs`](../../src/purgatory/mod.rs)** - Core purgatory operations
-2. **PR event arrives, no git data** - Event goes to purgatory awaiting git push
+- **[`src/purgatory/helpers.rs`](../../src/purgatory/helpers.rs)** - Ref matching logic
-3. **PR event arrives, placeholder exists with matching commit** - Event released, saved to DB
+- **[`src/purgatory/sync/functions.rs`](../../src/purgatory/sync/functions.rs)** - Sync functions with MockSyncContext
-4. **PR event arrives, placeholder exists with different commit** - Ref deleted, event to purgatory
+- **[`src/purgatory/sync/throttle.rs`](../../src/purgatory/sync/throttle.rs)** - Throttle manager
-5. **Git push to refs/nostr/ arrives, PR event exists in purgatory** - Event released, ref created
-6. **Git push to refs/nostr/ arrives, no PR event** - Placeholder created, awaiting event
-7. **Second git push updates placeholder** - Placeholder commit updated
-### Edge Cases (NOT TESTED)
+### Integration Tests
-1. **Relay restart** - All purgatory entries lost (acceptable per design)
+Located in [`tests/`](../../tests/):
-2. **Same event submitted twice** - Deduplicated by event ID
-3. **Push timeout during processing** - Entry expiry extended to 15 min minimum
-4. **Race between event and git push** - Whichever completes the pair triggers release
+- **State event purgatory flow** - Event arrives, git push releases it
+- **PR event purgatory flow** - Event arrives, git push releases it
+- **Git-data-first flow** - Git push creates placeholder, event completes it
+- **Authorization with purgatory** - Push authorized by purgatory state
+- **Background sync** - Sync fetches git data and releases events
-## Purgatory Authorization Fix (2025-12-24)
+---
-**Critical Implementation Note**: The original purgatory design placed purgatory checking AFTER git push execution. This created a deadlock where pushes were rejected because the authorizing state event was in purgatory, not the database.
+## Key Learnings
-### The Deadlock Problem
+### 1. Purgatory Authorization is Critical
-**Original broken flow:**
+Without checking purgatory during authorization, we have a deadlock:
-1. State event arrives → No git data exists → Event stored in PURGATORY (not database)
+- State event goes to purgatory (no git data)
-2. Git push arrives → Authorization checks DATABASE only → No state found → **PUSH REJECTED** ❌
+- Push is rejected (no state in database)
-3. Purgatory check runs → But push already failed, so this never helps
+- Event never gets released
-### The Fix: Authorization-Time Purgatory Check
+**Solution:** `authorize_push()` checks both database and purgatory.
-**Correct flow (implemented):**
+### 2. Late Binding for State Events
-1. State event arrives → No git data exists → Event stored in purgatory
-2. Git push arrives → Authorization checks **DATABASE + PURGATORY** → State found in purgatory → **PUSH AUTHORIZED** ✅
-3. After successful push → Save purgatory event to database → Remove from purgatory
-### Implementation Details
+Extracting refs at event arrival time doesn't work when:
+- Multiple state events arrive for same identifier
+- Git data for older state arrives after newer state received
-#### 1. Modified [`AuthorizationResult`](../../src/git/authorization.rs:397)
+**Solution:** Extract and match refs at push time via `find_matching_states()`.
-Added `from_purgatory: bool` field to track whether the authorizing state came from purgatory:
+### 3. Bidirectional Waiting for PR Events
-```rust
+PR events can arrive before or after git data:
-pub struct AuthorizationResult {
+- Event first → Wait for git push
-    pub authorized: bool,
+- Git first → Create placeholder, wait for event
-    pub reason: String,
-    pub state: Option<RepositoryState>,
-    pub maintainers: Vec<String>,
-    pub from_purgatory: bool,  // NEW: Track event source
-}
-```
-#### 2. Enhanced [`get_authorization_for_owner()`](../../src/git/authorization.rs:342)
+**Solution:** `PrPurgatoryEntry.event: Option<Event>` with `None` = placeholder.
-Added purgatory checking when no state found in database:
+### 4. Sync Queue Debouncing
-```rust
+When events arrive in bursts (e.g., negentropy sync), we don't want to spawn a sync task for each event.
-pub async fn get_authorization_for_owner(
-    database: &SharedDatabase,
-    identifier: &str,
-    owner_pubkey: &str,
-    purgatory: Option<&Arc<Purgatory>>,
-    pushed_refs: &[(String, String, String)],
-    repo_path: &Path,
-) -> Result<AuthorizationResult>
-```
-**Logic**:
+**Solution:** `enqueue_sync()` resets `attempt_count` and updates `next_attempt` if already queued.
-1. Check database for state events (existing behavior)
-2. If no state in database AND purgatory available:
-   - Parse pushed refs to RefPairs
-   - Get local refs from repository  
-   - Call [`find_matching_states()`](../../src/purgatory/mod.rs:203)
-   - Filter to latest event from authorized authors
-   - Return authorization with `from_purgatory: true`
-#### 3. Post-Push Purgatory Event Save
+### 5. Domain Throttling with Queues
-In [`handle_receive_pack()`](../../src/git/handlers.rs:187), after successful push:
+When a domain is throttled, we still want to eventually sync from it.
-```rust
+**Solution:** `ThrottleManager` maintains per-domain queues and processes them when capacity frees.
-if from_purgatory {
-    if let (Some(db), Some(purg)) = (&database, &purgatory) {
-        // Save state event to database
-        db.save_event(&state.event).await?;
-        
-        // Remove from purgatory
-        purg.remove_state_event(identifier, &state.event.id);
-    }
-}
-```
-### Files Modified
+---
-1. **[`src/git/authorization.rs`](../../src/git/authorization.rs)**
-   - Added `from_purgatory` field to `AuthorizationResult`
-   - Modified `get_authorization_for_owner()` signature and logic
-   - Added purgatory checking when database has no state
-2. **[`src/git/handlers.rs`](../../src/git/handlers.rs)**
-   - Modified `authorize_push()` to accept purgatory and repo_path parameters
-   - Added tracking of `from_purgatory` flag
-   - Added post-push database save for purgatory events
-### Why This Order Matters
-Checking purgatory DURING authorization (before push execution) is critical:
- **Prevents deadlock**: Push is authorized by purgatory state before execution
- **Maintains atomicity**: Only saves to database after successful push
- **Race condition safe**: First successful push claims the purgatory event
-The alternative (checking purgatory after push) creates an insurmountable deadlock where valid pushes are rejected because their authorizing state is in purgatory instead of the database.
-### Testing
+## Related Documentation
-The fix enables the `test_push_authorized_by_owner_state` integration test scenario where:
+- [Inline Authorization](inline-authorization.md) - Why purgatory checking during authorization is essential
-1. State event is sent to relay (goes to purgatory - no git data yet)
+- [Architecture Overview](architecture.md) - Full system design
-2. Git push is sent (uses purgatory state for authorization)
+- [Background Sync](../how-to/purgatory-sync.md) - How to configure and monitor sync
-3. State event is released from purgatory to database
+- [Test Strategy](../reference/test-strategy.md) - How we test purgatory
 ---
+*Part of the [ngit-grasp explanation docs](./)*
diff --git a/docs/explanation/purgatory-sync-redesign.md b/docs/explanation/purgatory-sync-redesign.md
deleted file mode 100644
index 629c2ff..0000000
--- a/docs/explanation/purgatory-sync-redesign.md
+++ /dev/null
@@ -1,1959 +0,0 @@
-# Purgatory Sync Redesign
-## Status
-**Proposed** - January 2026
-## Context
-The current purgatory sync implementation (`start_state_sync` at `src/purgatory/mod.rs:510`) has several limitations:
-1. **Per-event syncing**: Each state event triggers its own independent sync operation
-2. **No PR event syncing**: PR events enter purgatory but don't trigger git data fetching
-3. **No batching**: Multiple events for the same repository cause redundant fetch requests
-4. **No rate limiting**: Can overwhelm remote git servers or get rate-limited
-5. **No coordination**: Multiple concurrent syncs may fetch the same OIDs
-When syncing a new repository, we often receive multiple state and PR events in a burst. The current approach creates unnecessary load on remote servers and doesn't handle this common case efficiently.
-## Decision
-Redesign purgatory sync to be **identifier-based** rather than **event-based**, with:
-1. A background sync loop that processes identifiers, not individual events
-2. Batched OID fetching across all purgatory events for an identifier
-3. Domain-based throttling (30 requests/minute per domain)
-4. Exponential backoff per identifier (20s → 2m, then 2m intervals)
-5. Debouncing for burst event arrivals (500ms for sync-triggered, 3min default)
-6. **Clean separation of concerns**: Domain throttle handles rate limiting only; sync logic tracks its own tried URLs
-### Key Design Decision: Where Does OID Copying Happen?
-**Answer: In `process_newly_available_git_data`, NOT after the entire sync completes.**
-The current implementation (`sync_state_git_data`) fetches all OIDs first, then at the end:
-1. Copies OIDs to all authorized owner repos
-2. Aligns refs with state
-3. Saves to database
-4. Notifies subscribers
-5. Removes from purgatory
-The redesign moves all of this into `process_newly_available_git_data`, which is called after **each successful URL fetch**. This enables:
-| Aspect | Current (end-of-sync) | Redesign (per-fetch) |
-|--------|----------------------|---------------------|
-| **When events release** | Only after all URLs tried | As soon as OIDs available |
-| **Partial success** | All or nothing per event | Events release independently |
-| **Multiple state events** | All wait for slowest | Each releases when ready |
-| **Authorization check** | Once at start | At release time (handles changes) |
-**Why this matters:**
-Consider syncing an identifier with 3 state events from different maintainers:
- State A needs OIDs from `server1.com` (fast)
- State B needs OIDs from `server2.com` (slow)  
- State C needs OIDs from `server3.com` (down)
-With the redesign:
-1. Fetch from `server1.com` succeeds → `process_newly_available_git_data` releases State A immediately
-2. Fetch from `server2.com` succeeds → `process_newly_available_git_data` releases State B
-3. Fetch from `server3.com` fails → State C stays in purgatory, retries with backoff
-The current implementation would wait for all servers before releasing any events.
-### Unified Processing with Git Push Handler
-**Key insight**: The post-git-data-available processing is identical whether data arrives via:
- A successful `git push` (handle_receive_pack)
- Purgatory sync fetching OIDs from remote servers
-Both paths need to:
-1. Discover satisfiable events from purgatory
-2. Sync OIDs to authorized owner repos
-3. Align refs (+ set HEAD)
-4. Save events to database
-5. Notify WebSocket subscribers
-6. Remove from purgatory
-Rather than duplicate this logic, we use a single unified function `process_newly_available_git_data` that handles all post-git-data-available processing. See [Unified Git Data Sync](unify-git-data-sync.md) for the complete design.
-This means:
- **`handle_receive_pack`** calls `process_newly_available_git_data` after git push succeeds
- **`sync_identifier_from_url`** calls `process_newly_available_git_data` after OID fetch succeeds
- **Same behavior** regardless of how git data arrived
-## Architecture
-### Overview
-```
-┌──────────────────────────────────────────────────────────────────────────────────┐
-│                                  Purgatory                                        │
-│                                                                                   │
-│  ┌─────────────────┐  ┌─────────────────┐                                         │
-│  │  State Events   │  │   PR Events     │                                         │
-│  │  (by identifier)│  │  (by event_id)  │                                         │
-│  └────────┬────────┘  └────────┬────────┘                                         │
-│           │                    │                                                  │
-│           └──────────┬─────────┘                                                  │
-│                      │ add_state() / add_pr() / trigger_immediate_sync()          │
-│                      ▼                                                            │
-│           ┌──────────────────────────┐                                            │
-│           │      Sync Queue          │                                            │
-│           │  DashMap<id, Entry>      │                                            │
-│           │                          │                                            │
-│           │  Entry {                 │                                            │
-│           │    next_attempt,         │  ← delay/backoff timer                     │
-│           │    attempt_count,        │  ← for backoff calculation                 │
-│           │    in_progress,          │  ← prevents concurrent runs                │
-│           │  }                       │                                            │
-│           └────────────┬─────────────┘                                            │
-│                        │                                                          │
-│  ┌─────────────────────┼──────────────────────────────────────────────────────┐   │
-│  │                     ▼                                                      │   │
-│  │          ┌─────────────────────┐                                           │   │
-│  │          │   Main Sync Loop    │  (every 1s)                               │   │
-│  │          │                     │                                           │   │
-│  │          │  1. Find ALL ready  │                                           │   │
-│  │          │     identifiers     │                                           │   │
-│  │          │  2. Spawn parallel  │───────┐                                   │   │
-│  │          │     tasks for each  │       │  (parallel tasks)                 │   │
-│  │          │  3. Apply backoff   │       │                                   │   │
-│  │          │     when done       │       │                                   │   │
-│  │          └─────────────────────┘       │                                   │   │
-│  │                                        ▼                                   │   │
-│  │                             ┌──────────────────────────────────────────┐   │   │
-│  │                             │       sync_identifier()                  │   │   │
-│  │                             │                                          │   │   │
-│  │                             │  Owns its own tried_urls: HashSet        │   │   │
-│  │                             │                                          │   │   │
-│  │                             │  loop:                                   │   │   │
-│  │                             │    url = sync_identifier_next_url(       │   │   │
-│  │                             │            domain=None)                  │   │   │
-│  │                             │    if url is Some:                       │   │   │
-│  │                             │      sync_identifier_from_url(url)       │   │   │
-│  │                             │      tried_urls.insert(url)              │   │   │
-│  │                             │    else:                                 │   │   │
-│  │                             │      break (no non-throttled URLs left)  │   │   │
-│  │                             │                                          │   │   │
-│  │                             │  Enqueue throttled domains then return   │   │   │
-│  │                             └──────────────────────────────────────────┘   │   │
-│  │                                        │                                   │   │
-│  │                                        │ enqueue_identifier()              │   │
-│  │                                        ▼                                   │   │
-│  │  ┌─────────────────────────────────────────────────────────────────────┐   │   │
-│  │  │                        ThrottleManager                              │   │   │
-│  │  │                                                                     │   │   │
-│  │  │   DashMap<domain, DomainThrottle>                                   │   │   │
-│  │  │                                                                     │   │   │
-│  │  │   ┌─────────────────────────────────────────────────────────────┐   │   │   │
-│  │  │   │  DomainThrottle (per domain)                                │   │   │   │
-│  │  │   │                                                             │   │   │   │
-│  │  │   │  Rate limiting:           │  Queue (IndexMap for ordering): │   │   │   │
-│  │  │   │    - in_flight: u32       │    - queue: IndexMap<id, State> │   │   │   │
-│  │  │   │    - request_times        │    - State: tried_urls,         │   │   │   │
-│  │  │   │    - round_robin_index    │             in_progress         │   │   │   │
-│  │  │   └─────────────────────────────────────────────────────────────┘   │   │   │
-│  │  │                                                                     │   │   │
-│  │  │   Trigger-based processing (no polling loop):                       │   │   │
-│  │  │     - enqueue_identifier() triggers if capacity available           │   │   │
-│  │  │     - complete_request() triggers next item if capacity available   │   │   │
-│  │  │                                                                     │   │   │
-│  │  │   process_queued_identifier():                                      │   │   │
-│  │  │     1. Pick next identifier (round-robin, not in_progress)          │   │   │
-│  │  │     2. url = sync_identifier_next_url(domain=Some(this_domain))     │   │   │
-│  │  │     3. If url: sync_identifier_from_url(url), mark tried            │   │   │
-│  │  │        Else: remove identifier from queue, try next                 │   │   │
-│  │  └─────────────────────────────────────────────────────────────────────┘   │   │
-│  │                                                                            │   │
-│  └────────────────────────────────────────────────────────────────────────────┘   │
-└───────────────────────────────────────────────────────────────────────────────────┘
-```
-### Key Design Principles
-**1. Two Independent Execution Paths**
-The main sync loop and DomainThrottle loops run independently:
- **Main sync**: Tries non-throttled URLs, completes quickly, applies backoff, retries later
- **DomainThrottle**: Processes queued identifiers when capacity frees, doesn't block main sync
-**2. Two Separate tried_urls Tracking**
-Each path tracks its own tried URLs:
- **sync_identifier**: Local `HashSet<String>` for current attempt (all domains)
- **DomainThrottle**: Per-identifier `HashSet<String>` for URLs tried via throttle (this domain only)
-These don't need to merge because:
- Main sync skips throttled domains anyway
- DomainThrottle only processes its own domain's URLs
-**3. Shared Functions**
-Both paths use the same core functions:
- **`sync_identifier_next_url`**: Pure URL selection logic
- **`sync_identifier_from_url`**: Pure fetch logic
-The `domain` parameter determines behavior:
- `None`: Return any non-throttled URL
- `Some(domain)`: Return URL from that specific domain only
-### Flow Summary
-1. **Event arrives** → added to state_events/pr_events + sync_queue with delay
-   - User-submitted: 3 minute delay (expect git push to follow)
-   - Sync-triggered: 500ms delay (batch burst arrivals)
-   - `enqueue_sync()` resets `attempt_count` to 0 and updates `next_attempt` if needed
-2. **Main sync loop** (every 1s):
-   - Finds ALL ready identifiers (where `!in_progress && next_attempt <= now`)
-   - Spawns parallel tasks for each (marks `in_progress = true`)
-   - Each `sync_identifier()` task:
-     - Creates fresh `tried_urls: HashSet<String>`
-     - Loops calling `sync_identifier_next_url(domain=None)` + `sync_identifier_from_url`
-     - When no non-throttled URLs remain: enqueue with throttled domains, return
-   - When task completes: apply backoff or remove from queue
-3. **ThrottleManager / DomainThrottle** (trigger-based, no polling):
-   - Processing triggered by `enqueue_identifier()` or `complete_request()`
-   - When triggered and capacity available: pick next queued identifier (round-robin, not in_progress)
-   - Call `sync_identifier_next_url(domain=Some(this_domain))`
-   - If URL returned: call `sync_identifier_from_url`, mark URL tried, mark not in_progress
-   - If no URL: remove identifier from queue, try next identifier
-## Data Structures
-### SyncQueueEntry
-Tracks sync state for each identifier in the main sync queue:
-```rust
-/// Entry in the sync queue tracking when/how to sync an identifier
-#[derive(Debug, Clone)]
-pub struct SyncQueueEntry {
-    /// Don't attempt sync before this time
-    pub next_attempt: Instant,
-    
-    /// Number of sync attempts (for backoff calculation)
-    /// Reset to 0 when new event arrives for this identifier
-    pub attempt_count: u32,
-    
-    /// Whether a sync is currently in progress for this identifier
-    pub in_progress: bool,
-}
-impl SyncQueueEntry {
-    pub fn new(delay: Duration) -> Self {
-        Self {
-            next_attempt: Instant::now() + delay,
-            attempt_count: 0,
-            in_progress: false,
-        }
-    }
-    
-    /// Calculate backoff: 20s, 40s, 80s, 120s (capped at 2min)
-    pub fn backoff(&self) -> Duration {
-        let base = Duration::from_secs(20);
-        let multiplier = 2u32.saturating_pow(self.attempt_count.saturating_sub(1).min(3));
-        (base * multiplier).min(Duration::from_secs(120))
-    }
-    
-    pub fn is_ready(&self) -> bool {
-        !self.in_progress && Instant::now() >= self.next_attempt
-    }
-    
-    /// Called when new event arrives - resets attempt_count
-    pub fn on_new_event(&mut self, delay: Duration) {
-        self.attempt_count = 0;
-        let new_attempt = Instant::now() + delay;
-        if new_attempt < self.next_attempt {
-            self.next_attempt = new_attempt;
-        }
-    }
-    
-    /// Called when sync attempt completes
-    pub fn on_sync_complete(&mut self) {
-        self.in_progress = false;
-        if self.next_attempt <= Instant::now() {
-            self.attempt_count += 1;
-            self.next_attempt = Instant::now() + self.backoff();
-        }
-    }
-}
-```
-### ThrottleManager
-Manages all per-domain throttles and provides the interface for checking throttle status:
-```rust
-/// Manages rate limiting across all domains.
-/// 
-/// Owns a collection of DomainThrottle instances and provides:
-/// - Throttle status checking for sync_identifier_next_url
-/// - Identifier queue management
-/// - Trigger-based processing when capacity frees up
-pub struct ThrottleManager {
-    /// Per-domain throttle state
-    throttles: DashMap<String, DomainThrottle>,
-    
-    /// Sync context for processing queued identifiers
-    /// Set once at startup via set_context()
-    ctx: OnceLock<Arc<dyn SyncContext>>,
-    
-    /// Configuration
-    max_concurrent_per_domain: u32,
-    max_per_minute_per_domain: u32,
-}
-impl ThrottleManager {
-    pub fn new(max_concurrent: u32, max_per_minute: u32) -> Self {
-        Self {
-            throttles: DashMap::new(),
-            ctx: OnceLock::new(),
-            max_concurrent_per_domain: max_concurrent,
-            max_per_minute_per_domain: max_per_minute,
-        }
-    }
-    
-    /// Set the sync context (called once at startup)
-    pub fn set_context(&self, ctx: Arc<dyn SyncContext>) {
-        let _ = self.ctx.set(ctx);
-    }
-    
-    /// Check if a domain is currently throttled (at capacity)
-    pub fn is_throttled(&self, domain: &str) -> bool {
-        self.throttles
-            .get(domain)
-            .map_or(false, |t| !t.has_capacity())
-    }
-    
-    /// Get or create throttle for a domain
-    fn get_or_create(&self, domain: &str) -> dashmap::mapref::one::RefMut<String, DomainThrottle> {
-        self.throttles
-            .entry(domain.to_string())
-            .or_insert_with(|| DomainThrottle::new(
-                domain.to_string(),
-                self.max_concurrent_per_domain,
-                self.max_per_minute_per_domain,
-            ))
-    }
-    
-    /// Record that a request is starting for a domain
-    pub fn start_request(&self, domain: &str) {
-        self.get_or_create(domain).start_request();
-    }
-    
-    /// Record that a request completed for a domain.
-    /// Triggers processing of next queued identifier if capacity available.
-    pub fn complete_request(self: &Arc<Self>, domain: &str) {
-        let should_trigger = {
-            if let Some(mut throttle) = self.throttles.get_mut(domain) {
-                throttle.complete_request();
-                throttle.has_capacity() && throttle.has_queued_work()
-            } else {
-                false
-            }
-        };
-        
-        if should_trigger {
-            self.try_process_next(domain);
-        }
-    }
-    
-    /// Add an identifier to a domain's waiting queue.
-    /// Triggers processing if capacity is available.
-    pub fn enqueue_identifier(
-        self: &Arc<Self>,
-        domain: &str,
-        identifier: String,
-        tried_urls_for_domain: HashSet<String>,
-    ) {
-        let should_trigger = {
-            let mut throttle = self.get_or_create(domain);
-            throttle.enqueue_identifier(identifier, tried_urls_for_domain);
-            throttle.has_capacity()
-        };
-        
-        if should_trigger {
-            self.try_process_next(domain);
-        }
-    }
-    
-    /// Try to process the next queued identifier for a domain
-    fn try_process_next(self: &Arc<Self>, domain: &str) {
-        let identifier = {
-            if let Some(mut throttle) = self.throttles.get_mut(domain) {
-                throttle.next_ready_identifier()
-            } else {
-                None
-            }
-        };
-        
-        if let Some(identifier) = identifier {
-            let manager = self.clone();
-            let domain = domain.to_string();
-            
-            tokio::spawn(async move {
-                manager.process_queued_identifier(&domain, &identifier).await;
-            });
-        }
-    }
-    
-    /// Process a single identifier from a domain's queue
-    async fn process_queued_identifier(self: &Arc<Self>, domain: &str, identifier: &str) {
-        let ctx = match self.ctx.get() {
-            Some(ctx) => ctx,
-            None => return,
-        };
-        
-        // Get next URL for this identifier on this domain
-        let url = {
-            let throttle = match self.throttles.get(domain) {
-                Some(t) => t,
-                None => return,
-            };
-            let tried_urls = throttle.get_tried_urls(identifier);
-            
-            sync_identifier_next_url(
-                ctx.as_ref(),
-                identifier,
-                Some(domain),
-                &tried_urls,
-                self,
-            ).await
-        };
-        
-        match url {
-            Some(url) => {
-                // Fetch from this URL (this calls start_request/complete_request internally)
-                sync_identifier_from_url(ctx.as_ref(), identifier, &url, self).await;
-                
-                // Record URL as tried and mark not in_progress
-                // complete_request() will trigger next item if capacity available
-                if let Some(mut throttle) = self.throttles.get_mut(domain) {
-                    throttle.mark_url_tried(identifier, url);
-                    throttle.mark_identifier_not_in_progress(identifier);
-                }
-            }
-            None => {
-                // No more URLs for this identifier on this domain - remove from queue
-                if let Some(mut throttle) = self.throttles.get_mut(domain) {
-                    throttle.remove_identifier(identifier);
-                }
-                // Try next identifier since we didn't use any capacity
-                self.try_process_next(domain);
-            }
-        }
-    }
-}
-```
-### DomainThrottle
-Per-domain rate limiting and waiting queue:
-```rust
-/// Per-domain rate limiting and identifier queue.
-/// 
-/// Handles:
-/// - Rate limiting (concurrent requests, requests per minute)
-/// - Queue of identifiers waiting for capacity (using IndexMap for round-robin order)
-/// - Tracking tried URLs per identifier (for this domain only)
-/// - In-progress flag per identifier (prevents concurrent fetches for same identifier
-///   on this domain, important when queue is small and we have multiple concurrent slots)
-pub struct DomainThrottle {
-    /// Domain this throttle manages
-    domain: String,
-    
-    /// Current in-flight request count
-    in_flight: u32,
-    
-    /// Request timestamps (sliding window for rate limiting)
-    request_times: VecDeque<Instant>,
-    
-    /// Queued identifiers with their state.
-    /// IndexMap preserves insertion order for round-robin processing.
-    queue: IndexMap<String, IdentifierQueueState>,
-    
-    /// Round-robin index for fair processing across identifiers
-    round_robin_index: usize,
-    
-    /// Configuration
-    max_concurrent: u32,
-    max_per_minute: u32,
-}
-/// State for an identifier waiting in a domain's queue
-#[derive(Debug, Clone)]
-struct IdentifierQueueState {
-    /// URLs from this domain that have been tried
-    tried_urls: HashSet<String>,
-    
-    /// Whether a fetch is currently in progress for this identifier on this domain.
-    /// Prevents starting multiple concurrent fetches for the same identifier,
-    /// which is important when the queue is small (e.g., 2 identifiers with 5 
-    /// concurrent slots would otherwise try to process the same identifier multiple times).
-    in_progress: bool,
-}
-impl DomainThrottle {
-    pub fn new(domain: String, max_concurrent: u32, max_per_minute: u32) -> Self {
-        Self {
-            domain,
-            in_flight: 0,
-            request_times: VecDeque::new(),
-            queue: IndexMap::new(),
-            round_robin_index: 0,
-            max_concurrent,
-            max_per_minute,
-        }
-    }
-    
-    /// Check if domain has capacity for another request
-    pub fn has_capacity(&self) -> bool {
-        if self.in_flight >= self.max_concurrent {
-            return false;
-        }
-        
-        let now = Instant::now();
-        let window = Duration::from_secs(60);
-        let recent_count = self.request_times
-            .iter()
-            .filter(|t| now.duration_since(**t) < window)
-            .count();
-        
-        recent_count < self.max_per_minute as usize
-    }
-    
-    /// Check if there are any identifiers in the queue
-    pub fn has_queued_work(&self) -> bool {
-        !self.queue.is_empty()
-    }
-    
-    /// Record that a request is starting
-    pub fn start_request(&mut self) {
-        self.in_flight += 1;
-        self.request_times.push_back(Instant::now());
-    }
-    
-    /// Record that a request completed
-    pub fn complete_request(&mut self) {
-        self.in_flight = self.in_flight.saturating_sub(1);
-        
-        // Clean old timestamps
-        let now = Instant::now();
-        let window = Duration::from_secs(60);
-        while self.request_times.front().map_or(false, |t| now.duration_since(*t) >= window) {
-            self.request_times.pop_front();
-        }
-    }
-    
-    /// Add an identifier to the queue
-    pub fn enqueue_identifier(&mut self, identifier: String, tried_urls: HashSet<String>) {
-        self.queue
-            .entry(identifier)
-            .and_modify(|state| {
-                // Merge tried_urls if already exists
-                state.tried_urls.extend(tried_urls.iter().cloned());
-            })
-            .or_insert(IdentifierQueueState {
-                tried_urls,
-                in_progress: false,
-            });
-    }
-    
-    /// Get next identifier ready for processing (round-robin, not in_progress).
-    /// 
-    /// Iterates through the queue starting from round_robin_index, skipping
-    /// any identifiers that are already in_progress. This ensures fair
-    /// distribution even when some identifiers have active fetches.
-    pub fn next_ready_identifier(&mut self) -> Option<String> {
-        let len = self.queue.len();
-        if len == 0 {
-            return None;
-        }
-        
-        // Try each identifier starting from round_robin_index
-        for i in 0..len {
-            let index = (self.round_robin_index + i) % len;
-            if let Some((identifier, state)) = self.queue.get_index_mut(index) {
-                if !state.in_progress {
-                    state.in_progress = true;
-                    self.round_robin_index = (index + 1) % len;
-                    return Some(identifier.clone());
-                }
-            }
-        }
-        
-        None // All identifiers are in_progress
-    }
-    
-    /// Get tried URLs for an identifier
-    pub fn get_tried_urls(&self, identifier: &str) -> HashSet<String> {
-        self.queue
-            .get(identifier)
-            .map(|s| s.tried_urls.clone())
-            .unwrap_or_default()
-    }
-    
-    /// Mark a URL as tried for an identifier
-    pub fn mark_url_tried(&mut self, identifier: &str, url: String) {
-        if let Some(state) = self.queue.get_mut(identifier) {
-            state.tried_urls.insert(url);
-        }
-    }
-    
-    /// Mark identifier as not in progress (fetch completed)
-    pub fn mark_identifier_not_in_progress(&mut self, identifier: &str) {
-        if let Some(state) = self.queue.get_mut(identifier) {
-            state.in_progress = false;
-        }
-    }
-    
-    /// Remove an identifier from the queue entirely
-    pub fn remove_identifier(&mut self, identifier: &str) {
-        if let Some((index, _, _)) = self.queue.shift_remove_full(identifier) {
-            // Adjust round_robin_index if we removed an entry before it
-            if index < self.round_robin_index && self.round_robin_index > 0 {
-                self.round_robin_index -= 1;
-            }
-            // Clamp to valid range
-            if !self.queue.is_empty() {
-                self.round_robin_index = self.round_robin_index % self.queue.len();
-            } else {
-                self.round_robin_index = 0;
-            }
-        }
-    }
-}
-```
-### SyncContext Trait (For Testability)
-Abstract the external dependencies to enable unit testing:
-```rust
-/// Abstraction over external dependencies for sync operations.
-/// 
-/// This trait allows unit testing of sync logic by mocking:
-/// - Repository data fetching
-/// - OID existence checks
-/// - Git fetch operations
-/// - Event processing
-#[async_trait]
-pub trait SyncContext: Send + Sync {
-    /// Get repository data (announcements, clone URLs, etc.)
-    async fn fetch_repository_data(&self, identifier: &str) -> Result<RepositoryData>;
-    
-    /// Get all OIDs needed for purgatory events with this identifier
-    fn collect_needed_oids(&self, identifier: &str) -> HashSet<String>;
-    
-    /// Check if an OID exists locally
-    fn oid_exists(&self, repo_path: &Path, oid: &str) -> bool;
-    
-    /// Fetch OIDs from a remote server
-    async fn fetch_oids(&self, repo_path: &Path, url: &str, oids: &[String]) -> Result<Vec<String>>;
-    
-    /// Process newly available git data.
-    /// 
-    /// This is a thin wrapper around the unified `process_newly_available_git_data` function.
-    /// Called after each successful OID fetch to check if any purgatory events can now be satisfied.
-    /// 
-    /// See [Unified Git Data Sync](unify-git-data-sync.md) for the complete design.
-    async fn process_newly_available_git_data(
-        &self,
-        source_repo_path: &Path,
-        new_oids: &HashSet<String>,
-    ) -> Result<ProcessResult>;
-    
-    /// Check if there are still pending events for this identifier
-    fn has_pending_events(&self, identifier: &str) -> bool;
-    
-    /// Find the best local repo to fetch into
-    fn find_target_repo(&self, db_repo_data: &RepositoryData) -> Option<PathBuf>;
-    
-    /// Our domain (to exclude from clone URLs)
-    fn our_domain(&self) -> Option<&str>;
-}
-/// Real implementation of SyncContext with all dependencies
-pub struct RealSyncContext {
-    purgatory: Purgatory,
-    database: SharedDatabase,
-    git_data_path: PathBuf,
-    our_domain: Option<String>,
-    local_relay: Option<nostr_relay_builder::LocalRelay>,
-}
-impl RealSyncContext {
-    pub fn new(
-        purgatory: Purgatory,
-        database: SharedDatabase,
-        git_data_path: PathBuf,
-        our_domain: Option<String>,
-        local_relay: Option<nostr_relay_builder::LocalRelay>,
-    ) -> Self {
-        Self {
-            purgatory,
-            database,
-            git_data_path,
-            our_domain,
-            local_relay,
-        }
-    }
-}
-#[async_trait]
-impl SyncContext for RealSyncContext {
-    // ... other methods ...
-    
-    async fn process_newly_available_git_data(
-        &self,
-        source_repo_path: &Path,
-        new_oids: &HashSet<String>,
-    ) -> Result<ProcessResult> {
-        // Call the unified function that handles all post-git-data-available processing
-        // This is the same function called by handle_receive_pack after a git push
-        crate::git::process_newly_available_git_data(
-            source_repo_path,
-            new_oids,
-            &self.database,
-            self.local_relay.as_ref(),
-            &self.purgatory,
-            &self.git_data_path,
-        ).await
-    }
-    
-    // ... other methods ...
-}
-```
-**Note**: The `SyncContext` trait abstracts away the dependencies for testability. The real implementation (`RealSyncContext`) holds references to purgatory, database, etc., and the `process_newly_available_git_data` method delegates to the unified function. This keeps the sync logic functions (`sync_identifier_next_url`, `sync_identifier_from_url`) clean and testable with mocks.
-## Core Sync Logic
-### Two-Function Design
-The sync logic is split into two functions that can be called by either the main sync loop or by DomainThrottle:
-1. **`sync_identifier_next_url`**: Pure selection logic - finds next URL to try
-2. **`sync_identifier_from_url`**: Pure fetch logic - fetches from a specific URL
-This separation enables:
- Main sync loop to try non-throttled URLs immediately
- DomainThrottle to process queued identifiers when capacity frees
- Clean testability with mocked SyncContext
-### Helper: extract_domain
-```rust
-/// Extract domain from a URL (e.g., "https://github.com/foo/bar.git" → "github.com")
-fn extract_domain(url: &str) -> Option<String> {
-    url::Url::parse(url)
-        .ok()
-        .and_then(|u| u.host_str().map(|s| s.to_string()))
-}
-```
-### sync_identifier_next_url
-```rust
-/// Find the next URL to try for an identifier.
-/// 
-/// When `domain` is None: returns any non-throttled URL not in tried_urls
-/// When `domain` is Some: returns a URL from that specific domain not in tried_urls
-/// 
-/// Returns None if:
-/// - No pending events for this identifier
-/// - No OIDs needed (sync complete)
-/// - No untried URLs available (for the specified domain or all domains)
-/// - All available domains are throttled (when domain is None)
-pub async fn sync_identifier_next_url<C: SyncContext>(
-    ctx: &C,
-    identifier: &str,
-    domain: Option<&str>,
-    tried_urls: &HashSet<String>,
-    throttle_manager: &ThrottleManager,
-) -> Option<String> {
-    // 1. Check if we still have pending events
-    if !ctx.has_pending_events(identifier) {
-        return None;
-    }
-    
-    // 2. Collect needed OIDs
-    let needed_oids = ctx.collect_needed_oids(identifier);
-    if needed_oids.is_empty() {
-        // No OIDs needed - sync is complete
-        return None;
-    }
-    
-    // 3. Get repository data
-    let repo_data = match ctx.fetch_repository_data(identifier).await {
-        Ok(data) => data,
-        Err(_) => return None,
-    };
-    
-    // 4. Collect clone URLs, excluding our domain
-    let all_urls: Vec<String> = repo_data
-        .announcements
-        .iter()
-        .flat_map(|a| a.clone_urls.iter().cloned())
-        .filter(|url| ctx.our_domain().map_or(true, |d| !url.contains(d)))
-        .collect::<HashSet<_>>()
-        .into_iter()
-        .collect();
-    
-    // 5. Group by domain
-    let urls_by_domain: HashMap<String, Vec<String>> = all_urls
-        .iter()
-        .fold(HashMap::new(), |mut acc, url| {
-            if let Some(d) = extract_domain(url) {
-                acc.entry(d).or_default().push(url.clone());
-            }
-            acc
-        });
-    
-    // 6. Find an available URL
-    match domain {
-        Some(specific_domain) => {
-            // Only look at URLs from this specific domain
-            urls_by_domain
-                .get(specific_domain)
-                .and_then(|urls| {
-                    urls.iter()
-                        .find(|url| !tried_urls.contains(*url))
-                        .cloned()
-                })
-        }
-        None => {
-            // Try any non-throttled domain
-            for (d, domain_urls) in &urls_by_domain {
-                if throttle_manager.is_throttled(d) {
-                    continue;
-                }
-                if let Some(url) = domain_urls.iter().find(|url| !tried_urls.contains(*url)) {
-                    return Some(url.clone());
-                }
-            }
-            None
-        }
-    }
-}
-/// Information about throttled domains with untried URLs
-#[derive(Debug, Clone)]
-pub struct ThrottledDomainInfo {
-    pub domain: String,
-    pub tried_urls_for_domain: HashSet<String>,
-}
-/// Get information about throttled domains that have untried URLs.
-/// 
-/// Called by main sync loop to know which DomainThrottle queues to add the identifier to.
-pub async fn get_throttled_domains_with_untried_urls<C: SyncContext>(
-    ctx: &C,
-    identifier: &str,
-    tried_urls: &HashSet<String>,
-    throttle_manager: &ThrottleManager,
-) -> Vec<ThrottledDomainInfo> {
-    let repo_data = match ctx.fetch_repository_data(identifier).await {
-        Ok(data) => data,
-        Err(_) => return vec![],
-    };
-    
-    let all_urls: Vec<String> = repo_data
-        .announcements
-        .iter()
-        .flat_map(|a| a.clone_urls.iter().cloned())
-        .filter(|url| ctx.our_domain().map_or(true, |d| !url.contains(d)))
-        .collect::<HashSet<_>>()
-        .into_iter()
-        .collect();
-    
-    let urls_by_domain: HashMap<String, Vec<String>> = all_urls
-        .iter()
-        .fold(HashMap::new(), |mut acc, url| {
-            if let Some(d) = extract_domain(url) {
-                acc.entry(d).or_default().push(url.clone());
-            }
-            acc
-        });
-    
-    urls_by_domain
-        .into_iter()
-        .filter_map(|(domain, domain_urls)| {
-            if !throttle_manager.is_throttled(&domain) {
-                return None; // Not throttled, skip
-            }
-            
-            let untried: Vec<_> = domain_urls
-                .iter()
-                .filter(|url| !tried_urls.contains(*url))
-                .collect();
-            
-            if untried.is_empty() {
-                return None; // All URLs tried for this domain
-            }
-            
-            // Collect tried URLs that belong to this domain
-            let tried_urls_for_domain: HashSet<String> = tried_urls
-                .iter()
-                .filter(|url| extract_domain(url).as_deref() == Some(&domain))
-                .cloned()
-                .collect();
-            
-            Some(ThrottledDomainInfo {
-                domain,
-                tried_urls_for_domain,
-            })
-        })
-        .collect()
-}
-```
-### sync_identifier_from_url
-```rust
-/// Fetch git data from a specific URL for an identifier.
-/// 
-/// This function:
-/// 1. Records the request with the throttle manager
-/// 2. Performs the actual git fetch
-/// 3. Processes any events that can now be satisfied
-/// 4. Records request completion
-/// 
-/// Returns the number of OIDs successfully fetched.
-pub async fn sync_identifier_from_url<C: SyncContext>(
-    ctx: &C,
-    identifier: &str,
-    url: &str,
-    throttle_manager: &Arc<ThrottleManager>,
-) -> usize {
-    let domain = match extract_domain(url) {
-        Some(d) => d,
-        None => return 0,
-    };
-    
-    // Get repository data for target repo path
-    let repo_data = match ctx.fetch_repository_data(identifier).await {
-        Ok(data) => data,
-        Err(e) => {
-            tracing::debug!(identifier = %identifier, error = %e, "Failed to fetch repo data");
-            return 0;
-        }
-    };
-    
-    let target_repo = match ctx.find_target_repo(&repo_data) {
-        Some(path) => path,
-        None => {
-            tracing::debug!(identifier = %identifier, "No target repo found");
-            return 0;
-        }
-    };
-    
-    // Collect needed OIDs
-    let needed_oids: Vec<String> = ctx.collect_needed_oids(identifier).into_iter().collect();
-    if needed_oids.is_empty() {
-        return 0;
-    }
-    
-    // Perform the fetch
-    throttle_manager.start_request(&domain);
-    let fetch_result = ctx.fetch_oids(&target_repo, url, &needed_oids).await;
-    throttle_manager.complete_request(&domain);
-    
-    let oids_fetched = match fetch_result {
-        Ok(fetched) => {
-            tracing::debug!(
-                identifier = %identifier,
-                url = %url,
-                oids_fetched = fetched.len(),
-                "Fetch succeeded"
-            );
-            fetched.len()
-        }
-        Err(e) => {
-            tracing::debug!(
-                identifier = %identifier,
-                url = %url,
-                error = %e,
-                "Fetch failed"
-            );
-            0
-        }
-    };
-    
-    // Try to process any events that can now be satisfied
-    if oids_fetched > 0 {
-        let new_oids: HashSet<String> = needed_oids.iter().cloned().collect();
-        if let Err(e) = ctx.process_newly_available_git_data(&target_repo, &new_oids).await {
-            tracing::warn!(
-                identifier = %identifier,
-                error = %e,
-                "Failed to process newly available git data"
-            );
-        }
-    }
-    
-    oids_fetched
-}
-```
-### process_newly_available_git_data (Unified Function)
-This is the core function that handles the "release from purgatory" logic. It's called after each successful fetch to check if any purgatory events can now be satisfied with the available git data.
-**Key Design Decision**: This is a **unified function** shared with the git push handler. Both `handle_receive_pack` (after git push) and `sync_identifier_from_url` (after purgatory sync fetch) call the same function. See [Unified Git Data Sync](unify-git-data-sync.md) for the complete implementation.
-**Why unify?**
-The post-git-data-available processing is identical regardless of how data arrived:
-| Step | After git push | After purgatory fetch |
-|------|---------------|----------------------|
-| Discover satisfiable events | ✅ Same | ✅ Same |
-| Sync OIDs to owner repos | ✅ Same | ✅ Same |
-| Align refs (+ set HEAD) | ✅ Same | ✅ Same |
-| Save events to database | ✅ Same | ✅ Same |
-| Notify WebSocket | ✅ Same | ✅ Same |
-| Remove from purgatory | ✅ Same | ✅ Same |
-```rust
-/// Result of processing newly available git data
-#[derive(Debug, Default)]
-pub struct ProcessResult {
-    /// Number of state events released from purgatory
-    pub states_released: usize,
-    /// Number of PR events released from purgatory
-    pub prs_released: usize,
-    /// Number of repositories synced (OIDs copied + refs aligned)
-    pub repos_synced: usize,
-    /// Number of refs created/updated/deleted
-    pub refs_created: usize,
-    pub refs_updated: usize,
-    pub refs_deleted: usize,
-    /// Errors encountered (non-fatal)
-    pub errors: Vec<String>,
-}
-/// Unified processing of newly available git data.
-///
-/// Called whenever git data becomes available, whether from:
-/// - A successful `git push` (handle_receive_pack)
-/// - Purgatory sync fetching OIDs from remote servers
-///
-/// See unify-git-data-sync.md for complete implementation details.
-pub async fn process_newly_available_git_data(
-    source_repo_path: &Path,
-    new_oids: &HashSet<String>,
-    database: &SharedDatabase,
-    local_relay: Option<&nostr_relay_builder::LocalRelay>,
-    purgatory: &Purgatory,
-    git_data_path: &Path,
-) -> Result<ProcessResult>;
-```
-**Key properties of the unified function:**
-1. **Early release**: If we fetch from `server1.com` and get all OIDs for state event A, we immediately release A even if state event B still needs OIDs from `server2.com`
-2. **Idempotent**: The function can be called multiple times safely. It only processes events that are actually satisfiable.
-3. **Atomic per-event**: Each event is processed independently. If saving one event fails, others can still succeed.
-4. **Authorization at release time**: We check authorization when releasing, not when adding to purgatory. This handles the case where maintainer sets change while an event is in purgatory.
-5. **Handles all event types**: Both state events (kind 30618) and PR events (kind 1617/1618) are processed uniformly.
-### The Sync Identifier Loop (Main Sync)
-```rust
-/// Sync git data for an identifier.
-/// 
-/// This is called by the main sync loop. It:
-/// 1. Tries all non-throttled URLs
-/// 2. Enqueues with throttled domains for later processing
-/// 3. Returns without waiting for throttled domains
-/// 
-/// Returns true if sync completed (no pending events or no OIDs needed),
-/// false if events remain (will be retried after backoff).
-pub async fn sync_identifier<C: SyncContext>(
-    ctx: &C,
-    identifier: &str,
-    throttle_manager: &Arc<ThrottleManager>,
-) -> bool {
-    let mut tried_urls: HashSet<String> = HashSet::new();
-    
-    // Try all non-throttled URLs
-    loop {
-        match sync_identifier_next_url(
-            ctx,
-            identifier,
-            None, // Any domain
-            &tried_urls,
-            throttle_manager,
-        ).await {
-            Some(url) => {
-                // Found a non-throttled URL to try
-                sync_identifier_from_url(ctx, identifier, &url, throttle_manager).await;
-                tried_urls.insert(url);
-                
-                // Check if sync is now complete
-                if !ctx.has_pending_events(identifier) {
-                    tracing::info!(identifier = %identifier, "Sync complete - no pending events");
-                    return true;
-                }
-                
-                let needed_oids = ctx.collect_needed_oids(identifier);
-                if needed_oids.is_empty() {
-                    tracing::info!(identifier = %identifier, "Sync complete - all OIDs available");
-                    return true;
-                }
-                
-                // Continue trying more URLs
-            }
-            None => {
-                // No more non-throttled URLs available
-                break;
-            }
-        }
-    }
-    
-    // Check if we're done (no pending events or no needed OIDs)
-    if !ctx.has_pending_events(identifier) {
-        return true;
-    }
-    
-    let needed_oids = ctx.collect_needed_oids(identifier);
-    if needed_oids.is_empty() {
-        return true;
-    }
-    
-    // Enqueue with any throttled domains that have untried URLs
-    let throttled_domains = get_throttled_domains_with_untried_urls(
-        ctx,
-        identifier,
-        &tried_urls,
-        throttle_manager,
-    ).await;
-    
-    for info in throttled_domains {
-        tracing::debug!(
-            identifier = %identifier,
-            domain = %info.domain,
-            "Enqueueing with throttled domain"
-        );
-        throttle_manager.enqueue_identifier(
-            &info.domain,
-            identifier.to_string(),
-            info.tried_urls_for_domain,
-        );
-    }
-    
-    // Return false - events remain, will retry after backoff
-    // (throttled domains will process independently)
-    false
-}
-```
-### The Main Sync Loop
-```rust
-impl Purgatory {
-    pub fn start_sync_loop(
-        self: Arc<Self>,
-        database: SharedDatabase,
-        our_domain: Option<String>,
-        local_relay: Option<nostr_relay_builder::LocalRelay>,
-        throttle_manager: Arc<ThrottleManager>,
-    ) -> tokio::task::JoinHandle<()> {
-        tokio::spawn(async move {
-            let mut interval = tokio::time::interval(Duration::from_secs(1));
-            
-            loop {
-                interval.tick().await;
-                
-                // Find all ready identifiers
-                let ready: Vec<String> = self.sync_queue
-                    .iter()
-                    .filter(|e| e.value().is_ready())
-                    .map(|e| e.key().clone())
-                    .collect();
-                
-                for identifier in ready {
-                    // Check if events still exist
-                    if !self.has_pending_events(&identifier) {
-                        self.sync_queue.remove(&identifier);
-                        continue;
-                    }
-                    
-                    // Mark in progress
-                    if let Some(mut entry) = self.sync_queue.get_mut(&identifier) {
-                        if entry.in_progress {
-                            continue;
-                        }
-                        entry.in_progress = true;
-                    } else {
-                        continue;
-                    }
-                    
-                    // Spawn sync task
-                    let purgatory = self.clone();
-                    let db = database.clone();
-                    let domain = our_domain.clone();
-                    let relay = local_relay.clone();
-                    let throttle_manager = throttle_manager.clone();
-                    let id = identifier.clone();
-                    
-                    tokio::spawn(async move {
-                        // Create the real SyncContext implementation
-                        let ctx = RealSyncContext::new(
-                            purgatory.clone(),
-                            db,
-                            domain,
-                            relay,
-                        );
-                        
-                        let complete = sync_identifier(&ctx, &id, &throttle_manager).await;
-                        
-                        if complete || !purgatory.has_pending_events(&id) {
-                            purgatory.sync_queue.remove(&id);
-                            tracing::info!(identifier = %id, "Removed from sync queue");
-                        } else {
-                            // Apply backoff - will retry later
-                            // (throttled domains are being processed independently)
-                            if let Some(mut entry) = purgatory.sync_queue.get_mut(&id) {
-                                entry.on_sync_complete();
-                            }
-                        }
-                    });
-                }
-            }
-        })
-    }
-}
-```
-## Testing Strategy
-Tests are created **only** as part of each implementation phase. See [Implementation Phases](#implementation-phases) for the complete test plan.
-### Design Principles
-1. **Tests accompany code**: Each phase specifies exactly which tests to create
-2. **Unit tests for mechanics**: Test backoff, throttle, retry logic in isolation using mocks
-3. **Integration tests for outcomes**: Verify events sync correctly end-to-end
-4. **No speculative tests**: Don't create tests for code that doesn't exist yet
-### MockSyncContext
-Phases 4-6 use `MockSyncContext` to test sync logic without I/O:
-```rust
-/// Mock context for testing sync logic
-#[cfg(test)]
-pub struct MockSyncContext {
-    /// Repository data to return
-    repo_data: RepositoryData,
-    /// OIDs still needed (decremented when "fetched")
-    needed_oids: RefCell<HashSet<String>>,
-    /// Which OIDs each URL can provide
-    url_provides_oids: HashMap<String, HashSet<String>>,
-    /// Track fetch attempts for assertions
-    fetch_log: RefCell<Vec<String>>,
-    /// Whether there are pending events
-    has_pending: RefCell<bool>,
-}
-impl MockSyncContext {
-    pub fn new() -> Self;
-    pub fn with_urls(self, urls: &[&str]) -> Self;
-    pub fn with_needed_oids(self, oids: &[&str]) -> Self;
-    pub fn url_provides(self, url: &str, oids: &[&str]) -> Self;
-}
-```
-### Test Locations
-| Test Type | Location | Created In |
-|-----------|----------|------------|
-| SyncQueueEntry | `src/purgatory/sync/queue.rs` | Phase 1 |
-| DomainThrottle | `src/purgatory/sync/throttle.rs` | Phase 2 |
-| ThrottleManager | `src/purgatory/sync/throttle.rs` | Phase 3 |
-| Core sync functions | `src/purgatory/sync/functions.rs` | Phase 5-6 |
-| Queue integration | `src/purgatory/mod.rs` | Phase 7 |
-| Unified function helpers | `src/git/sync.rs` | Phase 9 |
-| Integration tests | `tests/purgatory_sync.rs` | Phase 12 |
-## Implementation Phases
-Each phase has clear deliverables, unit tests, and success criteria. Unit tests are created **only** for the code built in that phase.
---
-### Phase 1: SyncQueueEntry with Backoff
-**Goal**: Implement the sync queue entry struct with backoff calculation.
-**Files**:
- `src/purgatory/sync/mod.rs` (new - module declaration)
- `src/purgatory/sync/queue.rs` (new)
-**Note**: This creates a new `sync` submodule under `src/purgatory/`. The current purgatory structure is flat (`mod.rs`, `helpers.rs`, `types.rs`). Add `pub mod sync;` to `src/purgatory/mod.rs`.
-**Deliverables**:
-```rust
-pub struct SyncQueueEntry {
-    pub next_attempt: Instant,
-    pub attempt_count: u32,
-    pub in_progress: bool,
-}
-impl SyncQueueEntry {
-    pub fn new(delay: Duration) -> Self;
-    pub fn backoff(&self) -> Duration;
-    pub fn is_ready(&self) -> bool;
-    pub fn on_new_event(&mut self, delay: Duration);
-    pub fn on_sync_complete(&mut self);
-}
-```
-**Unit Tests** (2 tests):
-```rust
-#[cfg(test)]
-mod tests {
-    #[test]
-    fn backoff_doubles_up_to_cap() {
-        // 20s → 40s → 80s → 120s → 120s (capped)
-    }
-    
-    #[test]
-    fn new_event_resets_attempt_count() {
-        // on_new_event() resets attempt_count to 0
-    }
-}
-```
-**Success Criteria**:
- [ ] `SyncQueueEntry::new()` creates entry with given delay
- [ ] `backoff()` returns 20s, 40s, 80s, 120s, 120s for attempts 1-5
- [ ] `on_new_event()` resets `attempt_count` to 0
- [ ] `on_sync_complete()` increments `attempt_count` and updates `next_attempt`
- [ ] Both unit tests pass
---
-### Phase 2: DomainThrottle with Rate Limiting and Round-Robin
-**Goal**: Implement per-domain throttling with concurrent/rate limits and fair queue processing.
-**Files**:
- `src/purgatory/sync/throttle.rs` (new)
-**Deliverables**:
-```rust
-pub struct DomainThrottle {
-    domain: String,
-    in_flight: u32,
-    request_times: VecDeque<Instant>,
-    queue: IndexMap<String, IdentifierQueueState>,
-    round_robin_index: usize,
-    max_concurrent: u32,
-    max_per_minute: u32,
-}
-impl DomainThrottle {
-    pub fn new(domain: String, max_concurrent: u32, max_per_minute: u32) -> Self;
-    pub fn has_capacity(&self) -> bool;
-    pub fn start_request(&mut self);
-    pub fn complete_request(&mut self);
-    pub fn enqueue_identifier(&mut self, identifier: String, tried_urls: HashSet<String>);
-    pub fn next_ready_identifier(&mut self) -> Option<String>;
-    pub fn mark_identifier_not_in_progress(&mut self, identifier: &str);
-    pub fn remove_identifier(&mut self, identifier: &str);
-}
-```
-**Unit Tests** (4 tests):
-```rust
-#[cfg(test)]
-mod tests {
-    #[test]
-    fn concurrent_limit_blocks_when_saturated() {
-        // has_capacity() returns false when in_flight >= max_concurrent
-    }
-    
-    #[test]
-    fn rate_limit_blocks_when_window_full() {
-        // has_capacity() returns false when requests in last 60s >= max_per_minute
-        // Use deterministic time (pass Instant or mock clock)
-    }
-    
-    #[test]
-    fn round_robin_processes_identifiers_fairly() {
-        // Enqueue A, B, C → next_ready returns A, B, C, A, B, C...
-    }
-    
-    #[test]
-    fn skips_in_progress_identifiers() {
-        // next_ready skips identifiers where in_progress=true
-    }
-}
-```
-**Success Criteria**:
- [ ] Concurrent limit enforced (blocks at max_concurrent)
- [ ] Rate limit enforced (blocks at max_per_minute within 60s window)
- [ ] Round-robin ordering maintained across calls
- [ ] In-progress identifiers skipped
- [ ] All 4 unit tests pass
---
-### Phase 3: ThrottleManager (Rate Limiting Only)
-**Goal**: Implement the manager that owns all domain throttles and provides rate limiting. Queue processing methods (`set_context`, `process_queued_identifier`) are added in Phase 6 after `SyncContext` exists.
-**Files**:
- `src/purgatory/sync/throttle.rs` (extend)
-**Deliverables**:
-```rust
-pub struct ThrottleManager {
-    throttles: DashMap<String, DomainThrottle>,
-    max_concurrent_per_domain: u32,
-    max_per_minute_per_domain: u32,
-    // Note: ctx: OnceLock<Arc<dyn SyncContext>> added in Phase 6
-}
-impl ThrottleManager {
-    pub fn new(max_concurrent: u32, max_per_minute: u32) -> Self;
-    pub fn is_throttled(&self, domain: &str) -> bool;
-    pub fn start_request(&self, domain: &str);
-    pub fn complete_request(&self, domain: &str);  // Trigger logic added in Phase 6
-    pub fn enqueue_identifier(&self, domain: &str, identifier: String, tried_urls: HashSet<String>);  // Trigger logic added in Phase 6
-}
-```
-**Unit Tests** (1 test):
-```rust
-#[cfg(test)]
-mod tests {
-    #[test]
-    fn is_throttled_reflects_domain_capacity() {
-        // is_throttled returns true when domain has no capacity
-    }
-}
-```
-**Success Criteria**:
- [ ] `is_throttled()` correctly reflects domain capacity
- [ ] `start_request()`/`complete_request()` delegate to correct domain
- [ ] `enqueue_identifier()` creates domain throttle if needed
- [ ] Unit test passes
-**Note**: The `complete_request()` and `enqueue_identifier()` methods in this phase only update state. The trigger-based processing (spawning tasks when capacity frees) is added in Phase 6 after `SyncContext` is available.
---
-### Phase 4: SyncContext Trait and MockSyncContext
-**Goal**: Define the abstraction for sync operations and create the test mock.
-**Files**:
- `src/purgatory/sync/context.rs` (new)
-**Deliverables**:
-```rust
-#[async_trait]
-pub trait SyncContext: Send + Sync {
-    async fn fetch_repository_data(&self, identifier: &str) -> Result<RepositoryData>;
-    fn collect_needed_oids(&self, identifier: &str) -> HashSet<String>;
-    async fn fetch_oids(&self, repo_path: &Path, url: &str, oids: &[String]) -> Result<Vec<String>>;
-    async fn process_newly_available_git_data(
-        &self,
-        source_repo_path: &Path,
-        new_oids: &HashSet<String>,
-    ) -> Result<ProcessResult>;
-    fn has_pending_events(&self, identifier: &str) -> bool;
-    fn find_target_repo(&self, data: &RepositoryData) -> Option<PathBuf>;
-    fn our_domain(&self) -> Option<&str>;
-}
-// Test support
-#[cfg(test)]
-pub struct MockSyncContext { ... }
-```
-**Unit Tests** (0 tests):
- This phase creates infrastructure only; tests come in Phase 5
-**Success Criteria**:
- [ ] `SyncContext` trait compiles with all required methods
- [ ] `MockSyncContext` implements `SyncContext`
- [ ] Mock supports builder pattern for test setup
---
-### Phase 5: Core Sync Functions
-**Goal**: Implement `sync_identifier_next_url` and `sync_identifier_from_url`.
-**Files**:
- `src/purgatory/sync/functions.rs` (new)
-**Deliverables**:
-```rust
-pub async fn sync_identifier_next_url<C: SyncContext>(
-    ctx: &C,
-    identifier: &str,
-    domain: Option<&str>,
-    tried_urls: &HashSet<String>,
-    throttle_manager: &ThrottleManager,
-) -> Option<String>;
-pub async fn sync_identifier_from_url<C: SyncContext>(
-    ctx: &C,
-    identifier: &str,
-    url: &str,
-    throttle_manager: &Arc<ThrottleManager>,
-) -> usize;
-```
-**Unit Tests** (3 tests):
-```rust
-#[cfg(test)]
-mod tests {
-    #[tokio::test]
-    async fn next_url_skips_throttled_domains() {
-        // When domain is throttled, next_url returns URL from different domain
-    }
-    
-    #[tokio::test]
-    async fn next_url_skips_tried_urls() {
-        // URLs in tried_urls set are not returned
-    }
-    
-    #[tokio::test]
-    async fn from_url_fetches_and_processes_on_success() {
-        // Successful fetch triggers process_newly_available_git_data
-    }
-}
-```
-**Success Criteria**:
- [ ] `sync_identifier_next_url` returns non-throttled, untried URL
- [ ] `sync_identifier_next_url` returns `None` when all URLs tried or throttled
- [ ] `sync_identifier_from_url` calls `fetch_oids` and `process_newly_available_git_data`
- [ ] All 3 unit tests pass
---
-### Phase 6: sync_identifier Orchestration + ThrottleManager Queue Processing
-**Goal**: Implement the main sync loop for a single identifier AND add trigger-based queue processing to ThrottleManager.
-**Files**:
- `src/purgatory/sync/functions.rs` (extend)
- `src/purgatory/sync/throttle.rs` (extend - add queue processing triggers)
-**Deliverables**:
-```rust
-// In functions.rs
-pub async fn sync_identifier<C: SyncContext>(
-    ctx: &C,
-    identifier: &str,
-    throttle_manager: &Arc<ThrottleManager>,
-) -> bool;  // true if complete, false if pending
-// In throttle.rs - add to ThrottleManager
-impl ThrottleManager {
-    /// Set the sync context (called once at startup)
-    pub fn set_context(&self, ctx: Arc<dyn SyncContext>);
-    
-    /// Try to process the next queued identifier for a domain (internal)
-    fn try_process_next(self: &Arc<Self>, domain: &str);
-    
-    /// Process a single identifier from a domain's queue (internal)
-    async fn process_queued_identifier(self: &Arc<Self>, domain: &str, identifier: &str);
-}
-// Update complete_request and enqueue_identifier to trigger processing
-```
-**Unit Tests** (2 tests):
-```rust
-#[cfg(test)]
-mod tests {
-    #[tokio::test]
-    async fn tries_multiple_urls_until_complete() {
-        // Tries URL1 (partial), URL2 (partial), URL3 (complete) → returns true
-    }
-    
-    #[tokio::test]
-    async fn enqueues_throttled_domains_when_incomplete() {
-        // When URLs remain but are throttled, enqueues and returns false
-    }
-}
-```
-**Success Criteria**:
- [ ] Loops through available URLs until sync complete or all tried
- [ ] Enqueues with throttled domains when OIDs still needed
- [ ] Returns `true` when all OIDs fetched, `false` otherwise
- [ ] `complete_request()` triggers `try_process_next()` when capacity available
- [ ] `enqueue_identifier()` triggers `try_process_next()` when capacity available
- [ ] Both unit tests pass
---
-### Phase 7: Purgatory Sync Queue Integration
-**Goal**: Add sync queue to Purgatory and implement `enqueue_sync`.
-**Files**:
- `src/purgatory/mod.rs` (extend)
-**Deliverables**:
-```rust
-impl Purgatory {
-    // New field: sync_queue: Arc<DashMap<String, SyncQueueEntry>>
-    
-    pub fn enqueue_sync(&self, identifier: &str, delay: Duration);
-    pub fn has_pending_events(&self, identifier: &str) -> bool;
-}
-```
-**Unit Tests** (1 test):
-```rust
-#[cfg(test)]
-mod tests {
-    #[test]
-    fn enqueue_sync_debounces_rapid_calls() {
-        // Multiple enqueue_sync calls within delay window result in single entry
-    }
-}
-```
-**Success Criteria**:
- [ ] `enqueue_sync` adds/updates entry in sync_queue
- [ ] Rapid calls debounce (don't create multiple entries)
- [ ] `has_pending_events` checks both state_events and pr_events
- [ ] Unit test passes
---
-### Phase 8: Main Sync Loop
-**Goal**: Implement the background sync loop that processes ready identifiers.
-**Files**:
- `src/purgatory/sync/loop.rs` (new)
-**Deliverables**:
-```rust
-impl Purgatory {
-    pub fn start_sync_loop(
-        self: Arc<Self>,
-        ctx: Arc<dyn SyncContext>,
-        throttle_manager: Arc<ThrottleManager>,
-    ) -> JoinHandle<()>;
-}
-```
-**Note**: The sync loop interval is hardcoded to 1 second. No configuration option needed.
-**Unit Tests** (0 tests):
- The sync loop is tested via integration tests; unit testing async loops is fragile
-**Success Criteria**:
- [ ] Loop runs every 1 second (hardcoded)
- [ ] Finds ready identifiers and spawns sync tasks
- [ ] Applies backoff on incomplete syncs
- [ ] Removes completed identifiers from queue
---
-### Phase 9: Unified `process_newly_available_git_data` Function
-**Goal**: Implement the unified function that handles all post-git-data-available processing.
-This is the core function described in [Unified Git Data Sync](unify-git-data-sync.md). It will be called by both:
- `handle_receive_pack` after a successful git push
- `RealSyncContext::process_newly_available_git_data` after purgatory sync fetches OIDs
-**Files**:
- `src/git/sync.rs` (extend - add `ProcessResult` alongside existing types)
-**Note**: `src/git/sync.rs` already exists with `sync_to_owner_repos`, `align_repository_with_state`, etc. This phase extends it with the unified processing function.
-**Deliverables**:
-```rust
-/// Result of processing newly available git data
-#[derive(Debug, Default)]
-pub struct ProcessResult {
-    pub states_released: usize,
-    pub prs_released: usize,
-    pub repos_synced: usize,
-    pub refs_created: usize,
-    pub refs_updated: usize,
-    pub refs_deleted: usize,
-    pub errors: Vec<String>,
-}
-/// Unified processing of newly available git data.
-///
-/// Called whenever git data becomes available, whether from:
-/// - A successful `git push` (handle_receive_pack)
-/// - Purgatory sync fetching OIDs from remote servers
-pub async fn process_newly_available_git_data(
-    source_repo_path: &Path,
-    new_oids: &HashSet<String>,
-    database: &SharedDatabase,
-    local_relay: Option<&nostr_relay_builder::LocalRelay>,
-    purgatory: &Purgatory,
-    git_data_path: &Path,
-) -> Result<ProcessResult>;
-// Helper functions
-fn extract_identifier_from_repo_path(repo_path: &Path, git_data_path: &Path) -> Option<String>;
-fn extract_identifier_from_pr_event(event: &Event) -> Option<String>;
-// Purgatory additions
-impl Purgatory {
-    /// Find all PR events for an identifier.
-    /// Filters pr_events entries where the identifier matches (no secondary index needed).
-    pub fn find_prs_for_identifier(&self, identifier: &str) -> Vec<PrPurgatoryEntry>;
-}
-```
-**Unit Tests** (3 tests):
-```rust
-#[cfg(test)]
-mod tests {
-    #[test]
-    fn extract_identifier_from_repo_path_valid() {
-        // {git_data_path}/{npub}/{identifier}.git → identifier
-    }
-    
-    #[test]
-    fn extract_identifier_from_pr_event_valid() {
-        // Event with "a" tag "30617:<pubkey>:<identifier>" → identifier
-    }
-    
-    #[test]
-    fn extract_identifier_from_pr_event_missing_tag() {
-        // Event without "a" tag → None
-    }
-}
-```
-**Success Criteria**:
- [ ] `process_newly_available_git_data` discovers satisfiable events from purgatory
- [ ] State events: syncs OIDs to owner repos, aligns refs, sets HEAD, saves to DB, notifies WS, removes from purgatory
- [ ] PR events: syncs commit to owner repos, creates refs/nostr/<event-id>, saves to DB, notifies WS, removes from purgatory
- [ ] `find_prs_for_identifier` filters pr_events by identifier correctly
- [ ] All 3 unit tests pass
---
-### Phase 10: Update `handle_receive_pack` to Use Unified Function
-**Goal**: Refactor the push authorization handler to use `process_newly_available_git_data`.
-This replaces ~100 lines of duplicated post-push processing with a single call to the unified function.
-**Files**:
- `src/git/handlers.rs` (modify)
-**Before** (current code):
-```rust
-// After git receive-pack succeeds:
-// - try_set_head_if_available()
-// - database.save_event()
-// - remove_state_event() / remove_pr()
-// - relay.notify_event()
-// - sync_to_owner_repos()
-// - sync_pr_refs_to_tagged_owner_repos()
-// ... ~100 lines of processing
-```
-**After** (simplified):
-```rust
-// After git receive-pack succeeds:
-let new_oids: HashSet<String> = pushed_refs
-    .iter()
-    .filter(|(_, new_oid, _)| new_oid != "0000000000000000000000000000000000000000")
-    .map(|(_, new_oid, _)| new_oid.clone())
-    .collect();
-let result = process_newly_available_git_data(
-    &repo_path,
-    &new_oids,
-    &database,
-    Some(&relay),
-    &purgatory,
-    Path::new(git_data_path),
-).await;
-info!(
-    "Processed push: {} states, {} PRs released, {} repos synced",
-    result.states_released,
-    result.prs_released,
-    result.repos_synced
-);
-```
-**Unit Tests** (0 tests):
- Behavior tested via existing integration tests which should continue to pass
-**Success Criteria**:
- [ ] `handle_receive_pack` uses `process_newly_available_git_data`
- [ ] Duplicate code removed (~100 lines)
- [ ] All existing push-related tests still pass
- [ ] Push behavior unchanged (same events saved, same refs created)
---
-### Phase 11: RealSyncContext Implementation
-**Goal**: Implement the production `SyncContext` that connects to real systems.
-**Files**:
- `src/purgatory/sync/context.rs` (extend)
-**Deliverables**:
-```rust
-pub struct RealSyncContext {
-    purgatory: Purgatory,
-    database: SharedDatabase,
-    git_data_path: PathBuf,
-    our_domain: Option<String>,
-    local_relay: Option<LocalRelay>,
-}
-impl SyncContext for RealSyncContext { ... }
-```
-**Unit Tests** (0 tests):
- `RealSyncContext` is tested via integration tests
-**Success Criteria**:
- [ ] All `SyncContext` methods implemented
- [ ] Connects to real database, git, and relay
- [ ] `process_newly_available_git_data` method delegates to unified function from Phase 9
---
-### Phase 12: Integration Tests
-**Goal**: Verify end-to-end sync behavior with real relay instances.
-**Files**:
- `tests/purgatory_sync.rs` (new)
-**Integration Tests** (5 tests):
-```rust
-#[tokio::test]
-async fn state_event_syncs_from_remote() {
-    // State event enters purgatory, git data fetched, event released
-}
-#[tokio::test]
-async fn pr_event_syncs_from_remote() {
-    // PR event enters purgatory, commit fetched, event released
-}
-#[tokio::test]
-async fn concurrent_state_and_pr_sync() {
-    // Both event types sync correctly when arriving together
-}
-#[tokio::test]
-async fn partial_oid_aggregation_from_multiple_servers() {
-    // OIDs aggregated when no single server has all
-}
-#[tokio::test]
-async fn push_triggers_unified_processing() {
-    // Git push triggers process_newly_available_git_data
-    // Verifies Phase 10 integration
-}
-```
-**Success Criteria**:
- [ ] All 5 integration tests pass
- [ ] State events release after git sync
- [ ] PR events release after commit sync
- [ ] Partial OID scenarios handled correctly
- [ ] Push path uses unified function (same behavior as purgatory sync)
---
-### Phase 13: Cleanup
-**Goal**: Remove old `start_state_sync` code and wire up new system.
-**Files**:
- `src/purgatory/mod.rs` (modify)
- `src/main.rs` (modify)
-**Deliverables**:
- Remove `start_state_sync` method
- Wire `start_sync_loop` into application startup
- Update `add_state` to call `enqueue_sync`
-**Success Criteria**:
- [ ] Old sync code removed
- [ ] New sync loop starts on application boot
- [ ] All existing tests still pass
- [ ] All new tests pass
---
-## Test Summary
-| Phase | Unit Tests | Integration Tests | Total |
-|-------|------------|-------------------|-------|
-| 1. SyncQueueEntry | 2 | - | 2 |
-| 2. DomainThrottle | 4 | - | 4 |
-| 3. ThrottleManager (rate limiting) | 1 | - | 1 |
-| 4. SyncContext | 0 | - | 0 |
-| 5. Core Functions | 3 | - | 3 |
-| 6. sync_identifier + queue triggers | 2 | - | 2 |
-| 7. Queue Integration | 1 | - | 1 |
-| 8. Sync Loop | 0 | - | 0 |
-| 9. Unified Function | 3 | - | 3 |
-| 10. Push Handler Update | 0 | - | 0 |
-| 11. RealSyncContext | 0 | - | 0 |
-| 12. Integration | - | 5 | 5 |
-| 13. Cleanup | 0 | - | 0 |
-| **Total** | **16** | **5** | **21** |
-## Configuration
-| Option | CLI Flag | Environment Variable | Default |
-|--------|----------|---------------------|---------|
-| Domain concurrent limit | `--sync-domain-concurrent` | `NGIT_SYNC_DOMAIN_CONCURRENT` | `5` |
-| Domain rate limit | `--sync-domain-rate-limit` | `NGIT_SYNC_DOMAIN_RATE_LIMIT` | `30` |
-| Default sync delay | `--sync-default-delay-secs` | `NGIT_SYNC_DEFAULT_DELAY_SECS` | `180` |
-| Immediate sync delay | `--sync-immediate-delay-ms` | `NGIT_SYNC_IMMEDIATE_DELAY_MS` | `500` |
-**Note**: Sync loop interval is hardcoded to 1 second (not configurable).
-## Observability
-### Metrics
- `purgatory_sync_queue_size` - Identifiers pending sync
- `purgatory_sync_attempts_total` - Sync attempts per identifier
- `purgatory_sync_oids_fetched_total` - OIDs successfully fetched
- `purgatory_domain_in_flight` - In-flight requests per domain
- `purgatory_domain_requests_total` - Total requests per domain
-### Logging
- `INFO`: Successful sync completion, OIDs fetched
- `DEBUG`: URL attempts, throttle decisions, backoff applied
- `WARN`: Fetch failures, processing errors
diff --git a/docs/explanation/unify-git-data-sync.md b/docs/explanation/unify-git-data-sync.md
deleted file mode 100644
index fa1f983..0000000
--- a/docs/explanation/unify-git-data-sync.md
+++ /dev/null
@@ -1,481 +0,0 @@
-# Unified Git Data Sync
-## Status
-**Proposed** - January 2026
-## Context
-Currently, two separate code paths handle "git data is now available" scenarios:
-1. **`handle_receive_pack`** (src/git/handlers.rs) - After a successful `git push`
-2. **`sync_state_git_data`** (src/purgatory/mod.rs) - After purgatory sync fetches OIDs from remote servers
-Both paths perform essentially the same post-processing:
-| Step | `handle_receive_pack` | `sync_state_git_data` |
-|------|----------------------|----------------------|
-| Set HEAD | ✅ `try_set_head_if_available()` | ✅ (via `align_repository_with_state`) |
-| Save events to DB | ✅ `database.save_event()` | ✅ `database.save_event()` |
-| Remove from purgatory | ✅ `remove_state_event()` / `remove_pr()` | ✅ `remove_state_event()` |
-| Notify WebSocket | ✅ `relay.notify_event()` | ✅ `relay.notify_event()` |
-| Sync state to owner repos | ✅ `sync_to_owner_repos()` | ✅ `sync_to_owner_repos()` |
-| Sync PR refs to owner repos | ✅ `sync_pr_refs_to_tagged_owner_repos()` | ❌ Not implemented |
-This duplication creates maintenance burden and inconsistent behavior (e.g., PR sync missing from purgatory path).
-## Decision
-Create a single unified function that handles all post-git-data-available processing:
-```rust
-pub async fn process_newly_available_git_data(
-    source_repo_path: &Path,
-    new_oids: &HashSet<String>,
-    database: &SharedDatabase,
-    local_relay: Option<&nostr_relay_builder::LocalRelay>,
-    purgatory: &Purgatory,
-    git_data_path: &Path,
-) -> ProcessResult
-```
-### Key Design Principles
-**1. Always discover events from purgatory**
-Rather than accepting pre-authorized events (which may have changed since authorization), the function always scans purgatory to find satisfiable events. This ensures consistency and handles race conditions where events change between authorization and processing.
-**2. Minimal input, maximal output**
-Callers only need to provide:
- `source_repo_path` - Where the git data landed
- `new_oids` - Which OIDs are now available (for efficient filtering)
-The function handles everything else: finding events, syncing across repos, aligning refs, setting HEAD, saving to database, notifying subscribers, and cleaning up purgatory.
-**3. Process all event types uniformly**
-Both state events (kind 30618) and PR events (kind 1617/1618) are processed in the same flow, ensuring consistent behavior.
-## Architecture
-### Flow Overview
-```
-┌─────────────────────────────────────────────────────────────────────────────────┐
-│                         Git Data Becomes Available                               │
-│                                                                                  │
-│   ┌─────────────────────┐              ┌─────────────────────┐                   │
-│   │  handle_receive_pack │              │  purgatory sync     │                   │
-│   │  (push received)     │              │  (fetch completed)  │                   │
-│   └──────────┬──────────┘              └──────────┬──────────┘                   │
-│              │                                    │                              │
-│              │  source_repo_path                  │  source_repo_path            │
-│              │  new_oids                          │  new_oids                    │
-│              │                                    │                              │
-│              └────────────────┬───────────────────┘                              │
-│                               │                                                  │
-│                               ▼                                                  │
-│              ┌────────────────────────────────────────┐                          │
-│              │  process_newly_available_git_data()    │                          │
-│              │                                        │                          │
-│              │  1. Extract identifier from path       │                          │
-│              │  2. Fetch repository data from DB      │                          │
-│              │  3. Find satisfiable state events      │                          │
-│              │  4. Find satisfiable PR events         │                          │
-│              │  5. For each event:                    │                          │
-│              │     - Sync OIDs to owner repos         │                          │
-│              │     - Align refs (+ set HEAD)          │                          │
-│              │     - Save to database                 │                          │
-│              │     - Notify WebSocket                 │                          │
-│              │     - Remove from purgatory            │                          │
-│              └────────────────────────────────────────┘                          │
-└─────────────────────────────────────────────────────────────────────────────────┘
-```
-### Event Discovery
-The function discovers satisfiable events by scanning purgatory:
-**For State Events:**
-1. Get all state entries for the identifier from purgatory
-2. For each entry, check if ALL required OIDs exist in source repo
-3. Quick optimization: skip if none of `new_oids` are in the state's OID set
-**For PR Events:**
-1. Get all PR entries for the identifier from purgatory (via secondary index)
-2. For each entry with an event, check if the commit OID exists in source repo
-3. Quick optimization: skip if commit not in `new_oids`
-### Sync to Owner Repos
-**For State Events:**
-For each owner whose maintainer set authorizes the state author:
-1. Skip if a newer state already exists for that owner
-2. Copy missing OIDs from source repo to target repo
-3. Align refs (create/update/delete branches and tags)
-4. Set HEAD per state announcement
-**For PR Events:**
-For each owner whose maintainer set includes any tagged owner (from `a` tags):
-1. Copy commit from source repo to target repo (if missing)
-2. Create `refs/nostr/<event-id>` pointing to the commit
-## Data Structure Changes
-### PrPurgatoryEntry
-Add `identifier` field for secondary index lookup:
-```rust
-#[derive(Debug, Clone)]
-pub struct PrPurgatoryEntry {
-    /// The nostr PR event, if received (None = git data arrived first)
-    pub event: Option<Event>,
-    /// The expected commit SHA from 'c' tag or actual commit pushed
-    pub commit: String,
-    /// Repository identifier extracted from 'a' tag (30617:<owner>:<identifier>)
-    /// Used for lookup when git data arrives
-    pub identifier: Option<String>,
-    /// When this entry was added to purgatory
-    pub created_at: Instant,
-    /// Expiry deadline
-    pub expires_at: Instant,
-}
-```
-### Purgatory Secondary Index
-Add index for finding PR events by identifier:
-```rust
-pub struct Purgatory {
-    /// State events indexed by repository identifier
-    state_events: Arc<DashMap<String, Vec<StatePurgatoryEntry>>>,
-    /// PR events indexed by event ID (hex string)
-    pr_events: Arc<DashMap<String, PrPurgatoryEntry>>,
-    /// Secondary index: identifier -> event_ids for PR events
-    pr_events_by_identifier: Arc<DashMap<String, HashSet<String>>>,
-    git_data_path: PathBuf,
-}
-```
-### New Purgatory Methods
-```rust
-impl Purgatory {
-    /// Find all PR events for an identifier
-    pub fn find_prs_for_identifier(&self, identifier: &str) -> Vec<PrPurgatoryEntry>;
-    
-    /// Add PR with automatic identifier extraction and indexing
-    pub fn add_pr(&self, event: Event, event_id: String, commit: String);
-    
-    /// Add placeholder with optional identifier
-    pub fn add_pr_placeholder(&self, event_id: String, commit: String, identifier: Option<String>);
-    
-    /// Remove PR (also cleans up secondary index)
-    pub fn remove_pr(&self, event_id: &str);
-}
-```
-## Implementation
-### Core Function
-```rust
-/// Unified processing of newly available git data.
-///
-/// Called whenever git data becomes available, whether from:
-/// - A successful `git push` (handle_receive_pack)
-/// - Purgatory sync fetching OIDs from remote servers
-///
-/// # What it does
-///
-/// 1. **Discover satisfiable events**: Scans purgatory for state and PR events
-///    whose required OIDs are now available in `source_repo_path`
-///
-/// 2. **For each satisfiable STATE event**:
-///    - Find all owner repos that authorize this state's author
-///    - Copy OIDs from source repo to each authorized owner repo
-///    - Align refs (create/update/delete) to match state
-///    - Set HEAD per state announcement
-///    - Save event to database
-///    - Notify WebSocket subscribers
-///    - Remove from purgatory
-///
-/// 3. **For each satisfiable PR event**:
-///    - Find all owner repos that list tagged owners as maintainers
-///    - Copy commit from source repo to each relevant owner repo
-///    - Create refs/nostr/<event-id> in each repo
-///    - Save event to database
-///    - Notify WebSocket subscribers
-///    - Remove from purgatory
-pub async fn process_newly_available_git_data(
-    source_repo_path: &Path,
-    new_oids: &HashSet<String>,
-    database: &SharedDatabase,
-    local_relay: Option<&nostr_relay_builder::LocalRelay>,
-    purgatory: &Purgatory,
-    git_data_path: &Path,
-) -> ProcessResult {
-    let mut result = ProcessResult::default();
-    // Extract identifier from repo path
-    let identifier = match extract_identifier_from_repo_path(source_repo_path, git_data_path) {
-        Some(id) => id,
-        None => return result,
-    };
-    // Fetch repository data once for all operations
-    let db_repo_data = match fetch_repository_data(database, &identifier).await {
-        Ok(data) => data,
-        Err(e) => {
-            result.errors.push(format!("Failed to fetch repo data: {}", e));
-            return result;
-        }
-    };
-    // Process satisfiable state events
-    let state_result = process_satisfiable_state_events(
-        source_repo_path,
-        &identifier,
-        new_oids,
-        &db_repo_data,
-        database,
-        local_relay,
-        purgatory,
-        git_data_path,
-    ).await;
-    
-    result.merge_state_result(state_result);
-    // Process satisfiable PR events
-    let pr_result = process_satisfiable_pr_events(
-        source_repo_path,
-        &identifier,
-        new_oids,
-        &db_repo_data,
-        database,
-        local_relay,
-        purgatory,
-        git_data_path,
-    ).await;
-    
-    result.merge_pr_result(pr_result);
-    result
-}
-```
-### Result Type
-```rust
-/// Result of processing newly available git data
-#[derive(Debug, Default)]
-pub struct ProcessResult {
-    /// Number of state events released from purgatory
-    pub states_released: usize,
-    /// Number of PR events released from purgatory
-    pub prs_released: usize,
-    /// Number of owner repositories synced
-    pub repos_synced: usize,
-    /// Number of refs created across all repos
-    pub refs_created: usize,
-    /// Number of refs updated across all repos
-    pub refs_updated: usize,
-    /// Number of refs deleted across all repos
-    pub refs_deleted: usize,
-    /// Errors encountered (non-fatal)
-    pub errors: Vec<String>,
-}
-```
-### Helper: Extract Identifier from PR Event
-```rust
-/// Extract identifier from PR event's `a` tag.
-/// Format: 30617:<owner_pubkey>:<identifier>
-fn extract_identifier_from_pr_event(event: &Event) -> Option<String> {
-    event.tags.iter().find_map(|tag| {
-        let tag_vec = tag.clone().to_vec();
-        if tag_vec.len() >= 2 && tag_vec[0] == "a" && tag_vec[1].starts_with("30617:") {
-            let parts: Vec<&str> = tag_vec[1].split(':').collect();
-            if parts.len() >= 3 {
-                Some(parts[2].to_string())
-            } else {
-                None
-            }
-        } else {
-            None
-        }
-    })
-}
-```
-### Helper: Extract Identifier from Repo Path
-```rust
-/// Extract identifier from repository path.
-/// Path format: {git_data_path}/{npub}/{identifier}.git
-fn extract_identifier_from_repo_path(repo_path: &Path, git_data_path: &Path) -> Option<String> {
-    let relative = repo_path.strip_prefix(git_data_path).ok()?;
-    let components: Vec<_> = relative.components().collect();
-    if components.len() >= 2 {
-        let identifier_with_git = components[1].as_os_str().to_str()?;
-        Some(identifier_with_git.trim_end_matches(".git").to_string())
-    } else {
-        None
-    }
-}
-```
-## Integration
-### handle_receive_pack (Simplified)
-```rust
-// After git receive-pack succeeds:
-// Collect new OIDs from the push
-let new_oids: HashSet<String> = pushed_refs
-    .iter()
-    .filter(|(_, new_oid, _)| new_oid != "0000000000000000000000000000000000000000")
-    .map(|(_, new_oid, _)| new_oid.clone())
-    .collect();
-// Single unified call handles everything
-let result = process_newly_available_git_data(
-    &repo_path,
-    &new_oids,
-    &database,
-    Some(&relay),
-    &purgatory,
-    Path::new(git_data_path),
-).await;
-info!(
-    "Processed push: {} states, {} PRs released, {} repos synced",
-    result.states_released,
-    result.prs_released,
-    result.repos_synced
-);
-```
-### Purgatory Sync (Simplified)
-```rust
-// After fetching OIDs from remote:
-let new_oids: HashSet<String> = fetched_oids.into_iter().collect();
-let result = process_newly_available_git_data(
-    &source_repo_path,
-    &new_oids,
-    &database,
-    local_relay.as_ref(),
-    &purgatory,
-    &git_data_path,
-).await;
-```
-### Integration with Purgatory Sync Redesign
-The purgatory sync redesign (see `purgatory-sync-redesign.md`) uses this unified function in its `sync_identifier_from_url` implementation:
-```rust
-pub async fn sync_identifier_from_url<C: SyncContext>(
-    ctx: &C,
-    identifier: &str,
-    url: &str,
-    throttle_manager: &Arc<ThrottleManager>,
-) -> usize {
-    // ... fetch OIDs from URL ...
-    
-    let fetched_oids = ctx.fetch_oids(&target_repo, url, &needed_oids).await?;
-    
-    if !fetched_oids.is_empty() {
-        // Use unified processing
-        let new_oids: HashSet<String> = fetched_oids.into_iter().collect();
-        
-        let result = process_newly_available_git_data(
-            &target_repo,
-            &new_oids,
-            ctx.database(),
-            ctx.local_relay(),
-            ctx.purgatory(),
-            ctx.git_data_path(),
-        ).await;
-        
-        // Result already handled purgatory removal, DB saves, etc.
-    }
-    
-    fetched_oids.len()
-}
-```
-The `SyncContext` trait wraps this function in its `process_newly_available_git_data` method for testability.
-## Benefits
-1. **Single source of truth** - One function handles all post-git-data processing
-2. **Always fresh discovery** - Events discovered from purgatory at processing time
-3. **Consistent behavior** - Push and sync paths behave identically
-4. **Simpler callers** - Just pass repo_path + new_oids
-5. **Complete processing** - Handles all event types, all repo syncing, HEAD, DB, WebSocket, purgatory
-6. **PR sync parity** - PR events now synced in purgatory path (was missing)
-## Code to Remove/Simplify
-After implementing the unified function:
-1. **Remove**: Most of `sync_state_git_data` in `src/purgatory/mod.rs`
-2. **Simplify**: Event handling in `handle_receive_pack` (replace ~100 lines with single call)
-3. **Internalize**: `sync_to_owner_repos` and `sync_pr_refs_to_tagged_owner_repos` become internal helpers
-## Testing Strategy
-### Unit Tests
-1. `extract_identifier_from_repo_path` - Various path formats
-2. `extract_identifier_from_pr_event` - Various tag formats
-3. Event discovery logic with mock purgatory
-### Integration Tests
-1. Push triggers processing and releases state event
-2. Push triggers processing and releases PR event
-3. Purgatory sync triggers processing
-4. Multiple events for same identifier processed correctly
-5. Cross-repo sync works for both state and PR events
-## Future Considerations
-### Batch Processing
-Currently processes events one at a time. Could batch database saves and WebSocket notifications for efficiency with many events.
-### Partial Failures
-Currently continues on errors and collects them in result. Could add retry logic or transaction semantics if needed.
-### Metrics
-Add Prometheus metrics for:
- Events processed by type (state/PR)
- Repos synced per processing call
- Processing duration
- Errors by type
-## Related Documents
- [Purgatory Sync Redesign](purgatory-sync-redesign.md) - Uses this unified function for purgatory sync operations