ngit-grasp/docs/explanation/repository-lifecycle.md

Repository Lifecycle (Deletion, Holding, Archive, and Recovery)

Overview

ngit-grasp owns the lifecycle of repository-related nostr events and git data when a served repository scope is removed, restored, or quarantined. This covers NIP-09 deletion requests, NIP-62 request-to-vanish events, operator blacklist and whitelist reconciliation, service de-listing, holding/archive retention, recovery, and purgatory transitions.

Core consistency invariant

ngit-grasp enforces the following invariant across admission, serving, deletion, and recovery:

Served nostr state must always match git refs we can actually serve.

This invariant is the design center for lifecycle handling and a key rationale for purgatory. If the currently served repository state is removed and no valid rollback state exists, the relay must stop serving that state, park the announcement scope in purgatory, and wait for a promotable state before serving again.

Ownership of lifecycle behavior

ngit-grasp disables backend auto-processing and owns NIP-09/NIP-62 lifecycle handling in relay policy code:

• main DB uses process_nip09(false) and process_nip62(false) (src/nostr/builder.rs)
• tombstones DB uses process_nip09(false) and process_nip62(false) (src/nostr/lifecycle/tombstones.rs)
• holding DB uses process_nip09(false) and process_nip62(false) (src/nostr/lifecycle/holding.rs)

This keeps lifecycle behavior auditable and prevents the storage backends from silently applying deletion semantics outside ngit-grasp policy code.

The full cascade, holding, archive, and lifecycle flow applies consistently to NIP-09 repository/content deletions, targeted NIP-62 request-to-vanish events, and operator-driven blacklist/whitelist deletions. NIP-62 additionally records a vanish tombstone: archived payloads can remain in holding for retention and cleanup, but the tombstone continues to gate new events from that pubkey unless an explicit tombstone-removal path is introduced.

The Left-Pad Problem

The "left-pad problem" refers to a 2016 incident where a critical npm package was unpublished, breaking thousands of dependent projects. In the context of decentralized Git hosting, this translates to:

Scenario: A popular repository with many PRs, issues, and community contributions gets deleted by its owner. All dependent work (forks, patches, discussions) becomes inaccessible, potentially breaking workflows and losing community knowledge.

Our Solution: The deletion-request-disrespector configuration option allows operators to run archival relays that preserve deleted content, ensuring community work survives repository deletion while still respecting deletion requests on standard relays.

Architecture

Three-Database Design

The repository lifecycle system uses three relay databases plus archive filesystem storage:

┌─────────────────────────────────────────────────────────┐
│                    Main Database                        │
│         (Live events - actively served)                 │
│    LMDB/Memory backend                                 │
└─────────────────────────────────────────────────────────┘
                         ↓ deletion request
┌─────────────────────────────────────────────────────────┐
│                 Tombstones Database                     │
│     (Kind-5 / Kind-62 requests, deletion gate state)   │
│      Derived state: deleted IDs/coords/vanished keys   │
└─────────────────────────────────────────────────────────┘
                         ↓ delete acceptance gate
┌─────────────────────────────────────────────────────────┐
│                 Holding Database                        │
│    (Archived events - recovery window)                 │
│    Same backend type as main                           │
│    Retention: configurable (default 90 days)           │
└─────────────────────────────────────────────────────────┘
                         ↓ expiry
┌─────────────────────────────────────────────────────────┐
│              Permanent Deletion                         │
│         (Events removed from holding DB)                │
└─────────────────────────────────────────────────────────┘

                    Git Data Flow
┌─────────────────────────────────────────────────────────┐
│          Git Repository (Live)                          │
│    <git_data_path>/<npub>/<identifier>.git             │
└─────────────────────────────────────────────────────────┘
                         ↓ deletion request
┌─────────────────────────────────────────────────────────┐
│           Archive Filesystem                            │
│    .archive/<npub>/<identifier>-<timestamp>.tar.gz     │
│    Metadata is stored as holding DB events/tags         │
│    Retention: configurable (default 90 days)           │
└─────────────────────────────────────────────────────────┘
                         ↓ expiry
┌─────────────────────────────────────────────────────────┐
│              Permanent Deletion                         │
│         (Archive files removed)                         │
└─────────────────────────────────────────────────────────┘

