From 3516343d0c49d23c99080a8120c208a7ae0e7cc1 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Fri, 23 Jan 2026 11:49:41 +0000 Subject: [PATCH] issue: create 3ca0 - announcements purgatory system --- 3ca0-announcements-purgatory.md | 81 +++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) create mode 100644 3ca0-announcements-purgatory.md diff --git a/3ca0-announcements-purgatory.md b/3ca0-announcements-purgatory.md new file mode 100644 index 0000000..12bfd66 --- /dev/null +++ b/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?