feat: announcement purgatory

Extends purgatory to hold repository announcements until git data arrives,
preventing empty repositories from being served to clients.

When an announcement is received, a bare repo is created immediately and the
announcement is held in purgatory. It is only promoted and served once a git
push confirms real content exists. If no push arrives before expiry, the bare
repo is deleted and the announcement is silently discarded.

Key behaviours:
- Soft expiry: announcements are hidden from clients but kept alive while git
  pushes are in progress, reviving on successful push
- Expiry is extended when a matching state event or git push is observed
- NIP-09 deletion events remove announcements from purgatory
- Purgatory state (announcements, state events, PR events, expired set) is
  persisted to disk on graceful shutdown and restored on startup, with elapsed
  downtime subtracted from expiry deadlines
- Purgatory announcements drive StateOnly sync in the sync system so state
  events are fetched from listed relays before promotion
- SyncLevel added to RepoSyncIndex to distinguish purgatory repos (StateOnly)
  from promoted repos (Full L2+L3 sync)

1 files changed, 263 insertions, 10 deletions

diff --git a/src/nostr/policy/announcement.rs b/src/nostr/policy/announcement.rs
index 15a6e58..b366f0b 100644
--- a/src/nostr/policy/announcement.rs
+++ b/src/nostr/policy/announcement.rs
@@ -3,6 +3,8 @@
 /// Handles validation of NIP-34 repository announcements (kind 30617)
 /// according to GRASP-01 specification.
 use nostr_relay_builder::prelude::{Alphabet, Event, Filter, Kind, PublicKey, SingleLetterTag};
+use std::collections::HashSet;
+use std::time::Duration;
 
 use super::PolicyContext;
 use crate::config::Config;
@@ -11,12 +13,14 @@ use crate::nostr::events::{validate_announcement, RepositoryAnnouncement};
 /// Result of announcement policy evaluation
 #[derive(Debug, Clone, PartialEq)]
 pub enum AnnouncementResult {
-    /// Accept: Event lists our service (GRASP-01 compliant)
+    /// Accept: Event lists our service (GRASP-01 compliant) - replacement announcement
     Accept,
     /// Accept as maintainer: Event accepted via maintainer exception (multi-maintainer)
     AcceptMaintainer,
     /// Accept as archive: Event accepted via GRASP-05 archive whitelist (read-only)
     AcceptArchive,
+    /// Accept to purgatory: New announcement, waiting for git data
+    AcceptPurgatory,
     /// Reject: Event fails validation with reason
     Reject(String),
 }