Why Three Stores?

1. Main Database: Fast queries, clean data model (deleted = gone)
2. Tombstones Database: Durable deletion/vanish state for admission-time gating
3. Holding Database: Recovery mechanism, prevents accidental permanent deletion

Archive files on disk complement the DB layers by preserving repository git data during the retention window.

Holding Database Operations

Automatic Operations:

• Move to holding: NIP-09 deletions, targeted NIP-62 vanish removals, blacklist/whitelist deletions
• Automatic recovery: Re-publishing after NIP-09 deletion or operator-driven blacklist/whitelist restoration (within retention window). NIP-62 holding records are retained for safety/cleanup, but recovery of events authored by the vanished pubkey remains blocked by the vanish tombstone.
• Expiry cleanup: Daily background task removes entries older than retention period

Manual Operations:

• Manual ejection: Operator force-deletes before retention expires
  • Use case: Large repos consuming excessive storage
  • Use case: Confirmed malware requiring immediate permanent deletion
  • Mechanism: ngit-grasp holding-eject --owner <npub|hex> --identifier <id>
  • Logged for audit trail
• Legacy empty-repository cleanup:
  • Mechanism: ngit-grasp cleanup-empty-repos
  • Removes empty git repository directories that no longer have useful backing data.
  • This is intentionally narrow. A fuller maintenance cleanup command is a planned replacement, not part of the current deletion cascade.

Maintenance Cleanup Command (safe vs destructive)

ngit-grasp maintenance cleanup is planned as the replacement for the narrow legacy cleanup command. Its intended role is a full repository integrity sweep, not reuse of the live NIP-09 deletion-cascade planner.

The command should analyze the full relay/git data set and compute the state the relay should keep:

1. Start from accepted repository announcements.
2. Recursively mark repository-related events that remain valid through accepted references.
3. Independently retain GRASP-06 PR and PR-update events only when their backing git data exists and is consistent.
4. Treat unmarked repository-related events as cleanup candidates.
5. Reconcile repository git directories, 30618 state events, PR git data, and PR/PR-update events so served nostr state matches filesystem git data.

The command should be dry-run by default. Mutations should require explicit --execute, with destructive pruning of non-empty git data and unresolved missing-git scopes gated by separate opt-in flags and optional age thresholds. Reports should include candidate event deletions, orphan git directories, degraded state events, and PR/git mismatches before any destructive cleanup.

Migration from cleanup-empty-repos

cleanup-empty-repos remains the current legacy command. It should not be treated as a general database/git-data repair mechanism, and it should not grow ad hoc cascade-reconciliation behavior.

The intended migration is to introduce ngit-grasp maintenance cleanup in a separate change as the operator-facing replacement. That command should first ship as a read-only analyzer, then add explicit --execute mutations once the full-state sweep reports and invariants are well covered. After the replacement is proven, cleanup-empty-repos can be retained as a compatibility alias or deprecated in favor of the maintenance command.

• Blacklist restoration policy: optional startup auto-restore
  • Controlled by NGIT_BLACKLIST_AUTO_RESTORE (default false)
  • Restores only holding-source=blacklist scopes that are now unblacklisted and still within holding retention
  • Still-blacklisted scopes are skipped

Lifecycle Removal Flows

Standard Mode (Respects Deletions)

NIP-09 Deletion Requests

1. Kind 5 deletion request arrives
   ↓
2. Check idempotency:
   - if every actionable `e`/`a` target is already covered by an existing
     same-author kind-5 request, return a duplicate success response without
     storing the new deletion event
   - `e` targets are covered by any existing same-author deletion for that id
   - `a` targets are covered only when an existing same-author deletion for the
     same coordinate has `created_at >=` the new deletion request, preserving
     NIP-09 coordinate cutoff semantics
   ↓
3. Validate targets:
   - `e` targets found in the main DB must be authored by the deleter;
     cross-author main-DB targets reject the whole request
   - pre-emptive `e` deletes for unknown targets may be accepted, but if the
     target later arrives from a different author, the stale deletion request is
     removed from both tombstones and the served deletion-request stream
   - `a` coordinates are acted on only when coordinate pubkey matches deleter
   ↓
4. Record deletion tombstone so re-submission is gated
   ↓
