Reset stale fetching states on app launch

Add `reset_stale_fetching_states_internal` to `WpApiCache` that resets
`FetchingFirstPage` and `FetchingNextPage` states to `Idle` after migrations.

This prevents perpetual loading indicators when the app is killed during a
fetch operation. The reset runs in `perform_migrations()` because `WpApiCache`
is typically created once at app startup, unlike `MetadataService` which is
instantiated per-service.

Changes:
- Add `reset_stale_fetching_states_internal()` with comprehensive docs
- Call from `perform_migrations()` after migrations complete
- Add session handover document for MetadataService implementation

Author: oguzkocer

wp_mobile/docs/design/metadata_service_session_handover.md

@@ -0,0 +1,91 @@
+# MetadataService Session Handover
+
+## Completed Work
+
+### Phase 1: Database Foundation (wp_mobile_cache) ✅
+- Added `DbTable` variants: `ListMetadata`, `ListMetadataItems`, `ListMetadataState`
+- Created migration `0007-create-list-metadata-tables.sql` with 3 tables
+- Implemented `ListMetadataRepository` with full CRUD + concurrency helpers
+- 31 tests covering all repository operations
+
+### Phase 2: MetadataService (wp_mobile) ✅
+- Created `MetadataService` wrapping repository with site-scoped operations
+- Implements `ListMetadataReader` trait for compatibility with existing code
+- 15 tests covering service operations
+
+### Phase 3: Integration (partial) ✅
+- Added `metadata_service` field to `PostService`
+- Added `sync_post_list()` method for database-backed sync orchestration
+- Extended `SyncResult` with `current_page` and `total_pages` fields
+- Preserved existing in-memory `metadata_store` for backwards compatibility
+
+## Commits
+
+| Commit | Description |
+|--------|-------------|
+| `3c95dfb4` | Add database foundation for MetadataService (Phase 1) |
+| `e484f791` | Add list metadata repository concurrency helpers |
+| `3c85514b` | Add MetadataService for database-backed list metadata |
+| `5c83b435` | Integrate MetadataService into PostService |
+| `7f2166e4` | Update MetadataService implementation plan with progress |
+
+## Key Files
+
+- `wp_mobile_cache/src/list_metadata.rs` - Structs and `ListState` enum
+- `wp_mobile_cache/src/db_types/db_list_metadata.rs` - Column enums, `from_row` impls
+- `wp_mobile_cache/src/repository/list_metadata.rs` - Repository with all operations
+- `wp_mobile_cache/migrations/0007-create-list-metadata-tables.sql` - Schema
+- `wp_mobile/src/service/metadata.rs` - MetadataService implementation
+- `wp_mobile/src/service/posts.rs` - PostService integration
+
+## Test Coverage
+
+- `wp_mobile_cache`: 112 tests (31 new for list_metadata)
+- `wp_mobile`: 60 tests (15 new for MetadataService)
+
+---
+
+## Stale State on App Launch ✅ RESOLVED
+
+### Problem
+
+The `ListState` enum includes transient states (`FetchingFirstPage`, `FetchingNextPage`) that should not persist across app launches. If the app crashes during a fetch, these states remain in the database, causing perpetual loading indicators or blocked fetches on next launch.
+
+### Solution Implemented
+
+**Option B: Reset on `WpApiCache` initialization** was chosen.
+
+After `perform_migrations()` completes, we reset all fetching states to `Idle`:
+
+```rust
+// In WpApiCache::perform_migrations()
+Self::reset_stale_fetching_states_internal(connection);
+```
+
+### Why Option B Over Option A
+
+Option A (reset in `MetadataService::new()`) was rejected because `MetadataService` is not a singleton. Multiple services (PostService, CommentService, etc.) each create their own `MetadataService` instance. Resetting on each instantiation would incorrectly reset states when a new service is created mid-session.
+
+`WpApiCache` is typically created once at app startup, making it the right timing for session-boundary cleanup.
+
+### Design Decisions
+
+- **`Error` state is NOT reset**: It represents a completed (failed) operation, not an in-progress one. Preserving it allows UI to show "last sync failed" and aids debugging.
+- **Logs when states are reset**: Helps debugging by printing count of reset states.
+
+### Theoretical Issues (Documented in Code)
+
+If an app architecture creates multiple `WpApiCache` instances during a session (e.g., recreating after user logout/login), this would reset in-progress fetches. In practice this is rare, but the documentation in `WpApiCache::reset_stale_fetching_states_internal` explains alternatives if needed.
+
+See full documentation in `wp_mobile_cache/src/lib.rs`.
+
+---
+
+## Remaining Work
+
+See `metadata_service_implementation_plan.md` for full details:
+
+- **Phase 3.3**: Update collection creation to use sync callback
+- **Phase 3.4**: Remove deprecated in-memory store (after migration)
+- **Phase 4**: Observer split (data vs state observers)
+- **Phase 5.3**: Update example app

