From d1c9583266b869bcf82dd33521fb5d2d48efbcb2 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Wed, 24 Jun 2026 12:42:40 +0100 Subject: [PATCH] docs: rename deletion docs to repository lifecycle --- .env.example | 2 +- README.md | 4 +-- docs/explanation/README.md | 9 ++--- docs/explanation/architecture.md | 2 +- ...on-requests.md => repository-lifecycle.md} | 34 ++++++++++--------- docs/reference/configuration.md | 4 +-- nix/module.nix | 2 +- 7 files changed, 30 insertions(+), 27 deletions(-) rename docs/explanation/{deletion-requests.md => repository-lifecycle.md} (97%) diff --git a/.env.example b/.env.example index b3ee8bb..fa892f6 100644 --- a/.env.example +++ b/.env.example @@ -274,7 +274,7 @@ # deleted and re-submission stays rejected. NIP-09 and NIP-62 are advertised in # NIP-11. # -# See: docs/explanation/deletion-requests.md +# See: docs/explanation/repository-lifecycle.md # # CLI: --deletion-request-disrespector # Default: false diff --git a/README.md b/README.md index c90cb8b..e2cf3fb 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ blacklist, repository whitelist, and service de-listing), while `NGIT_DELETION_REQUEST_DISRESPECTOR=true` stores but does not act on user deletion/vanish requests for archival relays. -See [Deletion Request Support](docs/explanation/deletion-requests.md) for details. +See [Repository Lifecycle](docs/explanation/repository-lifecycle.md) for details. ### Sophisticated Sync System (GRASP-02) @@ -369,7 +369,7 @@ and whitelist reconciliation, archival disrespector mode, and service de-listing removal are implemented. Remaining work is operator-facing UX: richer holding management, explicit restore commands, and optional delayed archival policies. -See [Deletion Request Support](docs/explanation/deletion-requests.md). +See [Repository Lifecycle](docs/explanation/repository-lifecycle.md). ### Mitigate DoS attack vector diff --git a/docs/explanation/README.md b/docs/explanation/README.md index 58cc46f..df1348a 100644 --- a/docs/explanation/README.md +++ b/docs/explanation/README.md @@ -180,16 +180,17 @@ Explanation documentation helps you **understand concepts** and design decisions --- -### [Deletion Requests](deletion-requests.md) -**Handling repository and event deletion** +### [Repository Lifecycle](repository-lifecycle.md) +**Handling repository removal, holding, archive, recovery, and purgatory** **Topics:** -- Deletion request architecture +- Repository lifecycle architecture - Delete disrespector concept - Preventing left-pad scenarios - Archival policies +- Holding, recovery, purgatory, and operator curation flows -**Read when:** You want to understand how ngit-grasp handles deletion events (planned feature) +**Read when:** You want to understand how ngit-grasp keeps nostr state and git data aligned across deletion, vanish, moderation, recovery, and purgatory flows --- diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md index 202479b..47e3361 100644 --- a/docs/explanation/architecture.md +++ b/docs/explanation/architecture.md @@ -213,7 +213,7 @@ Operators can opt into archival behaviour with `NGIT_DELETION_REQUEST_DISRESPECTOR`, which stores but does not act on user deletion/vanish requests. -Full details: [Deletion Request Support](deletion-requests.md). +Full details: [Repository Lifecycle](repository-lifecycle.md). #### [`events.rs`](src/nostr/events.rs) - Event Parsing diff --git a/docs/explanation/deletion-requests.md b/docs/explanation/repository-lifecycle.md similarity index 97% rename from docs/explanation/deletion-requests.md rename to docs/explanation/repository-lifecycle.md index d70029a..af4ae49 100644 --- a/docs/explanation/deletion-requests.md +++ b/docs/explanation/repository-lifecycle.md @@ -1,11 +1,12 @@ -# Deletion Request Support (NIP-09 and NIP-62) +# Repository Lifecycle (Deletion, Holding, Archive, and Recovery) ## Overview -ngit-grasp implements optional support for NIP-09 deletion requests and NIP-62 -request-to-vanish events, allowing repository owners to remove their data from -the relay while giving operators configurable archival behavior for left-pad -resilience. +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 @@ -14,16 +15,16 @@ and recovery: > **Served nostr state must always match git refs we can actually serve.** -This invariant is the design center for deletion handling and a key rationale -for purgatory. If the currently served repository state is deleted and no valid +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 deletion behavior +## Ownership of lifecycle behavior -ngit-grasp disables backend auto-processing and owns NIP-09/NIP-62 handling in -relay policy code: +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`) @@ -32,7 +33,7 @@ relay policy code: - holding DB uses `process_nip09(false)` and `process_nip62(false)` (`src/nostr/lifecycle/holding.rs`) -This keeps deletion behavior auditable and prevents the storage backends from +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 @@ -54,7 +55,8 @@ The "left-pad problem" refers to a 2016 incident where a critical npm package wa ### Three-Database Design -The deletion system uses three relay databases plus archive filesystem storage: +The repository lifecycle system uses three relay databases plus archive +filesystem storage: ``` ┌─────────────────────────────────────────────────────────┐ @@ -176,7 +178,7 @@ deprecated in favor of the maintenance command. and still within holding retention - Still-blacklisted scopes are skipped -## Deletion Flow +## Lifecycle Removal Flows ### Standard Mode (Respects Deletions) @@ -491,12 +493,12 @@ Operators need ability to **force-delete** items from holding area before retent - It intentionally has no confirmation prompt, reason field, or operator field in the current CLI; richer operator UX is planned separately. -## Blacklist Deletion Integration +## Operator Curation Integration ### Overview -Blacklist-triggered deletions use the **same infrastructure** as NIP-09 deletion -requests and NIP-62 vanish lifecycle removals: +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 diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index a664335..d544a0c 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1176,8 +1176,8 @@ NGIT_DELETION_REQUEST_DISRESPECTOR=true NGIT_DELETION_REQUEST_DISRESPECTOR=false ``` -See [`docs/explanation/deletion-requests.md`](../explanation/deletion-requests.md) -for the full design rationale. +See [`docs/explanation/repository-lifecycle.md`](../explanation/repository-lifecycle.md) +for the full lifecycle design rationale. --- diff --git a/nix/module.nix b/nix/module.nix index 4b2d036..4ce19a6 100644 --- a/nix/module.nix +++ b/nix/module.nix @@ -289,7 +289,7 @@ let When disabled (default), deletion requests are honoured and NIP-09 and NIP-62 are advertised in NIP-11. - See: docs/explanation/deletion-requests.md + See: docs/explanation/repository-lifecycle.md ''; };