5. Compact superseded deletion requests:
   - after the new tombstone is recorded, remove older same-author kind-5
     requests from the tombstone DB and served main DB when every actionable
     target in the older request is covered by the new request
   - a newer `a`-tag cutoff supersedes an older cutoff for the same coordinate;
     `e` targets must still be present in the new request
   - removal uses the database delete path so event-id/kind/tag indexes stay in
     sync with event storage
   ↓
6. Process targets:
   - `a` tag targeting a kind-30617 announcement coordinate:
     recursively discover the accepted-reference component affected by the
     announcement deletion
   - `e` tag targeting an active kind-30618 repository state:
     delete the targeted state and attempt rollback from replaceable history;
     if no valid active state remains, move the affected announcement scope
     through cascade/holding into purgatory
   - `e` tag targeting an active kind-30617 repository announcement:
     delete the targeted announcement and attempt rollback from replaceable
     history; this path does not run generic graph cascade when no history
     candidate exists
   - other valid `e`/`a` targets: delete the targeted event/coordinate without
     announcement graph cascade
   ↓
7. Archive git repository to .archive/<npub>/<identifier>-<timestamp>.tar.gz
   when deleting a repository announcement with live git data
   ↓
8. Move deleted events to holding database:
   - Targeted events
   - Repository announcements, when announcement deletion is involved
   - All main-DB events that lose their accepted-reference path after cascade
     reevaluation, for cascade paths
   - Deletion metadata for retention/cleanup/recovery
   ↓
9. Delete events from main database
   ↓
10. Remove the live git repository when the owner+identifier announcement scope
   is no longer served
   ↓
11. Deleted/tombstoned targets no longer serve in queries
   ↓
12. Background task (daily):
    - Check holding database for expired entries
    - Delete events older than retention period
    - Delete corresponding archive files

Deletion gate checks tombstones before kind-specific admission and rejects:

• events from vanished pubkeys,
• re-submission of deleted event IDs,
• replaceable/addressable events covered by coordinate tombstones.

NIP-62 Vanish Requests

1. Kind 62 request-to-vanish arrives
   ↓
2. Validate relay targeting with NIP-62 rules:
   - `ALL_RELAYS` requests are actioned
   - relay URL targets matching this relay are actioned (`NGIT_DOMAIN` is
     interpreted as `wss://<domain>` and `ws://<domain>` when configured without
     a scheme)
   - non-targeting requests are accepted/stored but not actioned
   ↓
3. Record vanish tombstone so future events from that pubkey are gated
   ↓
4. For every live kind-30617 announcement authored by the vanished pubkey:
   - Recursively discover the accepted-reference component
   - Archive git repository to .archive/<npub>/<identifier>-<timestamp>.tar.gz
   - Move announcement and newly orphaned dependents to holding DB with
     holding-source=nip62
   - Delete those events from the main DB
   ↓
5. Move any remaining main-DB events authored by the vanished pubkey to holding
   with holding-source=nip62, then delete them from the main DB
   ↓
6. Evict the vanished author's purgatory entries

The vanish tombstone is intentionally independent from holding retention. A future re-announcement cannot bypass the vanish gate: recovery may preserve data for operators and cleanup, but publishing new events from the vanished pubkey is still rejected unless the relay gains an intentional tombstone-removal workflow.

Blacklist-Triggered Deletion

When a repository is added to NGIT_REPOSITORY_BLACKLIST, the same deletion flow applies:

1. Startup: Scan main DB for repos matching blacklist
   ↓
2. For each matching repository:
   - Recursively discover affected accepted-reference component (same cascade logic)
   - Archive git repository to .archive/<npub>/<identifier>-<timestamp>.tar.gz
   - Mark metadata as "blacklist-triggered" (not NIP-09)
   - Move events to holding database
   - Delete from main database
   ↓
3. Background task (daily):
   - Check holding database for expired entries
   - Delete events older than retention period
   - Delete corresponding archive files

Key Differences from NIP-09:

• No author validation required (operator decision)
• Triggered on startup, not by event arrival
• Metadata marks deletion as blacklist-triggered
• deletion_request_disrespector does NOT prevent blacklist deletion (see below)

Current scope: startup reconciliation only.

