From b46caa59eabd3611deb8f99c0a04d0c7a7a9bb99 Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Mon, 20 Oct 2025 10:27:41 -0400
Subject: [PATCH] Document moderation runtime flow and fixtures

---
 docs/moderation/README.md  | 9 +++++++++
 docs/moderation/testing.md | 8 ++++++++
 2 files changed, 17 insertions(+)

diff --git a/docs/moderation/README.md b/docs/moderation/README.md
index 7b6dfc19..63346289 100644
--- a/docs/moderation/README.md
+++ b/docs/moderation/README.md
@@ -18,6 +18,15 @@ bitvid is follow-centric. Your Home feed comes from people you follow (F1). Disc
 - **Replies/threads**: NIP-10 (comments).
 - **Counts**: NIP-45 (relay COUNT; optional fallbacks).
 
+## Runtime flow (blur, hide, override)
+- [`ModerationService`](../../js/services/moderationService.js) orchestrates ingest and scoring. Review the service for the trusted-report math and helper entry points.
+- [`createModerationStage`](../../js/feedEngine/stages.js) wires the service into the feed engine where moderation summaries decorate timeline items.
+- [`bitvidApp.decorateVideoModeration`](../../js/app.js) connects stage output to the UI layer alongside feature-flag plumbing.
+- [`VideoCard.refreshModerationUi`](../../js/ui/components/VideoCard.js) applies badges, blur states, and "show anyway" toggles.
+
+## Where to extend
+Thread new moderation behaviors through the same service → stage → app → UI flow above. Extending the existing layers keeps overrides, feature flags, and QA hooks consistent—avoid spinning up parallel moderation modules unless the architecture document explicitly calls for it.
+
 ## Defaults (policy)
 - Blur video thumbnails if **≥ 3** F1 friends report `nudity`.
 - Disable autoplay preview if **≥ 2** F1 friends report `nudity`.
diff --git a/docs/moderation/testing.md b/docs/moderation/testing.md
index baca76e6..73951ab1 100644
--- a/docs/moderation/testing.md
+++ b/docs/moderation/testing.md
@@ -40,6 +40,8 @@ Expected:
 * After 2 reports → autoplay blocked.
 * After 3 reports → thumbnail blurred; reason chip shown.
 
+**Exercises:** [`ModerationService.ingestReportEvent()`](../../js/services/moderationService.js) and [`ModerationService.getTrustedReportSummary()`](../../js/services/moderationService.js) wire through [`createModerationStage()`](../../js/feedEngine/stages.js) so [`bitvidApp.decorateVideoModeration()`](../../js/app.js) can hand the summary to [`VideoCard.refreshModerationUi()`](../../js/ui/components/VideoCard.js).
+
 ### B) Mute list (10000)
 
 ```json
@@ -53,6 +55,8 @@ Expected:
 
 Expected: author’s items are downranked/hidden for this viewer.
 
+**Exercises:** [`ModerationService.ingestTrustedMuteEvent()`](../../js/services/moderationService.js) updates [`ModerationService.isAuthorMutedByTrusted()`](../../js/services/moderationService.js) / [`getTrustedMutersForAuthor()`](../../js/services/moderationService.js), which [`createModerationStage()`](../../js/feedEngine/stages.js) propagates to the video item before [`VideoCard.refreshModerationUi()`](../../js/ui/components/VideoCard.js) renders the mute state.
+
 ### C) Admin blacklist (30000)
 
 ```json
@@ -67,11 +71,15 @@ Expected: author’s items are downranked/hidden for this viewer.
 
 Expected: when viewer subscribes to this list, author is hard-hidden.
 
+**Exercises:** [`accessControl`](../../js/accessControl.js) hydration feeds [`ModerationService.getAdminListSnapshot()`](../../js/services/moderationService.js) / [`getAccessControlStatus()`](../../js/services/moderationService.js), giving [`createModerationStage()`](../../js/feedEngine/stages.js) the whitelist/blacklist flags that [`bitvidApp.decorateVideoModeration()`](../../js/app.js) and [`VideoCard.refreshModerationUi()`](../../js/ui/components/VideoCard.js) respect.
+
 ### D) COUNT fallback
 
 * Use a relay that doesn’t support COUNT.
 * Verify “—” placeholders; no spinner loops; no crashes.
 
+**Exercises:** Missing COUNT data flows through [`ModerationService.setActiveEventIds()`](../../js/services/moderationService.js) → [`ModerationService.getTrustedReportSummary()`](../../js/services/moderationService.js) defaults, letting [`createModerationStage()`](../../js/feedEngine/stages.js) emit neutral moderation metadata that [`VideoCard.refreshModerationUi()`](../../js/ui/components/VideoCard.js) renders as placeholders.
+
 ## Automated checks (suggested)
 
 * `npm run test:unit` — covers `tests/moderation/trusted-report-count.test.mjs` for deduping and mute handling.