amethyst/docs/plans/2026-03-24-feat-weakref-cache-state-extraction-plan.md

---
title: "feat: WeakReference Cache + State Class Extraction"
type: feat
status: active
date: 2026-03-24
origin: docs/brainstorms/2026-03-24-weakref-cache-architecture-brainstorm.md
---

# feat: WeakReference Cache + State Class Extraction

## Enhancement Summary

**Deepened on:** 2026-03-24
**Agents used:** kotlin-expert, kotlin-multiplatform, kotlin-coroutines, gradle-expert, architecture-strategist, performance-oracle, code-simplicity-reviewer, pattern-recognition-specialist

### Key Improvements from Deepening
1. **Source set correction:** `commons/jvmAndroid` not `jvmMain` — both KMP + Gradle agents confirmed
2. **Massive simplification:** Extract 5 State classes now (not 22) — only what Desktop needs today
3. **Per-feature repositories** instead of single `IAccountSettings` — matches existing commons pattern (`EphemeralChatRepository`, `PublicChatListRepository`)
4. **Fix ICacheProvider `Any?` returns directly** — `User`/`Note` already in commons, no new methods needed
5. **DecryptionCaches are pure Kotlin** — move as-is, no interfaces needed
6. **Performance fixes:** `AtomicInteger` size tracker, single-pass `cleanUp()`, debounced `findUsersStartingWith`
7. **Heap monitoring:** `MemoryMXBean` check every 30s, cleanup at >75% or every 5min
8. **2 phases not 4** — cache swap + note pinning

### Critical Issues Discovered
1. **Static `LocalCache.justConsumeMyOwnEvent()` calls** in State classes bypass injected cache param — must fix during extraction
2. **`findUsersStartingWith` becomes O(n) per keystroke** with no cap — needs debouncing
3. **`size()` is O(n)** on ConcurrentSkipListMap — add AtomicInteger tracker
4. **Note.replies unbounded growth** for pinned notes — pruning is NOT optional for long-running Desktop sessions

---

## Overview

Replace `BoundedLargeCache` (strong refs, 50k cap, arbitrary eviction) with Android's `LargeSoftCache` (WeakReference-based, GC-driven). Extract 5 critical note-pinning State classes from `amethyst/` to `commons/` so Desktop gets the same retention logic. All in existing PR #1905 on branch `feat/desktop-cache-v2`.

(see brainstorm: `docs/brainstorms/2026-03-24-weakref-cache-architecture-brainstorm.md`)

## Problem Statement

Vitor's feedback on PR #1905: `BoundedLargeCache` causes notes to "just disappear" because eviction is by lowest hex key order — ignoring whether notes are displayed, replied-to, or part of a thread. Android solved this with `LargeSoftCache<K, WeakReference<V>>` where GC respects the reference graph.

Desktop's `DesktopIAccount` has **zero State objects** — it stubs everything. The State classes that pin important notes (bookmarks, follow list, mute list, relay lists, metadata) are Android-only.

## Proposed Solution

Two-phase approach (simplified from original 4 phases):

1. **Phase 1: Cache swap** — Move `LargeSoftCache` to `commons/jvmAndroid`, fix `ICacheProvider` types, replace `BoundedLargeCache`, add cleanup loop
2. **Phase 2: Pin critical notes** — Extract 5 State classes to `commons/commonMain`, wire in `DesktopIAccount`

Remaining 17 State classes extracted incrementally as Desktop builds features that need them.

## Technical Approach

### Architecture

```
┌──────────────────────────────────────────────────────┐
│              LargeSoftCache<K, WeakRef<V>>            │
│              (commons/jvmAndroid/ — shared)           │
│                                                      │
│  notes: LargeSoftCache<HexKey, Note>                 │
│  users: LargeSoftCache<HexKey, User>                 │
│  addressables: LargeSoftCache<String, AddressableNote>│
└───────────────────────┬──────────────────────────────┘
                        │ WeakRef (GC-managed)
    ┌───────────────────▼───────────────────┐
    │         Note Reference Graph           │
    │  (strong refs: replies, reactions,     │
    │   zaps, boosts, replyTo, author)       │
    │                                        │
    │  Clusters survive together.            │
    │  GC collects entire cluster when       │
    │  no external strong ref remains.       │
    └───────────────────┬───────────────────┘
                        │ strong refs (pinning)
    ┌───────────────────▼───────────────────┐
    │      State Classes (commons/)          │
    │  (hold strong refs to important notes) │
    │                                        │
    │  BookmarkListState → bookmarkList note │
    │  Kind3FollowListState → contact list   │
    │  MuteListState → mute list note        │
    │  Nip65RelayListState → relay list      │
    │  UserMetadataState → metadata note     │
    │                                        │
    │  Live on Account (Android) or          │
    │  DesktopIAccount (Desktop) — both      │
    │  implement IAccount                    │
    └───────────────────────────────────────┘
```

