--- title: WoT fetch via outbox model + PR #3483 review fixes type: fix status: completed date: 2026-07-06 origin: PR https://github.com/vitorpamplona/amethyst/pull/3483 review comments (Vitor Pamplona, davotoula) --- # WoT fetch via outbox model + PR #3483 review fixes ## Overview PR #3483 (branch `feat/wot-shared-index-relays`) adds Web-of-Trust badges + shared Index Relays + `amy wot` verbs. Two reviewers flagged issues: - **Vitor** (owner): stop broadcasting kind-0/kind-3 REQs to a static index-relay list. Use the outbox model: index relays discover each author's kind-10002, then kind-0/kind-3 REQs go to each author's declared write relays. - **davotoula**: six correctness / perf / lifecycle bugs across `DesktopLocalCache`, `WoTService`, and `FeedMetadataCoordinator` — some Desktop-scoped, most in `commons/commonMain` so Android inherits them the moment WoT gets wired there. This plan lands **both** in a single PR revision: - The outbox-model refactor for kind-0 / kind-3 fetching (Vitor's ask). - All six correctness/perf/lifecycle fixes (davotoula's ask). - A sweep confirming no production default references the dying `relay.damus.io`. The scope is intentionally larger than a normal review-fix cycle because the outbox refactor changes the same seams the bug-fixes touch — separating them would produce a churny diff. ## Problem Statement ### 1. Index-relay broadcast is architecturally wrong for kind-0 / kind-3 Current flow (this branch): ``` Login (~350 follows) ─▶ Main.kt:1315 └── FeedMetadataCoordinator.loadKind3Batched(follows) └── REQ kinds=[3] authors=[follows chunked/100] to *every* index relay in PreferencesIndexRelays.effective() ``` Semantics: - Every kind-3 event is fetched from index relays whether or not the author publishes there. - Users who *only* publish to their own outbox (increasingly common on modern Nostr) return no kind-3 — WoT signal is wrong (undercount). - Index-relay operators absorb the entire follow set's worth of REQ authors, even when other relays hold the data. - The same anti-pattern exists for kind-0 profile metadata (via `loadMetadataBatched`) and inside `amy wot sync` (which reimplements the same broadcast in `WotCommand.sync`). Vitor's directive (quoting review): > Kind 0 and 3 must be downloaded from the outbox relay (10002, write) of each > user. Basically, find all 10002 events via index relays (purple pages, etc), > then parse them all to find a list of relays per author, invert the map to > get a list of authors per relay, then use that list to download posts, kind > 0 and contact lists from each author. ### 2. Six correctness / perf / lifecycle bugs | # | File:line | Symptom | Severity | |---|-----------|---------|----------| | 1 | `DesktopLocalCache.kt:509-530` | `accountPubkey` race → self kind-3 stamped `lastContactListByAuthor` before self-check; later relay retry rejected by `createdAt <= prev`; empty follow view; `FollowAction.follow` calls `createFromScratch(...)` and **wipes real follow list** | **P0 (data loss)** | | 2 | `commons/wot/WoTService.kt:162-190` | `handleFollowSet` sets `myFollows` before the `MAX_FOLLOWS` guard, guard doesn't return `myFollows` to empty, and `Main.kt:1561` still calls `loadKind3Batched` when over the cap — CPU/memory blow-up the PR description promised was skipped | P1 (perf regression on mega-follow accounts) | | 3 | `commons/wot/WoTService.kt` | No `close()/dispose()` → writer coroutine + `Channel` leak on account switch; leaks compound over long sessions | P1 (leak) | | 4 | `commons/wot/WoTService.kt:37-49, 149-160` | Doc claims "per-key subscriber isolation via `Snapshot.withMutableSnapshot`" — that's a mis-attribution. Per-key isolation is a `SnapshotStateMap` property, not a `withMutableSnapshot` property; the `withMutableSnapshot` on *every* op just batches writes. Any consumer that reads the map iteratively (size, keys) *will* invalidate on every mutation, which the comment claims won't happen. Future Android integrator will trust the comment. | P2 (misleading docs → landmine) | | 5 | `commons/relayClient/assemblers/FeedMetadataCoordinator.kt:320-368` | `queuedKind3Pubkeys` marks pubkeys sent, never reset on failure. If every index relay times out (mobile flake / cold-start), WoT stays empty for the entire session; `loadKind3Batched` will short-circuit thereafter. | P1 (silent WoT-empty session) | | 6 | `commons/relayClient/assemblers/FeedMetadataCoordinator.kt:274, 338` | `eoseReceived: MutableSet` written from per-relay `Dispatchers.IO` `onEose` callbacks with no sync → race can drop an EOSE, blocking on the full 5 s timeout instead of firing early. Low ceiling but pre-existing pattern that this PR duplicates. | P2 (perf / responsiveness) | Additional owner-flagged item: - `relay.damus.io` shutting down end of month. Confirmed: no production default on this branch references it. Only commonTest fixtures do — leave those alone (they're wire-format fixtures, not runtime relay lists). ## Proposed Solution ### Outbox refactor: two-phase discovery Replace the single "broadcast a kind-3 REQ to all index relays" flow with a two-phase pipeline that reuses existing Quartz infrastructure. The pipeline lives in `commons/commonMain` so **Desktop, Android (future), and `amy`** all share it. ``` ┌────────────────────────────────────────────────────┐ │ Phase 1 — kind-10002 discovery (index-relay REQ) │ │ inputs: pubkeys[], indexRelays[] │ │ emits: Map> │ │ (author → declared write relays) │ │ │ │ • REQ kinds=[10002] authors=chunked-by-100 │ │ to every index relay. │ │ • Feed matching AdvertisedRelayListEvent into │ │ LocalCache (so future lookups skip the REQ). │ │ • Per-relay timeout (default 4s), NOT one global.│ └────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────┐ │ Phase 2a — RelayListRecommendationProcessor │ │ inputs: authorMap from Phase 1 │ │ emits: Set │ │ (relay → author set, minimal cover) │ │ │ │ Reuses Quartz's existing algorithm which: │ │ • builds relay → author set (transpose) │ │ • greedily picks most-popular relay, removes │ │ covered authors, repeats │ │ • second pass to ensure ≥2-relay coverage per │ │ author │ │ • filters onion/localhost per config │ └────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────┐ │ Phase 2b — per-relay kind 0 + kind 3 REQ │ │ For each RelayRecommendation: │ │ REQ kinds=[0,3] authors=[recommendation.users] │ │ with per-relay timeout, single subscription. │ │ Events flow into LocalCache via existing │ │ consume path. │ └────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────┐ │ Phase 3 — Fallback for authors without 10002 │ │ Authors in the input set that never returned a │ │ 10002 fall back to the current index-relay flow │ │ (REQ kinds=[0,3] authors=[fallbackSet] on index │ │ relays). Bounded; only fires when non-empty. │ └────────────────────────────────────────────────────┘ │ ▼ onEose() → WoTService.markReadyOnce() ``` Global 2 s startup fallback in `Main.kt` stays as the outermost safety net. ### Bug fixes (correctness first, always) **Fix 1 — `DesktopLocalCache` accountPubkey race.** Make `accountPubkey` either a constructor parameter or a required init that must resolve *before* hydration starts. Reorder `Main.kt` so `localCache.accountPubkey = account.pubKeyHex` runs before `localRelayStore.hydrate(localCache)`. Belt + braces: inside `consumeContactList`, do not stamp `lastContactListByAuthor` for events where `event.pubKey == accountPubkey` unless the self path actually accepted the event. This eliminates the "poisoned stamp" for the future relay retry even if a caller ever forgets to bind pubkey first. **Fix 2 — MAX_FOLLOWS guard bypass.** Two-part fix: - In `WoTService.handleFollowSet`, when the follow set exceeds `MAX_FOLLOWS`, set `myFollows = emptySet()` *and* flip a `disabled: Boolean` flag. Both `handleKind3` and every future op must early-return on `disabled`. - In the outbox driver's entrypoint (formerly `Main.kt:1561`), consult `WoTService.isDisabled` (new StateFlow) or `follows.size <= WoTService.MAX_FOLLOWS` before dispatching Phase 1. When over the cap: skip Phase 1 + 2 entirely and call `markReadyOnce()` immediately. **Fix 3 — `WoTService.close()`.** Add: ```kotlin private val supervisor = SupervisorJob(scope.coroutineContext[Job]) private val serviceScope = CoroutineScope(scope.coroutineContext + supervisor + writerDispatcher) fun close() { ops.close() supervisor.cancel() } ``` Call from account-switch (Main.kt clear path) and from `DesktopIAccount` disposal. Add an internal `AutoCloseable` implement so callers can lean on `use { }`. **Fix 4 — Correct the misleading comments.** Rewrite `WoTService` KDoc to say: > Scores are exposed via a Compose-observable `SnapshotStateMap`. Consumers > that read a *specific key* (`scores[pubkey]`) recompose only when that key > changes — this is `SnapshotStateMap`'s per-key observation. Consumers that > iterate the map or read its size will recompose on any mutation. > > Ops are serialized through a single-writer `Channel`. Coalescing writes > inside `Snapshot.withMutableSnapshot { }` batches state commits so a > multi-key op emits a single Compose invalidation instead of one per key. No behaviour change; the comment is the fix. **Fix 5 — `queuedKind3Pubkeys` retryable.** Convert the current mark-on-send set into mark-on-EOSE: - Track `inFlight: MutableSet` for de-duplication during a single call. - On successful EOSE (or per-relay EOSE), move pubkeys into `succeeded` (unchanged behaviour: skip future REQs). - On global timeout with zero events for a pubkey, **do not** promote to `succeeded`; keep them retryable on the next `loadKind3Batched` / `loadKind3ViaOutbox` call. - Cheap: same `Set` mechanics, just gated by outcome instead of intent. **Fix 6 — Synchronise `eoseReceived`.** Two options; pick (b): - (a) Wrap in `Mutex` / `synchronized` — `synchronized` needs a JVM-only path or an `expect/actual`. - (b) **Use a single-writer coroutine**: replace the `MutableSet` + `CompletableDeferred` handshake with a `Channel( capacity = Channel.UNLIMITED)` + a launched consumer that increments a local counter and completes the deferred when it hits `indexRelays.size`. Same shape, zero shared mutable state across dispatchers. KMP-clean. Apply the same fix to both `loadKind3Batched` and `loadMetadataBatched` because the pattern is duplicated. ### Damus sweep Grep of the current branch found `relay.damus.io` only in test fixtures (`FeedDefinitionSerializerTest`, `TorRelayEvaluationTest`, `RichTextParserTest`, `ZapSplitResolverTest`). None are production defaults. `DEFAULT_INDEX_RELAYS` = `{nos.lol, nostr.wine, noswhere, primal.net}`; `AmethystDefaults.DefaultIndexerRelayList` = `{purplepages, coracle, userkinds, yabu, nostr1}`. Leave the test fixtures alone (they exercise URL parsing on canonical example URLs — replacing them adds churn without protecting users). Include a one-line status note in the PR description so Vitor sees "checked". ## Technical Approach ### Architecture — where each piece lives Following the codebase-specific rule (`commons/ARCHITECTURE.md`): "protocol in Quartz, business logic in commons, layouts in platform apps." ``` quartz/ (unchanged — reuse only) nip65RelayList/AdvertisedRelayListEvent.kt — parser (existing) nip65RelayList/RelayListRecommendationProcessor — transpose + cover (existing) commons/commonMain/ wot/WoTService.kt — bug fixes 2/3/4 wot/OutboxDispatcher.kt — NEW (Phase 1-3 driver) wot/OutboxRelayLoader.kt — MOVED from amethyst/, Flow> relayClient/assemblers/FeedMetadataCoordinator.kt — bug fixes 5/6 + calls into OutboxDispatcher when configured desktopApp/jvmMain/ Main.kt — reorder localCache init, call OutboxDispatcher cache/DesktopLocalCache.kt — bug fix 1 — new consumeAdvertisedRelayList path cli/ commands/WotCommand.kt — amy wot sync via OutboxDispatcher ``` ### OutboxDispatcher API (draft) ```kotlin // commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/wot/OutboxDispatcher.kt class OutboxDispatcher( private val client: INostrClient, private val scope: CoroutineScope, private val indexRelays: () -> Set, // lazy — respects settings updates private val cache: OutboxCacheGateway, // interface, actual = DesktopLocalCache private val perRelayTimeoutMs: Long = 4_000, ) { data class Result( val kind10002Received: Int, val kind3Received: Int, val kind0Received: Int, val fallbackAuthors: Int, ) /** * Fetch kind-3 and kind-0 for [authors] via each author's declared write * relays (NIP-65). Falls back to [indexRelays] for authors with no 10002. * * Suspending — returns after every phase EOSEs or times out. Callers * that need "return immediately, mark ready later" should wrap in * [scope.launch]. */ suspend fun fetchKind0And3(authors: Set): Result suspend fun fetchKind3Only(authors: Set): Result // WoT-specific } interface OutboxCacheGateway { /** Returns the cached kind-10002 for [pubkey] if the local store already has one. */ fun cachedOutbox(pubkey: HexKey): AdvertisedRelayListEvent? /** Called for every 10002 that comes back — cache should stash it. */ fun onOutboxDiscovered(event: AdvertisedRelayListEvent, relay: NormalizedRelayUrl) /** Called for every kind-3 / kind-0 that comes back — cache should route through its consume path. */ fun onDiscoveredEvent(event: Event, relay: NormalizedRelayUrl) } ``` `DesktopLocalCache` implements `OutboxCacheGateway`; `amy` gets a minimal implementation that writes into its local store. `OutboxRelayLoader` (moved from `amethyst/`) provides the *live* Flow-form for reactive lookups; `OutboxDispatcher` uses it internally for the "check cache first, only REQ what's missing" fast-path. ### Reactivity for "new follow arriving" Current code (Main.kt:1559) collects `localCache.followedUsers` and calls `loadKind3Batched(follows)` on every change. The dedup set means the diff (only new pubkeys) actually flows through. Under the outbox model, the analogous flow is: ``` localCache.followedUsers.collect { follows -> wotService.onFollowSetChange(follows, account.pubKeyHex) if (wotService.isDisabled) { wotService.markReadyOnce(); return@collect } launch { val result = outboxDispatcher.fetchKind3Only(follows) // dedup inside wotService.markReadyOnce() } } ``` `fetchKind3Only` internally consults `inFlight` + `succeeded` and only REQs the diff. Test scenario "user follows one new person mid-session" trivially covered because Phase 1 for a single-element authors set is a single index- relay REQ, and Phase 2 is one per-outbox REQ. ### `amy wot sync` under outbox Replace the manual `Filter/chunked/ctx.drain(...)` block in `WotCommand.sync` with: ```kotlin val dispatcher = OutboxDispatcher(client, scope, ctx::indexRelays, AmyCacheGateway(store)) val result = dispatcher.fetchKind3Only(follows.toSet()) Output.emit("wot sync", "10002=${result.kind10002Received} kind3=${result.kind3Received} " + "fallback=${result.fallbackAuthors}") ``` The JSON schema for `--json` gains three new keys (`kind10002_received`, `fallback_authors`, `kind3_received`) — additive, no rename. ### Concurrency & KMP concerns - All new code targets `commonMain`. No `java.util.concurrent`, no `synchronized {}` (needs jvmAndroid actual). Rely on `Channel`, `Mutex`, `StateFlow`, and `Snapshot` — all KMP-safe. - `Dispatchers.IO` isn't KMP either; use `Dispatchers.Default` in commonMain and let platform code override if needed. - Per-relay timeouts implemented via `withTimeoutOrNull(perRelayTimeoutMs)` inside per-relay coroutines; overall EOSE gate uses a `CompletableDeferred` that trips when either (a) all per-relay jobs complete or (b) the outer `withTimeoutOrNull(overallCap)` fires. ### Data flow: how discovered 10002s stop double-fetching Every `AdvertisedRelayListEvent` received during Phase 1 goes through `OutboxCacheGateway.onOutboxDiscovered(event, relay)` → the platform cache's `consume` path. Next call for the same author checks `cachedOutbox(pubkey)` before dispatching Phase 1, so we never REQ the same 10002 twice within a session (or across sessions, if the local relay store persists the 10002 — which it does, since kind-10002 events are indexed like any other event). ### Implementation Phases #### Phase 1 — Bug fixes (correctness first, self-contained) Ship-blockers, no outbox dependency, land these commits first so a revert doesn't force rolling back the outbox refactor: 1. `fix(desktop-cache): eliminate accountPubkey race in consumeContactList` — reorder Main.kt so pubkey binds before hydrate; gate `lastContactListByAuthor` stamp inside self branch. Test: `DesktopLocalCacheHydrationTest` — reproduce the wipe by running hydration before pubkey bind, assert follow set survives relay retry. 2. `fix(wot): clear myFollows + set disabled flag when MAX_FOLLOWS exceeded` — plus a Main.kt short-circuit before dispatching Phase 1. Test: `WoTServiceTest.overCapDisablesEverything`. 3. `refactor(wot): close()/dispose() + AutoCloseable, call from account-switch` — Test: `WoTServiceLifecycleTest.closeCancelsWriter`. 4. `docs(wot): correct SnapshotStateMap isolation comments` — comment-only. 5. `fix(coordinator): mark queuedKind3Pubkeys only on EOSE, allow retry on timeout` — Test: `FeedMetadataCoordinatorTest.timeoutRetryIsAllowed`. 6. `fix(coordinator): single-writer EOSE aggregator (KMP-safe)` — Test: `FeedMetadataCoordinatorTest.eoseReadyUnderConcurrentCallbacks` using a fake client that fires EOSE from multiple dispatchers. **Success criteria phase 1:** all six tests pass; `./gradlew :commons:jvmTest :desktopApp:jvmTest :cli:test` green; `./gradlew spotlessApply` clean. #### Phase 2 — Outbox scaffolding (commons) 7. `refactor(commons): move OutboxRelayLoader from amethyst/ to commons/commonMain` — pure code motion; leave a re-export in the amethyst package to avoid Android build breaks. Test: existing Android `OutboxRelayLoaderTest` (if any) still passes. 8. `feat(commons): OutboxDispatcher two-phase kind-0/kind-3 fetcher` — commonMain, plus jvmMain test that drives a fake `INostrClient` through Phase 1/2/3 including the fallback path. 9. `feat(commons): OutboxCacheGateway interface + DesktopLocalCache impl` — including a new `consumeAdvertisedRelayList(event, relay)` in `DesktopLocalCache` that mirrors the existing `consumeContactList` pattern. **Success criteria phase 2:** `./gradlew :commons:jvmTest` green; `OutboxDispatcherTest` covers "author with 10002", "author without 10002 → fallback", "index relay times out on Phase 1", and "per-relay timeout on Phase 2 doesn't cancel other relays". #### Phase 3 — Cutover (Main.kt + amy) 10. `feat(desktop): route WoT kind-3 fetch through OutboxDispatcher` — Main.kt uses OutboxDispatcher; delete the direct `loadKind3Batched` call. Preserve the 2 s startup fallback for `markReadyOnce`. 11. `feat(desktop): also route stranger-avatar kind-0 through OutboxDispatcher` — MetadataPreloader gets a hook that prefers outbox when a 10002 exists for the author. 12. `feat(cli): amy wot sync via OutboxDispatcher` — rewrite the manual filter/drain in `WotCommand.sync`. Update its `--json` schema (additive). **Success criteria phase 3:** manual testing sheet (Section: Test Plan) passes end-to-end. `./gradlew test` green. #### Phase 4 — Documentation & PR description 13. Update PR description's "Behaviour" section to reflect the outbox flow. 14. Add a top-level "Damus relay: production defaults verified clean" line so Vitor doesn't have to look. ## Alternative Approaches Considered **A. Do the outbox refactor in a follow-up PR.** Rejected by user: the same files (WoTService, FeedMetadataCoordinator, Main.kt) also need the review fixes, so a two-PR split would double the churn in the same seams. **B. Skip Phase 1 (10002 discovery) and read the local cache only.** Would break for cold-start accounts with no cached 10002s. Only works for "warm-cache" sessions, defeating Vitor's ask on first login. **C. Adopt `AmethystDefaults.DefaultIndexerRelayList` as the new index-relay default.** The current branch keeps `{nos.lol, nostr.wine, noswhere, primal.net}` for continuity. Adopting the Purple Pages / Coracle / etc. set is a user-visible behaviour change deserving its own review. Deferred to a follow-up ticket. Documented in `PreferencesIndexRelays.kt:85-92` already; no action here. **D. Use `graperank` as Vitor idly mused in the follow-up comment.** Not actionable in this PR — it's a musing about extending `amy`, not a review change. Called out here so the item doesn't get lost, but leave for a future ticket. ## System-Wide Impact ### Interaction Graph ``` Login └─ Main.kt:1541 LaunchedEffect binds localCache.accountPubkey └─ (Fix 1: must run BEFORE the block below) └─ Main.kt:893 launch(Dispatchers.IO) { localRelayStore.hydrate(localCache) } └─ per-event: localCache.justConsumeMyOwnEvent → consumeContactList └─ before fix: stamps lastContactListByAuthor with null accountPubkey └─ after fix: stamp only inside self-branch, or after ordering guarantee Login (parallel) └─ Main.kt:1559 collect(followedUsers) → └─ WoTService.onFollowSetChange └─ ops.trySend(FollowSet) → writerLoop → handleFollowSet └─ Fix 2: MAX_FOLLOWS → clear myFollows + disabled=true, return └─ if !disabled: OutboxDispatcher.fetchKind3Only(follows) └─ Phase 1: REQ 10002 on index relays └─ OutboxCacheGateway.onOutboxDiscovered → DesktopLocalCache.consumeAdvertisedRelayList └─ Phase 2a: RelayListRecommendationProcessor.reliableRelaySetFor └─ Phase 2b: per-relay REQ kind=[0,3] authors=[relay's users] └─ OutboxCacheGateway.onDiscoveredEvent → LocalCache.consume path └─ consumeContactList (fixed) → _contactListEvents.tryEmit └─ WoTService.applyKind3 → handleKind3 → updateScore └─ Phase 3: fallback for missing-10002 authors → index-relay REQ └─ WoTService.markReadyOnce → _isReady.value = true → badge composables recompose Account switch └─ Main.kt:874 localCache.clear() → resets lastContactListByAuthor └─ Fix 3: WoTService.close() → cancels writer, drops ops channel └─ OutboxDispatcher scope cancels → in-flight REQs unsubscribe ``` ### Error & Failure Propagation - `client.subscribe` failure inside `OutboxDispatcher` → swallowed at the per-relay coroutine level, logged, moves on. The overall `withTimeoutOrNull` ensures the caller never blocks past its budget. - `AdvertisedRelayListEvent.writeRelaysNorm()` returning null (author has a 10002 but empty write list) → falls through to Phase 3 fallback. - Cache consume path errors (e.g. corrupt event) → existing `LocalCache` behavior; not new. ### State Lifecycle Risks - Between `WoTService.close()` and `OutboxDispatcher` scope cancel there's a small window where a pending REQ EOSE could arrive at a torn-down service. Mitigation: `OutboxCacheGateway.onDiscoveredEvent` and `WoTService.applyKind3` must be null-guarded against the "already-closed" state — WoTService's writerLoop naturally handles this (channel closed → loop exits). - Fix 1 requires Main.kt reordering; if the reorder is done wrong and pubkey bind is *later* than hydration, the bug recurs silently. Test: `DesktopLocalCacheHydrationTest.regressionOrderingProtection`. ### API Surface Parity `amy wot sync` and Desktop login both consume the same `OutboxDispatcher`, so any protocol change propagates. Android is a future consumer — the plan intentionally lives in commons/commonMain so wiring Android on top is a Main.kt-equivalent + gateway impl. ### Integration Test Scenarios 1. Cold-start login, well-connected account (~350 follows, ~90% with 10002): Phase 1 completes, Phase 2 fetches only from write relays, Phase 3 kicks in for the ~10% no-10002 authors, WoT ready < 5 s, badges render. 2. Cold-start login, ~4000-follow account: MAX_FOLLOWS trips → dispatcher skipped, `markReadyOnce()` immediately, no badges, no REQ traffic. 3. Cold-start login, all index relays unreachable: overall timeout fires, `markReadyOnce()`; on next `followedUsers` emission, `inFlight` is empty (thanks to fix 5) so a retry happens. 4. Mid-session follow: single-author `fetchKind3Only({newPubkey})` uses cache hit if `cachedOutbox(newPubkey) != null`, else does one Phase-1 REQ. 5. Account switch: `WoTService.close()` runs; opening the same account again creates a fresh instance without leaking the previous writer coroutine. 6. `amy wot sync` on a headless VM with only the OS event store: writes 10002 + kind 3 events to disk; second run of `amy wot get ` returns the correct hydrated score. ## Acceptance Criteria ### Functional - [ ] `DesktopLocalCache.consumeContactList` no longer stamps `lastContactListByAuthor` for the self path unless `accountPubkey` is set and the event matches. Regression test exists. - [ ] `WoTService` exposes `isDisabled: StateFlow`; caller (Main.kt) skips OutboxDispatcher when disabled. - [ ] `WoTService` implements `AutoCloseable`; account-switch path calls `close()`. - [ ] `FeedMetadataCoordinator.loadKind3Batched` and `loadMetadataBatched` retry on timeout (pubkeys not promoted to `succeeded`). - [ ] Both `loadKind3Batched` and `loadMetadataBatched` use single-writer EOSE aggregation (no `MutableSet` shared across dispatchers). - [ ] `OutboxDispatcher.fetchKind3Only` and `fetchKind0And3` exist in commons/commonMain with test coverage for the four scenarios in "Integration Test Scenarios". - [ ] `Main.kt` login path uses `OutboxDispatcher` for kind-3 seeding (WoT + follow-set metadata). - [ ] `amy wot sync` uses `OutboxDispatcher`; `--json` output additively gains `kind10002_received`, `kind3_received`, `fallback_authors`. ### Non-functional - [ ] `./gradlew test` green. - [ ] `./gradlew spotlessApply` clean before commit. - [ ] No production default relay list on this branch references `relay.damus.io` (already verified; keep it verified after refactor). - [ ] No use of `java.util.concurrent` / JVM-only `synchronized {}` in `commons/commonMain/`. - [ ] KDoc for `WoTService` accurately describes SnapshotStateMap per-key isolation. ### Quality Gates - [ ] Manual regression sheet covering integration scenarios 1-6 above. - [ ] `amy wot sync --json` sample output attached to PR description. - [ ] Follow-list-wipe regression covered by an automated test that hydrates a cached kind-3 before binding pubkey and asserts nothing is poisoned. ## Success Metrics - WoT badge coverage on real accounts (Vitor's expected win): jump from "index-relay-published authors only" to "any author with a 10002" — measured by running the desktop app before/after and diffing the badge count on a fixed follow-set. - Zero follow-list-wipe reports in the two weeks after merge (davotoula finding 1 was worst-case data loss). - Zero index-relay REQ traffic for kind-0/kind-3 authors that publish a 10002. Measurable by wireshark on a test build. ## Dependencies & Prerequisites - Quartz `AdvertisedRelayListEvent` + `RelayListRecommendationProcessor` — already exist, reused verbatim. - `INostrClient.subscribe(subId, filters, listener)` — already exists. - `DesktopLocalCache` needs a new `consumeAdvertisedRelayList(event, relay)` method — mirrors existing `consumeContactList` structure. - `OutboxRelayLoader` — moved from `amethyst/` to `commons/commonMain`; Android continues to compile because it only depends on things already in commons/quartz. No new third-party libraries introduced. No `libs.versions.toml` change. ## Risk Analysis & Mitigation | Risk | Likelihood | Impact | Mitigation | |------|------------|--------|------------| | Outbox refactor changes badge counts on live user accounts unexpectedly | Med | Med | Keep the Phase-3 fallback path so no author gets *worse* coverage than today. Manual A/B test on maintainer's account before merge. | | `RelayListRecommendationProcessor.reliableRelaySetFor` picks pathologically many relays for a fragmented follow set | Low | Low | Algorithm already caps by second-pass "at least 2 relays per author" rule. Add a hard `MAX_RELAYS_PER_FETCH` (say 40) as a belt-and-braces guard. | | Concurrent EOSE handshake rewrite introduces a new bug | Low | High | Test `FeedMetadataCoordinatorTest.eoseReadyUnderConcurrentCallbacks` with a fake client firing EOSE from three dispatchers 1000× to catch ordering assumptions. | | Bug fix 1 (Main.kt reordering) breaks another consumer that read localCache before accountPubkey bind | Med | Med | Grep for all `localCache.accountPubkey` reads; verify none pre-date the bind. If any, thread the pubkey through as a parameter. | | Adopting `AutoCloseable` on `WoTService` misleads callers into thinking it's `use`-scoped | Low | Low | Comment on `close()` says "call from account-switch/dispose only; instance lives for the account session". | | `amy wot sync --json` schema change breaks downstream scripts | Med | Low | Additive fields only, no renames. Document in `cli/plans/*` if a plan exists there. | ## Resource Requirements - One engineer, ~2-3 days including tests + manual regression. - Test-relay access: can use `wss://nos.lol` and Purple Pages for real Phase 1 verification. - Access to a mega-follow test account (>2000 follows) to verify Fix 2. - Access to an account with a well-populated 10002 network to verify Phase 2 does what we think. ## Future Considerations - Android wiring: `AndroidApp` currently doesn't wire WoTService. When it does, it can lean on the same `OutboxDispatcher` — expected diff is Main-equivalent + a `LocalCache` gateway. - Graperank scoring (Vitor's follow-up musing): if `amy wot` grows a scoring strategy plugin API, `OutboxDispatcher` remains unchanged; only the post-fetch aggregation layer inside `WoTService` changes. - Adopting `AmethystDefaults.DefaultIndexerRelayList`: separate ticket. Deserves its own review because it's a user-visible behaviour change. ## Documentation Plan - Update this plan's status to `completed` post-merge; write a short "solutions" note if the accountPubkey race surprised us elsewhere. - Update PR description "Behaviour" section to reflect outbox path. - Update `commons/ARCHITECTURE.md` "where does my code go?" section with a one-line entry for `OutboxDispatcher`. ## Sources & References ### Origin - **PR review comments:** https://github.com/vitorpamplona/amethyst/pull/3483#issuecomment-4892248528 (davotoula, bugs 1+2) https://github.com/vitorpamplona/amethyst/pull/3483#issuecomment-4892272000 (davotoula, bugs 3-6 impact on Android) https://github.com/vitorpamplona/amethyst/pull/3483#issuecomment-4892302009 (vitorpamplona, outbox directive) https://github.com/vitorpamplona/amethyst/pull/3483#issuecomment-4892686911 (vitorpamplona, Graperank musing — out of scope) ### Internal References - Kind-10002 parser: `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip65RelayList/AdvertisedRelayListEvent.kt` - Relay-cover algorithm: `quartz/src/commonMain/kotlin/com/vitorpamplona/quartz/nip65RelayList/RelayListRecommendationProcessor.kt` - Existing Android outbox loader: `amethyst/src/main/java/com/vitorpamplona/amethyst/model/topNavFeeds/OutboxRelayLoader.kt` - WoT service (bugs 2-4): `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/wot/WoTService.kt` - Feed metadata coordinator (bugs 5-6): `commons/src/commonMain/kotlin/com/vitorpamplona/amethyst/commons/relayClient/assemblers/FeedMetadataCoordinator.kt` - Cache race (bug 1): `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/cache/DesktopLocalCache.kt:509-530` - Main wiring: `desktopApp/src/jvmMain/kotlin/com/vitorpamplona/amethyst/desktop/Main.kt:1541-1568, 764-768, 863-874` - amy WoT: `cli/src/main/kotlin/com/vitorpamplona/amethyst/cli/commands/WotCommand.kt` - Index relay persistence: `commons/src/jvmMain/kotlin/com/vitorpamplona/amethyst/commons/relays/index/PreferencesIndexRelays.kt` - Baseline plan the PR extended: `desktopApp/plans/2026-07-01-feat-desktop-wot-score-plan.md` ### External References - NIP-65 (Relay List Metadata): https://github.com/nostr-protocol/nips/blob/master/65.md - Original plan for the current PR: `docs/plans/2026-07-01-feat-wot-followups-search-badges-and-index-relays-plan.md` ### Related Work - PR #3483 (this PR): https://github.com/vitorpamplona/amethyst/pull/3483 - Prior WoT badge PR (base for this branch): `feat/desktop-wot-score` ## Unanswered questions - Per-relay timeout budget — 4 s picked from thin air. Real number? - Should the fallback in Phase 3 also hit the account's own home/search relays, matching Android's `pickRelaysToLoadUsers` cascade? Or index-only? - WoTService.close() called from account-switch — what's the canonical disposal hook on Desktop? DesktopIAccount teardown? - amy wot sync `--json` schema — is `fallback_authors` the right name, or match Android naming? - Should `OutboxDispatcher` be a per-account singleton (like WoTService) or short-lived per fetch? Leaning singleton for the dedup set. - Do we want to persist the "author has no 10002" fact so we skip Phase 1 for them on next login? Requires a small persistent map — worth it? - Should Fix 1 (accountPubkey race) be split into its own hotfix commit before the outbox refactor lands, so backporters have a clean cherry-pick?