Future: When dynamic blacklist updates are supported, deletion can trigger immediately on config change instead of waiting for restart.

Archival Mode (Disrespector)

When deletion_request_disrespector = true:

1. Kind 5 deletion request arrives
   ↓
2. Check idempotency:
   - if every actionable `e`/`a` target is already covered by an existing
     same-author kind-5 request, return a duplicate success response without
     storing the new deletion event
   ↓
3. Store deletion request event in main database
   ↓
4. Do NOT process deletion
   ↓
5. Repository and events remain fully accessible
   ↓
Result: Archival relay preserves all content

Important: Disrespector mode affects user-initiated NIP-09 deletions and NIP-62 vanish requests. It does NOT prevent blacklist-triggered deletions.

Rationale:

• NIP-09/NIP-62 deletions are user agency decisions (left-pad protection needed)
• Blacklist deletions are operator moderation decisions (spam/malware/abuse)
• Archival relays still need ability to moderate malicious content
• Different policy goals: preservation vs. safety

Implementation Note: Implemented. The LMDB backend's automatic NIP-09 and NIP-62 processing is disabled (process_nip09(false), process_nip62(false)); ngit-grasp owns deletion handling in relay policy code, which short-circuits already-covered NIP-09 deletions before the deletion_request_disrespector archival-mode branch. When deletion_request_disrespector is set, new kind-5 requests are stored but not acted on, and kind-62 requests are stored but not acted on. NIP-09 and NIP-62 are omitted from the NIP-11 supported_nips list in this mode.

Recovery Mechanism

The holding database enables accidental deletion recovery via two distinct triggers for the same owner+identifier scope.

Trigger A: Re-announcement recovery

Scenario: repository was deleted via announcement deletion, then announced again

1. Owner publishes new announcement with same identifier
   ↓
2. Before parking that announcement in purgatory, system checks holding/archive
   eligibility for same owner+identifier
   ↓
3. Check: Is entry within retention period?
   ↓
4. If YES:
   - Extract git data from archive tar.gz
   - Restore to <git_data_path>/<npub>/<identifier>.git
   - Move events from holding DB → main DB
   - Re-run acceptance policy (should now pass)
   - Delete archive records
   - Return: "Restored X events"
   ↓
5. If NO (expired):
   - Process as new repository
   - Return: "New repository created"

Trigger B: Promotion recovery (deleted active state)

When deletion removes the currently served state and announcement serving is parked in purgatory:

1. Wait for a new valid authorized state event that can be promoted.
2. Promotion out of purgatory runs recovery hook for same owner+identifier.
3. Restore archived events/git from holding/archive.
4. Resume normal serving with git/state alignment.

Rollback history source-of-truth

Rollback for deleted active replaceable/addressable repository events uses ngit-grasp's dedicated replaceable-history store (src/nostr/lifecycle/history.rs), not backend internal replaceable compaction behavior.

The relay archives superseded 30617/30618 versions on write and uses that history at deletion time to pick rollback candidates for active e-target deletions (announcement + state).

This architecture is covered by two integration-test layers:

• tests/replaceable_history.rs verifies the durable history substrate: superseded 30617/30618 payloads are captured, queryable by coordinate/cutoff, survive LMDB restart, and do not change normal serving semantics.
• tests/nip09_state_cascade.rs verifies deletion behavior that consumes that substrate: active 30618 e deletion restores the previous state event and realigns refs, active 30617 e deletion restores the previous announcement when history exists, coordinate deletion cutoff semantics do not incorrectly resurrect history, and no-active-state behavior follows the purgatory invariant below.

Active replaceable rollback and git ref restoration

When a kind-5 deletion targets the active repository state (30618) by e tag, ngit-grasp must either restore a valid active state or stop serving the affected repository announcement scope:

1. Before destructive work, deletion policy builds rollback plans only for e-targeted 30617/30618 events that are still the active version for their coordinate.
2. The deletion request is tombstoned, then the targeted active state is moved to holding and removed from the main DB.
3. For a deleted active 30618, rollback looks up the latest superseded history record for the same 30618:<pubkey>:<identifier> coordinate at or before the deleted state's created_at cutoff.
4. The candidate payload is loaded from replaceable history, parsed as repository state, and accepted only if its author is still authorized for the repository announcements that remain outside purgatory.
5. The candidate state event is saved back to the main DB, making it the served active nostr state again.
6. The identifier is then realigned: ngit-grasp reloads repository data, selects the newest authorized active state per announcement owner, finds a repository copy containing the referenced objects, and runs the normal state-processing path to update/delete branch and tag refs in the served bare repositories.