### Implementation Phases

---

#### Phase 1: Cache Swap (~1 day)

**Goal:** Replace BoundedLargeCache with LargeSoftCache, fix ICacheProvider types, add cleanup.

##### 1a. Fix ICacheProvider return types (prerequisite)

**File:** `commons/src/commonMain/kotlin/.../model/cache/ICacheProvider.kt`

`User`, `Note`, `AddressableNote` all live in `commons/commonMain/` already. The `Any?` returns are a legacy artifact. Change directly:

```kotlin
interface ICacheProvider {
    // Change these from Any? to proper types
    fun getUserIfExists(pubkey: HexKey): User?        // was Any?
    fun getNoteIfExists(hexKey: HexKey): Note?         // was Any?
    fun getOrCreateUser(pubkey: HexKey): User?          // was Any?
    fun findUsersStartingWith(prefix: String, limit: Int = 50): List<User>  // was List<Any>

    // Already typed correctly — no change
    fun checkGetOrCreateNote(hexKey: HexKey): Note?
    fun getOrCreateAddressableNote(key: Address): AddressableNote
    fun justConsumeMyOwnEvent(event: Event): Boolean
    // ...
}
```

Callers that currently cast `as? User` just drop the cast. No breakage.

**Research Insight (kotlin-expert):** `User`/`Note` are already in commons — the `Any?` returns were from an earlier extraction. Safe to fix now.

##### 1b. Move LargeSoftCache to commons/jvmAndroid

**From:** `amethyst/src/main/java/.../model/LargeSoftCache.kt`
**To:** `commons/src/jvmAndroid/kotlin/.../model/cache/LargeSoftCache.kt`

**Research Insight (KMP + Gradle agents):** Must be `jvmAndroid`, NOT `jvmMain`. The `jvmAndroid` source set in commons already exists (line 85-90 of `commons/build.gradle.kts`). Both `jvmMain` and `androidMain` depend on it. Zero Gradle changes needed. `CacheOperations` from `quartz/jvmAndroid` is visible transitively.

**Changes:**
- Move file, update package to `com.vitorpamplona.amethyst.commons.model.cache`
- Update Android's `LocalCache.kt` import (only file that imports it)

**Performance improvements to LargeSoftCache:**

```kotlin
class LargeSoftCache<K : Any, V : Any> : CacheOperations<K, V> {
    private val cache = ConcurrentSkipListMap<K, WeakReference<V>>()

    // NEW: O(1) approximate size tracking (performance-oracle recommendation)
    private val _size = AtomicInteger(0)
    fun approximateSize(): Int = _size.get()

    fun put(key: K, value: V) {
        val prev = cache.put(key, WeakReference(value))
        if (prev == null) _size.incrementAndGet()
    }

    // IMPROVED: Single-pass cleanUp (performance-oracle: ~40% faster, zero alloc)
    fun cleanUp() {
        val iter = cache.entries.iterator()
        while (iter.hasNext()) {
            val entry = iter.next()
            if (entry.value.get() == null) {
                iter.remove()
                _size.decrementAndGet()
            }
        }
    }
    // ... rest unchanged
}
```

##### 1c. Replace BoundedLargeCache on Desktop

**File:** `desktopApp/.../cache/DesktopLocalCache.kt`

```kotlin
// Before
val users = BoundedLargeCache<HexKey, User>(MAX_USERS)
val notes = BoundedLargeCache<HexKey, Note>(MAX_NOTES)
val addressableNotes = BoundedLargeCache<String, AddressableNote>(MAX_ADDRESSABLE)

// After
val users = LargeSoftCache<HexKey, User>()
val notes = LargeSoftCache<HexKey, Note>()
val addressableNotes = LargeSoftCache<String, AddressableNote>()
```

**Remove:** `BoundedLargeCache.kt`, `MAX_NOTES`/`MAX_USERS`/`MAX_ADDRESSABLE` constants.

**API differences:**
- `BoundedLargeCache.values()` → use `forEach` + collect
- `BoundedLargeCache.count(predicate)` → available via `CacheOperations`
- `userCount()`/`noteCount()` → use `approximateSize()` (O(1) vs O(n))