wp_mobile_cache/src/lib.rs

@@ -262,7 +262,13 @@ impl WpApiCache {
     pub fn perform_migrations(&self) -> Result<i64, SqliteDbError> {
         self.execute(|connection| {
             let mut mgr = MigrationManager::new(connection)?;
-            mgr.perform_migrations().map_err(SqliteDbError::from)
+            let version = mgr.perform_migrations().map_err(SqliteDbError::from)?;
+
+            // Reset stale fetching states after migrations complete.
+            // See `reset_stale_fetching_states` for rationale.
+            Self::reset_stale_fetching_states_internal(connection);
+
+            Ok(version)
         })
     }
 
@@ -301,6 +307,89 @@ impl WpApiCache {
 }
 
 impl WpApiCache {
+    /// Resets stale fetching states (`FetchingFirstPage`, `FetchingNextPage`) to `Idle`.
+    ///
+    /// # Why This Is Needed
+    ///
+    /// The `ListState` enum includes transient states that represent in-progress operations:
+    /// - `FetchingFirstPage` - A refresh/pull-to-refresh is in progress
+    /// - `FetchingNextPage` - A "load more" pagination fetch is in progress
+    ///
+    /// If the app is killed, crashes, or the process terminates while a fetch is in progress,
+    /// these states will persist in the database. On the next app launch:
+    /// - UI might show a perpetual loading indicator
+    /// - New fetch attempts might be blocked if code checks "already fetching"
+    /// - State is inconsistent with reality (no fetch is actually in progress)
+    ///
+    /// # Why We Reset in `WpApiCache` Initialization
+    ///
+    /// We considered several approaches:
+    ///
+    /// 1. **Reset in `MetadataService::new()`** - Rejected because `MetadataService` is not
+    ///    a singleton. Multiple services (PostService, CommentService, etc.) each create
+    ///    their own `MetadataService` instance. Resetting on each instantiation would
+    ///    incorrectly reset states when a new service is created mid-session.
+    ///
+    /// 2. **Reset in `WpApiCache` initialization** (this approach) - Chosen because
+    ///    `WpApiCache` is typically created once at app startup, making it the right
+    ///    timing for session-boundary cleanup.
+    ///
+    /// 3. **Session tokens** - More complex: tag states with a session ID and treat
+    ///    mismatched sessions as stale. Adds schema complexity for minimal benefit.
+    ///
+    /// 4. **In-memory only for fetching states** - Keep transient states in memory,
+    ///    only persist `Idle`/`Error`. Adds complexity in state management.
+    ///
+    /// # Theoretical Issues
+    ///
+    /// This approach assumes `WpApiCache` is created once per app session. If an app
+    /// architecture creates multiple `WpApiCache` instances during a session (e.g.,
+    /// recreating it after a user logs out and back in), this would reset in-progress
+    /// fetches. In practice:
+    /// - Most apps create `WpApiCache` once at startup
+    /// - If your architecture differs, consider wrapping this in a "first launch" check
+    ///   or using a session token approach
+    ///
+    /// # Note on `Error` State
+    ///
+    /// We intentionally do NOT reset `Error` states. These represent completed (failed)
+    /// operations, not in-progress ones. Preserving them allows:
+    /// - UI to show "last sync failed" on launch
+    /// - Debugging by inspecting `error_message`
+    ///
+    /// If you need a fresh start, the user can trigger a refresh which will overwrite
+    /// the error state.
+    fn reset_stale_fetching_states_internal(connection: &mut Connection) {
+        use crate::list_metadata::ListState;
+
+        // Reset both fetching states to idle
+        let result = connection.execute(
+            "UPDATE list_metadata_state SET state = ?1 WHERE state IN (?2, ?3)",
+            params![
+                ListState::Idle.as_db_str(),
+                ListState::FetchingFirstPage.as_db_str(),
+                ListState::FetchingNextPage.as_db_str(),
+            ],
+        );
+
+        match result {
+            Ok(count) if count > 0 => {
+                eprintln!(
+                    "WpApiCache: Reset {} stale fetching state(s) from previous session",
+                    count
+                );
+            }
+            Ok(_) => {
+                // No stale states found - normal case
+            }
+            Err(e) => {
+                // Log but don't fail - table might not exist yet on fresh install
+                // (though we run this after migrations, so it should exist)
+                eprintln!("WpApiCache: Failed to reset stale fetching states: {}", e);
+            }
+        }
+    }
+
     /// Execute a database operation with scoped access to the connection.
     ///
     /// This is the **only** way to access the database. The provided closure