@@ -35,10 +39,13 @@ impl AnnouncementPolicy {
 
     /// Validate a repository announcement event
     ///
-    /// Returns `Accept` if the announcement lists the service properly,
-    /// `AcceptMaintainer` if accepted via maintainer exception,
-    /// `AcceptArchive` if accepted via GRASP-05 archive config,
-    /// or `Reject` with reason.
+    /// Returns:
+    /// - `Accept` if this is a replacement announcement (active announcement exists in DB or
+    ///   purgatory)
+    /// - `AcceptPurgatory` if this is a new announcement (no active announcement exists)
+    /// - `AcceptMaintainer` if accepted via maintainer exception
+    /// - `AcceptArchive` if accepted via GRASP-05 archive config
+    /// - `Reject` with reason if validation fails
     pub async fn validate(&self, event: &Event) -> AnnouncementResult {
         // First, try validation (GRASP-01 + GRASP-05)
         let validation_result = validate_announcement(event, &self.config);
@@ -49,6 +56,23 @@ impl AnnouncementPolicy {
                 // GRASP-01 Exception: Accept announcements from recursive maintainers
                 match RepositoryAnnouncement::from_event(event.clone()) {
                     Ok(announcement) => {
+                        // If this pubkey+identifier has a purgatory entry AND the incoming
+                        // event is strictly newer, the owner is sending a replacement that
+                        // removes our service. Clear the purgatory entry and its bare repo.
+                        //
+                        // If the incoming event is older than the purgatory entry (e.g. a
+                        // relay replay of a superseded announcement), ignore it — the newer
+                        // purgatory entry takes precedence and must not be evicted.
+                        let should_evict = self
+                            .ctx
+                            .purgatory
+                            .find_announcement(&event.pubkey, &announcement.identifier)
+                            .is_some_and(|entry| event.created_at > entry.event.created_at);
+
+                        if should_evict {
+                            self.remove_purgatory_announcement(&event.pubkey, &announcement.identifier);
+                        }
+
                         match self
                             .is_maintainer_in_any_announcement(
                                 &announcement.identifier,
@@ -67,11 +91,221 @@ impl AnnouncementPolicy {
                     Err(_) => AnnouncementResult::Reject(reason),
                 }
             }
-            // Accept, AcceptArchive, or AcceptMaintainer - return as-is
+            AnnouncementResult::Accept | AnnouncementResult::AcceptArchive => {
+                // Parse announcement to check for existing active announcement
+                match RepositoryAnnouncement::from_event(event.clone()) {
+                    Ok(announcement) => {
+                        let in_db = match self
+                            .has_db_announcement(&event.pubkey, &announcement.identifier)
+                            .await
+                        {
+                            Ok(v) => v,
+                            Err(e) => {
+                                tracing::warn!(
+                                    error = %e,
+                                    "Failed to check for existing DB announcement - rejecting"
+                                );
+                                return AnnouncementResult::Reject(format!(
+                                    "Database error checking existing announcement: {}",
+                                    e
+                                ));
+                            }
+                        };
+
+                        if in_db {
+                            // Replacement announcement with DB entry - accept immediately
+                            tracing::debug!(
+                                identifier = %announcement.identifier,
+                                "Replacement announcement (DB) - accepting immediately"
+                            );
+                            return validation_result;
+                        }
+
+                        let in_purgatory = self
+                            .ctx
+                            .purgatory
+                            .has_purgatory_announcement(&event.pubkey, &announcement.identifier);
+
+                        if in_purgatory {
+                            // Replacement announcement with purgatory entry - replace it and
+                            // extend expiry so the new announcement gets a fresh 30-minute window.
+                            tracing::debug!(
+                                identifier = %announcement.identifier,
+                                "Replacement announcement (purgatory) - replacing purgatory entry"
+                            );
+                            self.replace_purgatory_announcement(event, &announcement);
+                            // Return Accept (not AcceptPurgatory) - this is a replacement, not new
+                            return validation_result;
+                        }
+
+                        // No existing announcement - route to purgatory
+                        tracing::debug!(
+                            identifier = %announcement.identifier,
+                            "New announcement - routing to purgatory"
+                        );
+                        AnnouncementResult::AcceptPurgatory
+                    }
+                    Err(e) => AnnouncementResult::Reject(format!(
+                        "Failed to parse announcement: {}",
+                        e
+                    )),
+                }
+            }
+            // AcceptPurgatory shouldn't come from validate_announcement, but handle it
             result => result,
         }
     }
 
+    /// Replace a purgatory announcement entry with a newer event.
+    ///
+    /// Called when a replacement announcement arrives for a (pubkey, identifier) pair
+    /// that is currently in purgatory. Updates the purgatory entry and extends the
+    /// expiry so the new announcement has a fresh waiting window.
+    fn replace_purgatory_announcement(
+        &self,
+        event: &Event,
+        announcement: &RepositoryAnnouncement,
+    ) {
+        let repo_path = self.ctx.git_data_path.join(announcement.repo_path());
+        let relays: HashSet<String> = announcement.relays.iter().cloned().collect();
+
+        // add_announcement uses the (owner, identifier) key so it overwrites the old entry
+        self.ctx.purgatory.add_announcement(
+            event.clone(),
+            announcement.identifier.clone(),
+            event.pubkey,
+            repo_path,
+            relays,
+        );
+
+        // Extend the announcement's expiry (reset to full 30 min window)
+        self.ctx.purgatory.extend_announcement_expiry(
+            &event.pubkey,
+            &announcement.identifier,
+            Duration::from_secs(1800),
+        );
+
+        // Also extend any state events waiting for this identifier
+        let state_entries = self.ctx.purgatory.find_state(&announcement.identifier);
+        if !state_entries.is_empty() {
+            let state_ids: Vec<_> = state_entries.iter().map(|e| e.event.id).collect();
+            self.ctx.purgatory.extend_expiry(
+                &announcement.identifier,
+                &state_ids,
+                Duration::from_secs(1800),
+            );
+        }
+    }
+
+    /// Remove a purgatory announcement and clean up associated resources.
+    ///
+    /// Called when a replacement announcement is rejected (owner removed our service).
+    /// Deletes the bare repository from disk and removes any state events waiting for
+    /// this identifier.
+    fn remove_purgatory_announcement(&self, pubkey: &PublicKey, identifier: &str) {
+        // Get the repo path before removing from purgatory
+        if let Some(entry) = self.ctx.purgatory.find_announcement(pubkey, identifier) {
+            // Delete the bare repository from disk
+            if entry.repo_path.exists() {
+                if let Err(e) = std::fs::remove_dir_all(&entry.repo_path) {
+                    tracing::warn!(
+                        path = %entry.repo_path.display(),
+                        error = %e,
+                        "Failed to delete bare repository during purgatory cleanup"
+                    );
+                } else {
+                    tracing::info!(
+                        path = %entry.repo_path.display(),
+                        "Deleted bare repository for rejected purgatory announcement"
+                    );
+                }
+            }
+        }
+
+        // Remove the announcement from purgatory
+        self.ctx.purgatory.remove_announcement(pubkey, identifier);
+
+        // Only remove state events if no other owner still has an announcement in purgatory
+        // for this identifier. State events are keyed by identifier alone, so blindly removing
+        // them would also discard state events legitimately belonging to a different owner's
+        // repository that happens to share the same identifier string.
+        let other_owners_remain = !self
+            .ctx
+            .purgatory
+            .get_announcements_by_identifier(identifier)
+            .is_empty();
+
+        if !other_owners_remain {
+            self.ctx.purgatory.remove_state(identifier);
+        }
+
+        tracing::info!(
+            identifier = %identifier,
+            other_owners_remain = %other_owners_remain,
+            "Cleared purgatory entry: owner removed our service from announcement"
+        );
+    }
+
+    /// Check if there's an announcement in the database for this (pubkey, identifier).
+    ///
+    /// Only checks the database (promoted announcements). For purgatory checks use
+    /// `purgatory.has_purgatory_announcement()` directly.
+    async fn has_db_announcement(
+        &self,
+        pubkey: &PublicKey,
+        identifier: &str,
+    ) -> Result<bool, String> {
+        let filter = Filter::new()
+            .kind(Kind::GitRepoAnnouncement)
+            .author(*pubkey)
+            .custom_tag(
+                SingleLetterTag::lowercase(Alphabet::D),
+                identifier.to_string(),
+            );
+
+        let events: Vec<Event> = match self.ctx.database.query(filter).await {
+            Ok(events) => events.into_iter().collect(),
+            Err(e) => return Err(format!("Database query failed: {}", e)),
+        };
+
+        Ok(!events.is_empty())
+    }
+
+    /// Add an announcement to purgatory
+    ///
+    /// Creates the bare repository and stores the announcement in purgatory
+    /// until git data arrives.
+    pub fn add_to_purgatory(&self, event: &Event) -> Result<(), String> {
+        let announcement = RepositoryAnnouncement::from_event(event.clone())
+            .map_err(|e| format!("Failed to parse announcement: {}", e))?;
+
+        // Create bare repository
+        self.ensure_bare_repository(&announcement)?;
+
+        // Build repo path
+        let repo_path = self.ctx.git_data_path.join(announcement.repo_path());
+
+        // Extract relays from announcement
+        let relays: HashSet<String> = announcement.relays.iter().cloned().collect();
+
+        // Add to purgatory
+        self.ctx.purgatory.add_announcement(
+            event.clone(),
+            announcement.identifier.clone(),
+            event.pubkey,
+            repo_path,
+            relays,
+        );
+
+        tracing::info!(
+            identifier = %announcement.identifier,
+            event_id = %event.id,
+            "Added announcement to purgatory"
+        );
+
+        Ok(())
+    }
+
     /// Create a bare git repository if it doesn't exist
     /// Path format: <git_data_path>/<npub>/<identifier>.git
     pub fn ensure_bare_repository(
@@ -117,6 +351,11 @@ impl AnnouncementPolicy {
     ///
     /// This enables accepting announcements from maintainers even when they don't list
     /// this GRASP server, for maintainer chain discovery and GRASP-02 sync.
+    ///
+    /// Checks both the database (promoted announcements) and purgatory (announcements
+    /// waiting for git data). This is necessary because a maintainer's announcement
+    /// (which lists the recursive maintainer) may still be in purgatory when the
+    /// recursive maintainer's announcement arrives.
     async fn is_maintainer_in_any_announcement(
         &self,
         identifier: &str,
@@ -128,12 +367,26 @@ impl AnnouncementPolicy {
             identifier.to_string(),
         );
 
-        let announcements: Vec<Event> = match self.ctx.database.query(filter).await {
+        let db_announcements: Vec<Event> = match self.ctx.database.query(filter).await {
             Ok(events) => events.into_iter().collect(),
             Err(e) => return Err(format!("Database query failed: {}", e)),
         };
 
-        if announcements.is_empty() {
+        // Also collect purgatory announcements for this identifier
+        let purgatory_announcements: Vec<Event> = self
+            .ctx
+            .purgatory
+            .get_announcements_by_identifier(identifier)
+            .into_iter()
+            .map(|entry| entry.event)
+            .collect();
+
+        let all_announcements: Vec<&Event> = db_announcements
+            .iter()
+            .chain(purgatory_announcements.iter())
+            .collect();
+
+        if all_announcements.is_empty() {
             // No existing announcements for this identifier - author cannot be a maintainer
             return Ok(false);
         }
@@ -141,14 +394,14 @@ impl AnnouncementPolicy {
         let author_hex = author.to_hex();
 
         // Check each announcement to see if author is listed as a maintainer
-        for event in &announcements {
+        for event in &all_announcements {
             // Check if author is the owner of this announcement
             if event.pubkey == *author {
                 return Ok(true);
             }
 
             // Check if author is listed in the maintainers tag
-            if let Ok(announcement) = RepositoryAnnouncement::from_event(event.clone()) {
+            if let Ok(announcement) = RepositoryAnnouncement::from_event((*event).clone()) {
                 if announcement.maintainers.contains(&author_hex) {
                     return Ok(true);
                 }