**Performance fix for `findUsersStartingWith`:**

```kotlin
// Before: O(n) per keystroke with no cap
// After: debounce at call site + yield during iteration
override fun findUsersStartingWith(prefix: String, limit: Int): List<User> {
    val results = mutableListOf<User>()
    users.forEach { _, user ->
        if (results.size >= limit) return@forEach
        if (user.anyNameStartsWith(prefix)) results.add(user)
    }
    return results
}
```

Call sites must debounce to 300ms. Acceptable because search already uses debounced state.

##### 1d. Add Desktop cleanup loop

**Research Insight (kotlin-coroutines):** Inline in coordinator, no abstraction needed. `Dispatchers.Default` for CPU-bound work. `Mutex.tryLock()` if heap trigger added. `yield()` every 1000 items.

```kotlin
// In Coordinator or Main.kt — inline, no CacheCleanupService needed
private val cleanupScope = CoroutineScope(
    SupervisorJob() + Dispatchers.Default + CoroutineExceptionHandler { _, t ->
        println("Cleanup failed, will retry: ${t.message}")
    }
)

private val memoryBean = ManagementFactory.getMemoryMXBean()
private var lastCleanupTime = 0L

val cleanupJob = cleanupScope.launch {
    delay(2.minutes) // Grace period for startup
    while (isActive) {
        delay(30.seconds) // Check frequently, clean infrequently
        val heapPct = memoryBean.heapMemoryUsage.let { it.used.toDouble() / it.max }
        val elapsed = System.currentTimeMillis() - lastCleanupTime

        if (heapPct > 0.75 || elapsed > 5.minutes.inWholeMilliseconds) {
            val ops = listOf(
                "cleanMemory" to { localCache.cleanMemory() },
                "cleanObservers" to { cleanObserversWithYield() },
                "pruneExpired" to { localCache.pruneExpiredEvents() },
                "pruneReplaceables" to { localCache.prunePastVersionsOfReplaceables() },
            )
            ops.forEach { (name, op) ->
                try { op() } catch (e: Exception) {
                    println("Cleanup $name failed: ${e.message}")
                }
            }
            lastCleanupTime = System.currentTimeMillis()
        }
    }
}

private suspend fun cleanObserversWithYield() {
    var count = 0
    localCache.notes.forEach { _, note ->
        note.clearFlow()
        if (++count % 1000 == 0) yield()
    }
}
```

##### Phase 1 Acceptance Criteria

- [ ] `ICacheProvider` methods return typed `User?`/`Note?` (not `Any?`)
- [ ] `LargeSoftCache` in `commons/src/jvmAndroid/kotlin/.../model/cache/`
- [ ] `LargeSoftCache` has `AtomicInteger` size tracker + single-pass `cleanUp()`
- [ ] Android's `LocalCache` imports from commons (one import change)
- [ ] Desktop's `DesktopLocalCache` uses `LargeSoftCache`
- [ ] `BoundedLargeCache.kt` deleted
- [ ] Desktop cleanup loop: periodic + heap-pressure triggered
- [ ] `findUsersStartingWith` debounced at call sites
- [ ] `./gradlew :commons:compileKotlinJvm :amethyst:compileDebugKotlin :desktopApp:compileKotlin` passes

---

#### Phase 2: Pin Critical Notes (~1-2 days)

**Goal:** Extract 5 essential State classes to commons so Desktop pins important notes.

##### Why only 5 (not 22)?

**Research Insight (code-simplicity-reviewer):** Desktop currently has zero State classes and zero UI for most of the 22 features. Only 5 State classes serve features Desktop has today:

| State Class | Why Desktop needs it now |
|-------------|------------------------|
| BookmarkListState | Bookmarks screen exists |
| Kind3FollowListState | Follow list drives home feed |
| Nip65RelayListState | Relay list drives subscriptions |
| MuteListState | Content filtering |
| UserMetadataState | Profile display |

The other 17 (GeohashList, ProxyRelay, IndexerRelay, etc.) pin notes for features Desktop hasn't built yet. Extract them when needed.

##### 2a. Per-feature repository interfaces (not IAccountSettings)

**Research Insight (pattern-recognition-specialist):** The existing commons State classes use **per-feature repository interfaces**, not a shared settings interface:

- `EphemeralChatRepository` — 2 methods: `ephemeralChatList()`, `updateEphemeralChatListTo()`
- `PublicChatListRepository` — 2 methods: `publicChatList()`, `updatePublicChatListTo()`

Follow the same pattern. Each State class gets a narrow repository interface:

```kotlin
// commons/commonMain — one per State class that uses settings
interface Kind3FollowListRepository {
    val backupContactList: ContactListEvent?
    fun updateContactListTo(event: ContactListEvent)
}

interface MuteListRepository {
    val backupMuteList: MuteListEvent?
    fun updateMuteList(event: MuteListEvent)
}

interface Nip65RelayListRepository {
    val backupNIP65RelayList: AdvertisedRelayListEvent?
    fun updateNIP65RelayList(event: AdvertisedRelayListEvent)
}
// UserMetadataState — audit for specific settings usage
```

Android's `AccountSettings` implements all 5 interfaces. Desktop implements with stubs initially (no persistence yet), returning null for backup events.

**Naming convention (pattern-recognition):** `I` prefix for broad abstractions (`IAccount`, `ICacheProvider`). No prefix for narrow feature-scoped interfaces (`Kind3FollowListRepository`, `MuteListRepository`).

##### 2b. Move DecryptionCaches as-is

**Research Insight (kotlin-expert):** DecryptionCaches are pure Kotlin wrappers around `PrivateTagArrayEventCache<T>` from `quartz/commonMain`. No interfaces needed, no Android deps:

```kotlin
// Already works in commons/commonMain — no changes needed
class MuteListDecryptionCache(val signer: NostrSigner) {
    val cachedPrivateLists = PrivateTagArrayEventCache<MuteListEvent>(signer)
}
```

Only `MuteListState` uses a DecryptionCache among the initial 5 State classes. Move `MuteListDecryptionCache` alongside it.

##### 2c. Fix static LocalCache calls

**Research Insight (pattern-recognition + architecture):** Several State classes call `LocalCache.justConsumeMyOwnEvent(event)` as a **static singleton call**, not through the injected `cache` parameter. Found in:
- `Kind3FollowListState` (line 168)
- `MuteListState` (line 147)
- `SearchRelayListState` (line 108)

During extraction, change to `cache.justConsumeMyOwnEvent(event)` — the method already exists on `ICacheProvider`.

##### 2d. Extraction order

1. **BookmarkListState** — no settings, no decryptionCache, simplest. Verify imports: change `amethyst.model.Note` → `amethyst.commons.model.Note`
2. **Nip65RelayListState** — needs `Nip65RelayListRepository` interface
3. **Kind3FollowListState** — needs `Kind3FollowListRepository`, fix static `LocalCache` call
4. **MuteListState** — needs `MuteListRepository` + move `MuteListDecryptionCache`, fix static call
5. **UserMetadataState** — audit settings usage, create repository interface

##### 2e. Wire State classes on DesktopIAccount

```kotlin
class DesktopIAccount(
    private val accountState: AccountState.LoggedIn,
    val localCache: DesktopLocalCache,
    // ...
) : IAccount {
    // Stub repositories — no persistence yet, return null for backups
    private val kind3Repo = object : Kind3FollowListRepository {
        override val backupContactList: ContactListEvent? = null
        override fun updateContactListTo(event: ContactListEvent) { /* no-op for now */ }
    }
    // ... similar stubs for other repos

    val bookmarkList = BookmarkListState(signer, localCache, scope)
    val kind3FollowList = Kind3FollowListState(signer, localCache, scope, kind3Repo)
    val nip65RelayList = Nip65RelayListState(signer, localCache, scope, nip65Repo)
    val muteList = MuteListState(signer, localCache, MuteListDecryptionCache(signer), scope, muteRepo)
    val userMetadata = UserMetadataState(signer, localCache, scope, metadataRepo)
}
```

##### Phase 2 Acceptance Criteria

- [ ] 5 State classes in `commons/commonMain/`
- [ ] Per-feature repository interfaces (not single IAccountSettings)
- [ ] `MuteListDecryptionCache` moved alongside `MuteListState`
- [ ] All static `LocalCache.` calls changed to `cache.` (injected)
- [ ] Android's `Account` imports State classes from commons (no behavior change)
- [ ] Desktop's `DesktopIAccount` creates 5 State objects with stub repos
- [ ] Pinned AddressableNotes survive GC on Desktop
- [ ] `@Stable`/`@Immutable` annotations compile on all targets
- [ ] `./gradlew spotlessApply` + all modules compile

---

## System-Wide Impact

