ngit-grasp/3ca0-announcements-purgatory.md

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
• Created worktree: worktrees/3ca0-announcements-purgatory
• Ready to begin implementation

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?