issue: create 3ca0 - announcements purgatory system

3ca0-announcements-purgatory.md

@@ -0,0 +1,81 @@
+# Announcements Purgatory System
+
+**ID:** 3ca0
+
+## Problem
+
+Currently, acceptable announcements that don't replace existing announcements are immediately accepted and served to clients. We need a "purgatory" system where new announcements are held in a pending state until they become relevant (when a corresponding state event arrives).
+
+This prevents serving announcements for repositories that may never receive state events, while still maintaining the git infrastructure in case they do.
+
+## Requirements
+
+### 1. Purgatory Instead of Immediate Acceptance
+- Acceptable announcements that do not replace an existing announcement should go to purgatory instead of being immediately accepted and served
+- The bare git repo should still be created when an announcement enters purgatory
+- Announcements should not be served to clients while in purgatory
+
+### 2. Expiry and Cleanup
+- If an announcement expires while in purgatory, the bare git repo should be deleted
+- Need to track expiry times for announcements in purgatory
+- Background cleanup mechanism to handle expired purgatory announcements
+
+### 3. State Event Interaction
+- When a state event arrives, any announcements in purgatory should have their expiry extended to match the state event's expiry
+- This keeps purgatory announcements alive as long as they might become relevant
+- Need to determine when/how announcements transition from purgatory to active
+
+### 4. State Event Acceptability
+- State event acceptability checks must consider announcements in purgatory
+- A state event should be rejected if it would conflict with announcements in purgatory (not just active announcements)
+- Validation logic needs to check both active and purgatory announcements
+
+## Plan
+
+- [ ] Phase 1: Design data structures for purgatory tracking
+  - Define purgatory announcement storage structure
+  - Determine what metadata needs tracking (expiry, repo path, etc.)
+  - Design interface for purgatory operations
+  
+- [ ] Phase 2: Implement purgatory storage and lifecycle
+  - Add purgatory data structure to relay state
+  - Implement add/remove/query operations for purgatory
+  - Create background task for expiry cleanup
+  - Handle git repo deletion on expiry
+  
+- [ ] Phase 3: Modify announcement acceptance logic
+  - Route new announcements to purgatory vs active
+  - Ensure git repo is still created for purgatory announcements
+  - Prevent serving purgatory announcements to clients
+  
+- [ ] Phase 4: Update state event validation
+  - Modify acceptability checks to include purgatory
+  - Implement expiry extension for purgatory announcements
+  - Define transition logic from purgatory to active
+  
+- [ ] Phase 5: Testing and documentation
+  - Add unit tests for purgatory operations
+  - Add integration tests for announcement/state event interactions
+  - Document the purgatory system behavior
+
+## Progress
+
+### 2026-01-23 [Session 00:00]
+- Started: Created issue with requirements and initial plan
+
+## Implementation Considerations
+
+- **Data Structure**: Need separate storage for purgatory announcements (HashMap keyed by repo identifier?)
+- **Expiry Tracking**: Store expiry timestamp with each purgatory announcement
+- **Background Task**: Periodic cleanup task to check for expired purgatory announcements
+- **Git Repo Management**: Ensure repo creation happens for purgatory, deletion on expiry
+- **Transition Logic**: When does an announcement leave purgatory? (When state event arrives? When it would replace an active announcement?)
+- **Query Performance**: State event validation needs to efficiently check both active and purgatory
+- **Concurrency**: Ensure thread-safe access to purgatory data structure
+
+## Notes
+
+- This feature prevents resource waste on announcements that never receive state events
+- Maintains quick response time for repositories that do become active
+- Need to clarify: What triggers transition from purgatory to active? Just state event arrival?
+- Consider: Should there be a maximum purgatory size or time limit?