### Interaction Graph

```
Event arrives from relay
  → Coordinator.consumeEvent()
    → DesktopLocalCache.consume()
      → notes.getOrCreate(id) [LargeSoftCache — creates WeakRef]
        → Note populated with event, author, relationships
          → Note.addReply/addReaction/addZap [strong refs to related notes]
            → eventStream.emit()
              → FeedViewModels receive update

State class created on DesktopIAccount
  → State.init { cache.getOrCreateAddressableNote(address) }
    → AddressableNote pinned via strong ref on State object
      → Note's reference graph (replies, reactions) also pinned transitively
        → Cluster survives GC

Periodic cleanup (every 5 min or heap > 75%)
  → LargeSoftCache.cleanUp() sweeps stale WeakRef entries (single-pass)
  → cleanObservers() clears unused NoteFlowSets (yield every 1000)
  → pruneExpiredEvents() removes NIP-40 expired notes
  → prunePastVersionsOfReplaceables() keeps only latest replaceable
```

### Error Propagation

- **getOrCreate race:** Two threads create same Note → `putIfAbsent` ensures one wins. Note constructor is pure (just stores `idHex`), no side effects. Acceptable.
- **GC during render:** Compose holds strong ref during composition. Cache eviction can't crash.
- **State class missing:** If a State class isn't created, that note type has no pin → GC can collect. Mitigated by creating all 5 critical ones at init.

### State Lifecycle Risks

- **Note.replies unbounded growth:** Pinned notes keep all replies alive via strong refs. For long-running Desktop sessions, this grows monotonically. `pruneRepliesAndReactions` is account-dependent — tracked as follow-up work (not deferred indefinitely).
- **NoteFlowSet leak:** `cleanObservers()` with `yield()` handles this.
- **`SharingStarted.Eagerly` on State classes:** All 5 State classes use `stateIn(scope, SharingStarted.Eagerly)`. Desktop has no process lifecycle to bound this. Consider `WhileSubscribed(5000)` for non-critical states when expanding beyond 5.
- **Replaceable event swap:** AddressableNote stays pinned, `.event` swaps. FlowSet emits. No orphaned refs.

### Performance Characteristics

| Operation | Before (BoundedLargeCache) | After (LargeSoftCache) |
|-----------|---------------------------|----------------------|
| `size()` | O(1) via AtomicInteger | O(1) via AtomicInteger (new) |
| `get(key)` | O(log n), strong ref | O(log n), WeakRef deref |
| `forEach` | O(n), no GC checks | O(n), GC check per entry |
| `cleanUp()` | N/A (evict by key order) | O(n) single-pass iterator |
| `findUsersStartingWith` | O(n) capped at 25k | O(n) uncapped — **debounce required** |
| Eviction | Arbitrary (by hex key) | GC-driven (respects refs) |
| Memory cap | Hard (50k/25k/10k) | None (GC-managed) |

## Acceptance Criteria

### Functional

- [ ] Desktop cache uses WeakReferences — no hard size limits
- [ ] Notes only disappear when nothing references them (not arbitrarily)
- [ ] Bookmarks, contact list, mute list, relay lists, metadata pinned on Desktop
- [ ] Navigation persistence maintained (existing behavior)
- [ ] Android behavior unchanged (same code, new import path)

### Non-Functional

- [ ] `BoundedLargeCache` deleted
- [ ] 5 critical State classes in commons
- [ ] Periodic + heap-triggered cleanup on Desktop
- [ ] `LargeSoftCache` shared from `commons/jvmAndroid/`
- [ ] `ICacheProvider` returns typed `User?`/`Note?`
- [ ] `./gradlew spotlessApply` + compile on all modules

## Dependencies & Risks

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Static `LocalCache.` calls in State classes | High | High | Audit each class. Found in Kind3FollowList, MuteList, SearchRelay. Change to `cache.` |
| `findUsersStartingWith` O(n) jank | High | Medium | Debounce 300ms at call sites. Already debounced in search UI. |
| `size()` O(n) in logging paths | Medium | Low | `AtomicInteger` tracker on LargeSoftCache. Use `approximateSize()`. |
| Note.replies unbounded growth | Medium | Medium | Follow-up: implement non-account-dependent reply cap (e.g., 500 per note) |
| Import path changes break Android | Low | Medium | Only `LocalCache.kt` changes import. One-line diff. |
| BookmarkListState imports `amethyst.model.Note` (wrong package) | Low | Low | Change to `amethyst.commons.model.Note` during extraction |

