docs: update docs with sync and purgatory and git data sync

1 files changed, 506 insertions, 724 deletions

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)
-**Implementation**: Phases 1-7 complete
-**Source Code**: [`src/purgatory/`](../../src/purgatory/)
+**Status**: ✅ Implemented  
+**Implementation**: [`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
-- **PR Events**: Indexed by `event_id`, matched directly via `refs/nostr/<event-id>`
+State events (kind 30618) and PR events (kind 1617/1618) have fundamentally different matching patterns:
 
-### 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>`
-- **Git first**: Push creates placeholder, waits for PR event to arrive
+| Scenario | What Happens |
+|----------|--------------|
+| **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
-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
-```
+See [`src/git/authorization.rs:51-162`](../../src/git/authorization.rs) for implementation.
+
+---
 
 ## 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)
-    /// or the actual commit pushed (if git arrived first)
+    
+    /// Expected commit SHA from 'c' tag (if event exists)
+    /// 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: DashMap<String, Vec<StatePurgatoryEntry>>,
-
+    /// State events indexed by identifier (d tag)
+    /// 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
-        Purgatory->>Purgatory: Add entry indexed by identifier
-        WritePolicy->>Client: OK true purgatory: will not be served until git data arrives
+        WritePolicy->>Purgatory: add_state(event, identifier, author)
+        Purgatory->>Purgatory: Store in state_events[identifier]
+        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
-    WritePolicy->>WritePolicy: Validate structure
-    WritePolicy->>WritePolicy: Extract event_id and commit from c tag
+    Client->>WritePolicy: EVENT kind:1617/1618
+    WritePolicy->>WritePolicy: Extract event_id and commit from 'c' tag
 
-    Note right of WritePolicy: Check if git data already exists
-    WritePolicy->>GitRepos: Check refs/nostr/event-id in authorized repos
+    Note right of WritePolicy: Check if git data exists
+    WritePolicy->>GitRepos: Check refs/nostr/<event-id> in repos
 
-    alt Git data already exists
-        GitRepos-->>WritePolicy: Found matching commit
-        WritePolicy->>WritePolicy: Process immediately
+    alt Git data exists in database
+        GitRepos-->>WritePolicy: Found with matching commit
+        WritePolicy->>Database: Save event
         WritePolicy->>Client: OK true - event saved
-    else Git data arrived first - placeholder exists
-        WritePolicy->>Purgatory: find_pr_placeholder - event_id
-        alt Placeholder found with matching commit
+    else Placeholder exists in purgatory
+        WritePolicy->>Purgatory: find_pr_placeholder(event_id)
+        alt Placeholder has matching commit
             Purgatory-->>WritePolicy: Placeholder entry
-            WritePolicy->>WritePolicy: Process - save event
-            WritePolicy->>Purgatory: remove - event_id
+            WritePolicy->>Database: Save event
+            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:
-
-**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.
+**Critical:** Authorization happens BEFORE git-receive-pack execution, checking both database and purgatory.
 
 ```mermaid
 sequenceDiagram
     participant GitClient
     participant GitHandler
+    participant Authorization
     participant Purgatory
     participant Database
-    participant GitRepo
-
-    GitClient->>GitHandler: POST /npub/identifier/git-receive-pack
-    GitHandler->>GitHandler: Parse pushed refs into RefPairs
-
-    Note over GitHandler: Look up state events by identifier
-    GitHandler->>Purgatory: find_matching_states - identifier, pushed_refs
-
-    loop For each state event in purgatory[identifier]
-        Purgatory->>Purgatory: Parse state event refs
-        Purgatory->>Purgatory: Check: pushed_refs covers event refs that differ from local
-        Purgatory->>Purgatory: Check: event refs not in push already exist locally
-        alt All event refs can be satisfied
-            Purgatory->>Purgatory: Add to candidates
-        end
-    end
-
-    Purgatory-->>GitHandler: Vec of candidate state events
-
-    Note over GitHandler: Get all state events and announcements for identifier
-    GitHandler->>Database: Get announcements for identifier
-    GitHandler->>Database: Get all state events for identifier from relay
-    GitHandler->>GitHandler: collect_authorized_maintainers from announcements
-
-    Note over GitHandler: Find authoritative state event
-    loop For each candidate from purgatory
-        GitHandler->>GitHandler: Check if event.author is authorized for target repo
-        alt Author authorized
-            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
+    participant GitProcess
+
+    GitClient->>GitHandler: POST /npub/id/git-receive-pack
+    GitHandler->>Authorization: authorize_push(body, purgatory, database)
+    
+    Note over Authorization: Parse pushed refs from pkt-line format
+    Authorization->>Authorization: parse_pushed_refs(body)
+    Authorization->>Authorization: Separate state refs from refs/nostr/*
+    
+    Note over Authorization: Check database for state events
+    Authorization->>Database: Query state events for identifier
+    
+    alt State found in database
+        Database-->>Authorization: State event
+        Authorization->>Authorization: Validate refs match
+        Authorization-->>GitHandler: Authorized (from_purgatory=false)
+    else No state in database - check purgatory
+        Authorization->>Purgatory: find_matching_states(identifier, pushed_refs, local_refs)
+        
+        alt Matching state in purgatory
+            Purgatory-->>Authorization: State event(s)
+            Authorization->>Authorization: Filter to authorized authors
+            Authorization->>Authorization: Find latest state
+            Authorization->>Authorization: Validate refs match
+            Authorization->>Purgatory: extend_expiry(15min)
+            Authorization-->>GitHandler: Authorized (from_purgatory=true)
+        else No matching state anywhere
+            Authorization-->>GitHandler: Rejected - no authorized state
         end
     end
-
-    Note over GitHandler: Only ONE approved state event per repo
-    alt Approved state event exists
-        GitHandler->>Purgatory: extend_expiry - event_id - ensure 15 min
-        GitHandler->>GitRepo: Execute git-receive-pack
-
-        alt Push successful
+    
+    alt Authorized
+        GitHandler->>GitProcess: Execute git-receive-pack
+        
+        alt Push succeeds AND from_purgatory=true
             GitHandler->>Database: Save state event
-            GitHandler->>GitRepo: Align ALL refs to state - including unpushed
-            GitHandler->>GitHandler: Sync to other authorized maintainer repos
-            GitHandler->>Purgatory: remove - event_id
+            GitHandler->>Purgatory: remove_state_event(identifier, event_id)
             GitHandler->>GitClient: Push accepted
-        else Push failed
-            GitHandler->>GitClient: Push rejected
+        else Push succeeds AND from_purgatory=false
+            GitHandler->>GitClient: Push accepted
+        else Push fails
+            GitHandler->>GitClient: Push rejected - git error
         end
-    else No approved state event
-        GitHandler->>GitClient: Push rejected - no authorized state
+    else Rejected
+        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
-
-    GitClient->>GitHandler: POST /npub/identifier/git-receive-pack refs/nostr/abc123
-    GitHandler->>GitHandler: Extract event_id from ref
-    GitHandler->>GitHandler: Extract pushed commit SHA
-
-    Note over GitHandler: First check relay database
-    GitHandler->>Database: Query for PR event with event_id
-
+    participant Database
+    participant GitProcess
+
+    GitClient->>GitHandler: POST /npub/id/git-receive-pack refs/nostr/abc123
+    GitHandler->>GitHandler: Extract event_id and commit from push
+    
+    Note over GitHandler: Check database first
+    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
-        GitHandler->>Purgatory: find_pr - event_id
-
+    else Event not in database - check purgatory
+        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 - event_id
+                GitHandler->>Purgatory: remove_pr(event_id)
                 GitHandler->>GitClient: Push accepted
             else Commit mismatch
                 GitHandler->>GitClient: Push rejected - commit mismatch
             end
-        else No PR event anywhere
-            Note over GitHandler: Git data first scenario
-            GitHandler->>GitRepo: Execute push - accept any data
-            GitHandler->>Purgatory: add_pr_placeholder - event_id, commit
+        else No PR event anywhere (git-data-first)
+            GitHandler->>GitProcess: Execute push - accept any 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
-sequenceDiagram
-    participant Handler
-    participant Database
-    participant Authorization
-    participant GitRepos
+Purgatory includes a background sync system that fetches git data from remote servers when events arrive before git data.
 
-    Handler->>Database: Get all announcements for identifier
-    Handler->>Authorization: collect_authorized_maintainers - announcements
-    Authorization-->>Handler: Map of owner -> authorized maintainers
+### Sync Architecture
 
-    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
-                Handler->>GitRepos: Align owner's repo to state event refs
-            else PR event
-                Handler->>GitRepos: Ensure refs/nostr/event-id exists
-            end
-        end
-    end
+### Sync Queue Entry
+
+```rust
+pub struct SyncQueueEntry {
+    /// When to attempt next sync
+    pub next_attempt: Instant,
+    
+    /// 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
-sequenceDiagram
-    participant Timer
-    participant Purgatory
+### Sync Delays
 
-    loop Every 60 seconds
-        Timer->>Purgatory: cleanup
+| Scenario | Delay | Reason |
+|----------|-------|--------|
+| 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
-        loop For each identifier in state_events
-            loop For each entry
-                alt now > expires_at
-                    Purgatory->>Purgatory: Remove entry
-                end
-            end
-        end
+### Domain Throttling
 
-        Note over Purgatory: Clean PR events
-        loop For each event_id in pr_events
-            alt now > entry.expires_at
-                Purgatory->>Purgatory: Remove entry
-            end
-        end
-    end
+```rust
+pub struct ThrottleManager {
+    /// Max requests per domain per minute
+    max_requests_per_minute: usize,
+    
+    /// Tracking window duration
+    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
-    pub fn new() -> Self;
-
-    // ==================== State Events ====================
+    /// Add a state event to purgatory
+    /// Automatically enqueues for sync with 3min delay
+    pub fn add_state(&self, event: Event, identifier: String, author: PublicKey);
+    
+    /// 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
-    /// Returns purgatory message for client response
-    pub fn add_state(&self, event: Event, identifier: String) -> String;
+### Finding Entries
 
-    /// Find state events that could be satisfied by pushed refs
-    /// Returns events where:
-    /// - All refs in event are either in pushed_refs OR already exist locally
-    /// - At least one ref in event is in pushed_refs (something to update)
+```rust
+impl Purgatory {
+    /// Find state events waiting for an identifier
+    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
-    /// 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>;
+### Removing Entries
 
-    /// Remove PR entry after successful processing
-    pub fn remove_pr(&self, event_id: &EventId);
+```rust
+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)
-    /// Returns count of removed entries
-    pub fn cleanup(&self) -> usize;
+```rust
+impl Purgatory {
+    /// 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
-    pub fn state_event_count(&self) -> usize;
-    pub fn pr_event_count(&self) -> usize;
-    pub fn pr_placeholder_count(&self) -> usize;
+### Sync Queue Management
 
-    /// Check if an event is in purgatory (either store)
-    pub fn contains(&self, event_id: &EventId) -> bool;
+```rust
+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> {
-    // Parse refs/heads/* and refs/tags/* tags
-    // Return vec of RefPair { ref_name, object_sha }
-}
+pub fn extract_refs_from_state(event: &Event) -> Vec<RefPair>;
 
 /// 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)
-/// - At least one ref in state_refs is actually being changed by the push
+/// - Every ref in state is either in pushed_refs OR in local_refs
+/// - 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
-
-### 1. Nip34WritePolicy Changes
+See [`src/purgatory/helpers.rs`](../../src/purgatory/helpers.rs) for implementation.
 
-```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)
-2. If accepted, check if we need to sync repos with the same identifier
+State and PR events are added to purgatory when git data doesn't exist:
 
 ```rust
+// From src/nostr/policy/state.rs
 async fn handle_state(&self, event: &Event) -> WritePolicyResult {
-    let identifier = extract_identifier(&event)?;
-    let author = event.pubkey;
-    let state_refs = extract_refs_from_state(&event);
-
-    // Check for existing state event from this author with larger created_at
-    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()
-            };
-        }
+    let identifier = extract_identifier(event)?;
+    
+    // Check if we have matching git data
+    if self.has_matching_git_data(&identifier, event).await? {
+        return WritePolicyResult::Accept;
     }
-
-    // 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()
-    }
-}
-```
-
-### 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()
+        message: "purgatory: awaiting git data".into()
     }
 }
 ```
 
-### 4. Git Handler Changes
+### 2. Git Push Authorization
 
-In `handle_receive_pack` for normal refs:
-
-**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>`.
+Authorization checks both database and purgatory:
 
 ```rust
-async fn handle_state_refs_push(
-    &self,
+// From src/git/authorization.rs
+pub async fn authorize_push(
+    database: &SharedDatabase,
     identifier: &str,
-    repo_owner: &str,
-    pushed_refs: &[RefPair],
-) -> Result<Option<Event>, GitError> {
-    let local_refs = git::list_refs(&self.repo_path)?;
-
-    // Find matching state events
-    let candidates = self.purgatory.find_matching_states(
-        identifier,
-        pushed_refs,
-        &local_refs,
-    );
-
-    // Get all state events from relay for this identifier
-    let relay_states = self.database.get_state_events_for_identifier(identifier).await?;
-
-    // Get announcements to determine authorization
-    let announcements = self.database.get_announcements(identifier).await?;
-    let auth_map = collect_authorized_maintainers(&announcements);
-
-    // Find the authoritative state event (largest created_at among all authorized)
-    let mut best_candidate: Option<(Event, Timestamp)> = None;
-
-    // Check purgatory candidates
-    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));
+    owner_pubkey: &str,
+    request_body: &Bytes,
+    purgatory: &Arc<Purgatory>,  // Critical!
+    repo_path: &std::path::Path,
+) -> anyhow::Result<AuthorizationResult> {
+    // Parse pushed refs
+    let pushed_refs = parse_pushed_refs(request_body);
+    
+    // Check database for state events
+    let db_result = get_authorization_from_db(database, identifier).await?;
+    
+    if !db_result.authorized {
+        // No state in database - check purgatory
+        let purgatory_result = get_state_authorization_for_specific_owner_repo(
+            database,
+            identifier,
+            owner_pubkey,
+            purgatory,
+            &pushed_refs,
+            repo_path,
+        ).await?;
+        
+        return purgatory_result;
     }
-
-    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(
-    &self,
-    event_id: &str,
-    pushed_commit: &str,
-) -> Result<PushDecision, GitError> {
-    // Check database first
-    if let Some(event) = self.database.get_event_by_id(event_id).await? {
-        let expected_commit = extract_c_tag_commit(&event)?;
-        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()));
-        }
+// From src/git/handlers.rs
+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);
     }
-
-    // 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
-// During startup
-let purgatory = Arc::new(Purgatory::new());
+Started during application initialization:
 
-// Pass to WritePolicy
-let write_policy = Nip34WritePolicy::new(
-    &config.domain,
+```rust
+// From src/main.rs
+let purgatory = Arc::new(Purgatory::new(git_data_path));
+let ctx = Arc::new(RealSyncContext::new(
     database.clone(),
-    &git_data_path,
     purgatory.clone(),
-);
-
-// Pass to git handlers (via shared state)
-let git_state = GitState {
-    purgatory: purgatory.clone(),
-    database: database.clone(),
-    // ...
-};
-
-// Spawn cleanup task
-let purgatory_cleanup = purgatory.clone();
-tokio::spawn(async move {
+    config.domain.clone(),
+    git_data_path.clone(),
+));
+let throttle_manager = Arc::new(ThrottleManager::new(5, 30));
+throttle_manager.set_context(ctx.clone());
+
+// Start sync loop
+let sync_handle = purgatory.clone().start_sync_loop(ctx, throttle_manager);
+
+// Start cleanup task
+let cleanup_handle = tokio::spawn(async move {
     let mut interval = tokio::time::interval(Duration::from_secs(60));
     loop {
         interval.tick().await;
-        let removed = purgatory_cleanup.cleanup();
-        if removed > 0 {
-            tracing::debug!("Purgatory cleanup removed {} expired entries", removed);
+        let (state_removed, pr_removed) = purgatory.cleanup();
+        if state_removed + pr_removed > 0 {
+            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
-│   ��── pr_events.rs        # PR event purgatory logic
-│   ��── helpers.rs          # extract_refs_from_state, can_satisfy_state, etc.
-├── nostr/
-│   ├── builder.rs          # Modified: Nip34WritePolicy accepts Arc<Purgatory>
-│   ��── policy/
-│       ├── state.rs        # Modified: handle_state uses purgatory
-│       └── pr_event.rs     # Modified: handle_pr_event uses purgatory
+│   ├── helpers.rs          # Ref extraction and matching functions
+│   ��── sync/
+│       ��── mod.rs          # Sync module exports
+��       ��── loop.rs         # Background sync loop
+│       ├── functions.rs    # sync_identifier, sync_identifier_from_url
+│       ��── context.rs      # SyncContext trait and RealSyncContext
+│       ├── queue.rs        # SyncQueueEntry
+│       └── throttle.rs     # ThrottleManager, DomainThrottle
 ├── git/
-│   └── handlers.rs         # Modified: handle_receive_pack integrates purgatory
-└── main.rs                 # Modified: creates Purgatory, spawns cleanup task
+│   ├── authorization.rs    # authorize_push with purgatory checking
+│   ├── 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
-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
+### Unit Tests
 
-### PR Event Tests
+Located in each module:
 
-1. **PR event arrives, git data exists** - Event processed immediately, saved to DB
-2. **PR event arrives, no git data** - Event goes to purgatory awaiting git push
-3. **PR event arrives, placeholder exists with matching commit** - Event released, saved to DB
-4. **PR event arrives, placeholder exists with different commit** - Ref deleted, event to purgatory
-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
+- **[`src/purgatory/mod.rs`](../../src/purgatory/mod.rs)** - Core purgatory operations
+- **[`src/purgatory/helpers.rs`](../../src/purgatory/helpers.rs)** - Ref matching logic
+- **[`src/purgatory/sync/functions.rs`](../../src/purgatory/sync/functions.rs)** - Sync functions with MockSyncContext
+- **[`src/purgatory/sync/throttle.rs`](../../src/purgatory/sync/throttle.rs)** - Throttle manager
 
-### Edge Cases (NOT TESTED)
+### Integration Tests
 
-1. **Relay restart** - All purgatory entries lost (acceptable per design)
-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
+Located in [`tests/`](../../tests/):
 
+- **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:**
-1. State event arrives → No git data exists → Event stored in PURGATORY (not database)
-2. Git push arrives → Authorization checks DATABASE only → No state found → **PUSH REJECTED** ❌
-3. Purgatory check runs → But push already failed, so this never helps
+Without checking purgatory during authorization, we have a deadlock:
+- State event goes to purgatory (no git data)
+- Push is rejected (no state in database)
+- Event never gets released
 
-### The Fix: Authorization-Time Purgatory Check
+**Solution:** `authorize_push()` checks both database and purgatory.
 
-**Correct flow (implemented):**
-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
+### 2. Late Binding for State Events
 
-### 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
-pub struct AuthorizationResult {
-    pub authorized: bool,
-    pub reason: String,
-    pub state: Option<RepositoryState>,
-    pub maintainers: Vec<String>,
-    pub from_purgatory: bool,  // NEW: Track event source
-}
-```
+PR events can arrive before or after git data:
+- Event first → Wait for git push
+- Git first → Create placeholder, wait for event
 
-#### 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
-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>
-```
+When events arrive in bursts (e.g., negentropy sync), we don't want to spawn a sync task for each event.
 
-**Logic**:
-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`
+**Solution:** `enqueue_sync()` resets `attempt_count` and updates `next_attempt` if already queued.
 
-#### 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
-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);
-    }
-}
-```
+**Solution:** `ThrottleManager` maintains per-domain queues and processes them when capacity frees.
 
-### 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:
-1. State event is sent to relay (goes to purgatory - no git data yet)
-2. Git push is sent (uses purgatory state for authorization)
-3. State event is released from purgatory to database
+- [Inline Authorization](inline-authorization.md) - Why purgatory checking during authorization is essential
+- [Architecture Overview](architecture.md) - Full system design
+- [Background Sync](../how-to/purgatory-sync.md) - How to configure and monitor sync
+- [Test Strategy](../reference/test-strategy.md) - How we test purgatory
 
 ---
 
+*Part of the [ngit-grasp explanation docs](./)*