When a kind-5 deletion targets the active repository announcement (30617) by e tag, ngit-grasp similarly looks for the latest superseded announcement in replaceable history and restores it when present. This e-tag rollback path is not the same as announcement-coordinate cascade deletion:

• If a history candidate exists, the previous announcement is restored to the main DB.
• If no history candidate exists, no cascade graph is computed from the deleted announcement. The targeted announcement is moved to holding and removed from the main DB, and the live bare repository is removed when that owner+identifier announcement scope is no longer served.
• Dependent event graph cascade for announcement deletion currently belongs to announcement-coordinate deletion (a tag), targeted NIP-62 vanish over announcements, operator-driven blacklist/whitelist deletion paths, and the no-active-state transition caused by deleting the only valid active 30618 state.

If another authorized maintainer still has a valid active state for the identifier, the surviving state remains the active source for git ref alignment; the deleted maintainer's state rollback must not disturb that maintainer's served announcement/state.

If no valid active state remains for the affected announcement scope, the relay must not keep serving an announcement with empty/stale git refs. Instead it must:

1. remove the served announcement scope from the main DB;
2. archive/remove the live bare repository using the same holding/archive safety semantics as announcement deletion;
3. park the announcement scope in purgatory, so it is not served while git/state alignment is unresolved;
4. wait for a new valid authorized state event and matching git data; and
5. promote/recover the scope only through the normal purgatory promotion path, restoring any holding/archive data needed for the same owner+identifier.

Blacklist Recovery

When a repository is removed from the blacklist, startup behavior depends on NGIT_BLACKLIST_AUTO_RESTORE:

Disabled (default):

• No startup restore sweep
• Repository remains in holding/archive unless recovered by another trigger

Enabled:

• Startup scans holding metadata with holding-source=blacklist
• Deduplicates owner+identifier scopes within retention
• Restores scopes that no longer match current blacklist
• Skips scopes still blacklisted

This keeps recovery opt-in and operator-controlled while removing manual restore steps for common unblacklist workflows.

Manual Ejection from Holding Area

Operators need ability to force-delete items from holding area before retention period expires:

Use Cases:

1. Large repositories consuming excessive storage
2. Confirmed malware/abuse that shouldn't be recoverable
3. Legal/compliance requirements for immediate permanent deletion

Mechanism (implemented):

• Admin CLI command: ngit-grasp holding-eject --owner <npub|hex> --identifier <id>
• Immediately delete from holding DB and archive filesystem
• Emits command output with deletion counts
• Metric: ngit_manual_ejections_total

Current CLI limitations:

• Manual ejection is permanent (no undo)
• It intentionally has no confirmation prompt, reason field, or operator field in the current CLI; richer operator UX is planned separately.

Operator Curation Integration

Overview

Blacklist- and whitelist-triggered removals use the same infrastructure as NIP-09 deletion requests and NIP-62 vanish lifecycle removals:

• Same holding database for 90-day retention
• Same git archive mechanism
• Same cascade deletion logic
• Same recovery capabilities (if unblacklisted)

Key Differences from NIP-09

Aspect	NIP-09 Deletion	Blacklist Deletion
Trigger	Kind 5 event arrives	Startup scan of main DB
Author validation	Required (pubkey match)	Not applicable (operator decision)
Disrespector mode	Prevents deletion	Does NOT prevent deletion
Purpose	User agency	Moderation/safety
Recovery	Automatic (re-publish)	Startup auto-restore (optional)
Metadata	Links to Kind 5 event	Marks "blacklist-triggered"

Why Disrespector Doesn't Prevent Blacklist Deletion

Design Decision: The deletion_request_disrespector configuration ONLY affects NIP-09/NIP-62 user-initiated deletions. It does NOT prevent blacklist-triggered deletions.

Rationale:

1. Different Policy Goals:

   • NIP-09/NIP-62 = User agency (prevent left-pad)
   • Blacklist = Operator safety (prevent spam/malware/abuse)