## Future Work (tracked, not deferred indefinitely)

1. **Extract remaining 17 State classes** — as Desktop builds features that need them
2. **`pruneRepliesAndReactions`** — non-account-dependent reply/reaction cap (e.g., 500 per note) to bound memory for popular threads
3. **Desktop persistence** — implement real `Kind3FollowListRepository` etc. with disk-backed storage
4. **`SharingStarted.WhileSubscribed`** — for non-critical State classes when expanding beyond 5

## Success Metrics

- BoundedLargeCache eviction bugs → eliminated (WeakRef model)
- Desktop note retention → matches Android behavior for 5 critical types
- Android behavior → unchanged (regression-free)
- Desktop memory stability → heap monitoring confirms GC collects unpinned notes

## Sources & References

### Origin

- **Brainstorm:** [docs/brainstorms/2026-03-24-weakref-cache-architecture-brainstorm.md](docs/brainstorms/2026-03-24-weakref-cache-architecture-brainstorm.md) — Key decisions: LargeSoftCache shared, extract State classes, same pinning as Android, extensible for Desktop-specific pins later, one PR in existing #1905

### Internal References

- Prior clean-cache plan: `docs/plans/2026-03-22-feat-clean-cache-single-source-of-truth-plan.md`
- Cache architecture brainstorm: `docs/brainstorms/2026-03-17-desktop-cache-architecture-brainstorm.md`
- Android LargeSoftCache: `amethyst/src/main/java/.../model/LargeSoftCache.kt`
- Android LocalCache: `amethyst/src/main/java/.../model/LocalCache.kt`
- Android Account (State objects): `amethyst/src/main/java/.../model/Account.kt`
- Android MemoryTrimmingService: `amethyst/src/main/java/.../service/eventCache/MemoryTrimmingService.kt`
- Desktop DesktopLocalCache: `desktopApp/.../cache/DesktopLocalCache.kt`
- Desktop BoundedLargeCache: `desktopApp/.../cache/BoundedLargeCache.kt`
- Desktop DesktopIAccount: `desktopApp/.../model/DesktopIAccount.kt`
- ICacheProvider: `commons/.../model/cache/ICacheProvider.kt`
- CacheOperations: `quartz/src/jvmAndroid/.../utils/cache/CacheOperations.kt`
- Note model: `commons/.../model/Note.kt`
- Existing pattern: `EphemeralChatRepository` / `PublicChatListRepository` in commons

### Research Insights Applied

- **kotlin-expert:** DecryptionCaches are pure Kotlin (move as-is), fix `Any?` returns directly, normalize static LocalCache calls, only 3 files use `@Stable`/`@Immutable`
- **kotlin-multiplatform:** `commons/jvmAndroid` (not `jvmMain`), zero Gradle changes, `CacheOperations` visible transitively
- **kotlin-coroutines:** `SupervisorJob` + `Dispatchers.Default`, `Mutex.tryLock()` for heap trigger, `yield()` every 1000 items, 2-min startup grace period
- **gradle-expert:** Zero build.gradle.kts changes needed, no circular deps introduced
- **architecture-strategist:** Fix ICacheProvider types as Phase 0 prerequisite, `pruneRepliesAndReactions` is NOT optional for Desktop, consider `SharingStarted.WhileSubscribed` for non-critical states
- **performance-oracle:** `AtomicInteger` size tracker, single-pass `cleanUp()`, `findUsersStartingWith` O(n) jank needs debouncing, non-account-dependent reply cap needed
- **code-simplicity-reviewer:** 5 State classes not 22, per-feature repos not IAccountSettings, inline cleanup not CacheCleanupService, 2 phases not 4
- **pattern-recognition-specialist:** Per-feature repository interfaces match `EphemeralChatRepository` pattern, `I` prefix for broad abstractions only, static `LocalCache.` calls are extraction blockers

### Resolved Questions (from original plan)

1. **AccountSettings audit** → Resolved: use per-feature repository interfaces, not single IAccountSettings. Each State class gets a narrow 2-method interface.
2. **DecryptionCache complexity** → Resolved: pure Kotlin wrappers around quartz's `PrivateTagArrayEventCache`. Move as-is, no interfaces.
3. **ICacheProvider Any? methods** → Resolved: `User`/`Note` already in commons. Change return types directly. Callers drop casts.
4. **Account-dependent prune timing** → Resolved: follow-up work, not deferred. Implement non-account-dependent reply cap (500 per note) as next step.