2. Archival Relays Need Moderation:

   • Archive mode preserves valuable deleted content
   • But still must handle malicious content
   • Spam, malware, abuse require operator intervention

3. Separate Concerns:

   • Disrespector = "Don't honor user deletion requests"
   • Blacklist = "Don't accept these specific repos regardless of source"

Detection and Timing

Current Behavior (Startup Scan):

1. Relay starts up
2. Load blacklist configuration
3. Scan main database for matching repos
4. For each match: archive → holding DB → delete from main
5. Continue normal operation

In the same startup parity pass, repository whitelist mismatches are also reconciled (for announcements that list this relay service but no longer match repository_whitelist).

When NGIT_BLACKLIST_AUTO_RESTORE=true, startup also runs a blacklist restore pass between blacklist parity delete and whitelist parity delete.

Startup also runs a whitelist restore pass after whitelist parity delete. This restores holding scopes tagged holding-source=whitelist when they now match repository_whitelist (while still respecting blacklist precedence).

Future Enhancement (Dynamic Updates):

• Watch for configuration file changes
• Trigger deletion/restore immediately on blacklist addition/removal
• Requires careful design to avoid race conditions

Cascade Deletion Strategy

When a repository announcement is deleted through a cascade-capable path (NIP-09 a-coordinate deletion of a kind-30617 announcement, targeted NIP-62 vanish over the author's announcements, blacklist deletion, or whitelist reconciliation), ngit-grasp cascade-deletes the main-DB events that lose their accepted-reference path after that announcement is removed.

NIP-09 e-tag deletion has two important replaceable cases:

• Deleting the only valid active kind-30618 repository state can make the served announcement scope invalid. In that no-active-state case, ngit-grasp runs the announcement cascade, archives/removes live git data, and parks the scope in purgatory until a new valid state and git data arrive.
• Deleting a kind-30617 announcement by event id is narrower: it deletes the targeted announcement event and may restore a previous announcement from replaceable history, but it does not compute the generic announcement cascade when no history candidate exists.

Basic Rules

Cascade deletion is graph analysis over the same reference shapes used for event admission. It is not limited to a fixed list of repository event kinds.

1. Start at the deleted announcement. The seed is the deleted kind-30617 announcement event id plus its address coordinate.
2. Recursively load the affected main-DB graph. From each discovered event, load events it references and events that reference it.
3. Analyze the loaded graph after removing the announcement. Events that still have a surviving accepted-repository path are retained. Events that only depended on the deleted announcement are moved to holding and removed from the main database.
4. Do not promote unrelated graph regions into the cascade. Another accepted repository announcement can anchor events already found in the affected graph, but a reference to that announcement is a boundary, not permission to retain or delete that repository's entire descendant graph.

The reference forms are:

`a` / `A` — address references
`e` / `E` — event-id references
`q`       — event-id or address references

The graph is built from the main database only. Holding, history, archive, and internal metadata stores are not graph inputs.

Retention Rule

After graph loading, the deleted announcement is excluded and retention is computed as a fixed point:

1. Keep surviving independent anchors.
2. Keep events that reference kept events or kept addresses.
3. Keep events that are referenced by kept events.
4. Repeat until no additional events are kept.
5. Move every remaining non-special node in the component to holding and delete it from the main database.

Surviving anchors include remaining repository announcements, kind-10317 GRASP lists, and independently valid GRASP-06 /prs/ endpoint events. The deleted announcement itself is never a surviving anchor.

This means a deleted repository's issue, comment, or arbitrary related event can survive when it is still connected to another accepted repository/reference path. The same event is deleted when the removed announcement was its only acceptance path.

Boundaries and Special Cases

Repository state events (30618) are not handled by the generic graph. They are keyed by repository identifier, so ngit-grasp preserves the existing identifier semantics:

• state survives while any repository announcement for the identifier remains;
• state is moved to holding when the last announcement for that identifier is removed.

Deletion requests, vanish requests, holding metadata, and history metadata do not act as recursive graph frontiers. They are lifecycle/control records, not normal repository content anchors.

PR and PR-update events have an additional invariant: served PR data must not outlive the git data needed to broadcast it. Generic graph reachability may keep them only when they still reference a kept repository announcement, or when they are independently valid through the GRASP-06 /prs/ flow. Otherwise they are removed from the retained set and retention is recalculated.

GRASP-06 PRs are treated as their own anchored flow. They can survive repository announcement deletion when the /prs/ endpoint relationship still makes the PR data independently valid.

If recursive graph expansion fails or exceeds internal safety caps, ngit-grasp does not cascade-delete from a known-partial graph. It falls back to deleting the requested announcement coordinate and then applies the normal identifier-level state cleanup.

Multi-Maintainer Scenarios

Challenge

Multiple maintainers can have announcements for the same identifier:

• npub1alice.../my-repo
• npub1bob.../my-repo

Git data is synced between their repositories. When ONE maintainer deletes, what happens?

Solution: Graph Retention

When npub1alice deletes her announcement:

1. Archive HER git directory:
   .archive/npub1alice.../my-repo-<timestamp>.tar.gz

2. Recursively load the affected main-DB reference graph

3. Analyze the graph after removing alice's announcement:
   - WITHOUT alice's announcement
   - WITH bob's announcement still present
   
4. Retain events still anchored by bob's announcement:
   Event A kept because:
     - References bob's announcement ✓
   Event B kept because:
     - References Event A ✓
   Event C orphaned because:
     - Only referenced alice's announcement ✗

5. Delete orphaned events, keep retained events

6. Handle circular dependencies naturally:
   - Event X kept because references Event Y
   - Event Y kept because references Event X
   - Neither has external anchor → both deleted

Graph Algorithm Details

Recursive expansion:

1. Seed from the deleted announcement event id and address.
2. Follow outgoing accepted-reference tags (a, A, e, E, and q).
3. Query incoming references using the same tag forms.
4. Treat other repository announcements as boundaries for unrelated graph expansion.
5. Deduplicate by event id/address and continue until no new main-DB nodes are discovered.

Retention fixed point:

1. Start from surviving independent anchors.
2. Propagate retention in both directions across accepted-reference edges.
3. Apply PR/PR-update git-data vetoes.
4. Delete the loaded nodes that remain unretained.

Safety caps:

• Internal node, edge, and orphan-delete caps bound worst-case graph work.
• Cap/query failures fall back to coordinate-only announcement deletion plus state cleanup rather than broad deletion from a partial graph.
• These limits are code-level safeguards, not user/operator configuration.

Complexity:

• Deletion events are rare (not performance critical)
• The graph is computed on demand from indexed main-DB reference queries
• No full relay dump, pre-computation, or cache is required at current scale

Configuration

deletion_request_disrespector

Type: bool
Default: false (respects deletion requests)
CLI: --deletion-request-disrespector
Env: NGIT_DELETION_REQUEST_DISRESPECTOR

Description: When true, relay ignores NIP-09 deletion requests and NIP-62 vanish requests and acts as an archival server. Critical for preventing left-pad scenarios by ensuring at least some relays preserve deleted content.

IMPORTANT: This setting does NOT prevent blacklist-triggered deletions. Blacklist is for operator moderation (spam/malware/abuse), which archival relays still need.

Use Cases:

• Community archival relays
• Research/historical preservation
• Backup/mirror relays
• GRASP-05 archive mode deployments

holding_retention_secs

Type: u64 Default: 7776000 (90 days in seconds) CLI: --holding-retention-secs Env: NGIT_HOLDING_RETENTION_SECS

Description: How long to retain archived events and git data before permanent deletion. Provides recovery window for accidental deletions.

Recommended Values:

• Development/Testing: 5 seconds (fast test cycles)
• Staging: 300 seconds (5 minutes)
• Production: 7776000 seconds (90 days, default)
• Archival Relay: 31536000 seconds (1 year) or higher

Notes:

• Configurable in seconds for testing flexibility
• Background cleanup task runs on NGIT_HOLDING_CLEANUP_INTERVAL_SECS (default daily)
• Check occurs on startup to handle offline periods
• Testing Challenge: Daily cleanup doesn't work well with 3-5 second retention for tests - alternative timing strategy needed

NIP-11 Advertisement

Deletion support is conditionally advertised in NIP-11 relay information (implemented in src/http/nip11.rs):

• When deletion_request_disrespector = false: include 9 ("deletion") and 62 ("request to vanish") in the supported NIPs array
• When deletion_request_disrespector = true: do NOT include 9 or 62 (archival mode stores but does not honor deletion or vanish requests)

This allows clients to discover whether a relay respects deletion requests.

Security Considerations

Validation

1. Author Matching:
   • For e targets, deletion request author MUST match deleted event author
   • For a targets, only coordinates with matching author are acted on
   • This prevents malicious actors from deleting other people's repositories
   • Enforced before destructive deletion processing
2. Signature Verification: Handled by nostr-relay-builder (already implemented)
3. Timestamp Check: For addressable events, delete versions up to deletion created_at

Attack Vectors

DoS via Deletion Spam:

• Mitigation: ownership checks + normal admission validation
• Mitigation: idempotent delete paths for already-deleted targets

Archive Disk Exhaustion:

• Mitigation: Background cleanup enforces retention limits
• Mitigation: Compressed tar.gz archives
• Mitigation: Configurable retention period
• Mitigation: Manual ejection mechanism for emergency storage relief

Recovery Abuse:

• Mitigation: Recovery only within retention window
• Mitigation: Must be original owner (pubkey match)
• Mitigation: Normal announcement validation applies

Blacklist Bypass:

• Mitigation: Blacklist checked on startup (retroactive deletion)
• Mitigation: Blacklist checked during announcement validation (prevents new)
• Mitigation: Blacklist deletion not affected by disrespector mode
• Note: Manual ejection available for confirmed abuse

Monitoring & Metrics

Prometheus Metrics (Currently Exposed):

• ngit_blacklist_deletions_total{phase,result}
• ngit_blacklist_startup_restore_total{result,reason}
• ngit_holding_cleanup_runs_total
• ngit_holding_cleanup_deleted_total{type}
• ngit_holding_cleanup_last_run_deleted{type}
• ngit_recovery_total{result}
• ngit_manual_ejections_total
• ngit_manual_ejection_deleted_total{type}

Related Documentation

• NIP-09 Specification: /persistent/dcdev/clones/nips/09.md
• Architecture Overview: docs/explanation/architecture.md
• Configuration Reference: docs/reference/configuration.md
• Roadmap: README.md

Future Enhancements

Remaining enhancements (updated after subsequent deletion/archival and GRASP-05 work):

Archive-mode policy extensions

• Selective disrespect: policy-based disrespect for specific criteria (e.g. popularity, community contribution, identifier allowlist).

Blacklist lifecycle improvements

• Dynamic blacklist updates: apply blacklist additions/removals without restart.
• Dedicated restore CLI: explicit operator restore commands with clear scope selection and outcomes.

Operator controls and UX

• Holding-area management UI: optional web/admin UX for archive and holding lifecycle operations.

Repository maintenance cleanup replacement

• Replace the narrow legacy cleanup command with ngit-grasp maintenance cleanup as a deliberate full-state integrity sweep rather than a deletion-cascade helper.
• Functional intent: inspect the full relay/git data set, mark events rooted in accepted repository announcements, recursively retain valid dependent events, and independently retain GRASP-06 PR/PR-update events only when their backing git data is present and consistent.
• Sweep unmarked repository-related events, then reconcile repository git dirs, state events, PR git data, and PR/PR-update events so served nostr state and filesystem git data match.
• Keep the command dry-run by default, require explicit --execute for mutation, and report candidate deletions, degraded states, orphan git dirs, and PR/git mismatches before destructive cleanup.

Delayed archival strategy (active repositories)

• Add optional grace/delay workflow for high-activity repositories before archival execution.
• Support cancellation windows, notification issue creation, and schedulable delayed archival operations.
• Expose policy knobs (notification delay, archive delay, activity/creator thresholds).

Monitoring and integration follow-up

• Expand deletion/archival/recovery metrics and provide dashboard + alerting guidance.

Conclusion

The deletion request system balances three competing needs:

1. User Agency: Owners can delete their repositories
2. Community Protection: Archival relays prevent left-pad scenarios
3. Recovery Grace Period: Holding database prevents accidental permanent deletion

By making deletion behavior configurable rather than mandatory, we enable a heterogeneous relay network where some relays respect deletions (user privacy) while others preserve content (community resilience).