Add ListMetadataRepository for paginated list state tracking

[oguzkocer]

Summary

Adds ListMetadataRepository to wp_mobile_cache for tracking paginated list state, enabling efficient cache invalidation and stale detection.

Database Schema

┌─────────────────────────────────────┐
│           list_metadata             │
├─────────────────────────────────────┤
│ rowid          INTEGER PK           │
│ db_site_id     INTEGER FK ──────────┼──► db_sites
│ key            TEXT                 │
│ total_pages    INTEGER?             │
│ total_items    INTEGER?             │
│ current_page   INTEGER              │
│ per_page       INTEGER              │
│ version        INTEGER              │
│ last_first_page_fetched_at  TEXT?   │
│ last_fetched_at             TEXT?   │
└─────────────────────────────────────┘
         │
         │ 1:1                     1:n
         ▼                          │
┌─────────────────────────────┐     │
│    list_metadata_state      │     │
├─────────────────────────────┤     │
│ rowid            INTEGER PK │     │
│ list_metadata_id INTEGER FK─┼──┐  │
│ state            INTEGER    │  │  │
│ error_message    TEXT?      │  │  │
│ updated_at       TEXT       │  │  │
└─────────────────────────────┘  │  │
                                 │  │
┌─────────────────────────────┐  │  │
│    list_metadata_items      │  │  │
├─────────────────────────────┤  │  │
│ rowid            INTEGER PK │  │  │
│ list_metadata_id INTEGER FK─┼──┴──┘
│ entity_id        INTEGER    │
│ modified_gmt     TEXT?      │
│ parent           INTEGER?   │
│ menu_order       INTEGER?   │
└─────────────────────────────┘

Type Hierarchy

ListKey (newtype)
    │
    └──► String

ListState (enum, repr(i32))
    ├── Idle = 0
    ├── FetchingFirstPage = 1
    ├── FetchingNextPage = 2
    └── Error = 3

DbListMetadata ◄─────────────────┐
    ├── row_id: RowId            │
    ├── db_site_id: RowId        │  from_row()
    ├── key: String              │
    ├── total_pages: Option      │
    ├── current_page: i64        │
    ├── per_page: i64            │
    └── version: i64             │
                                 │
DbListMetadataItem ◄─────────────┤
    ├── row_id: RowId            │
    ├── list_metadata_id: RowId  │
    ├── entity_id: i64           │
    ├── modified_gmt: Option     │
    ├── parent: Option           │
    └── menu_order: Option       │
                                 │
DbListMetadataState ◄────────────┤
    ├── row_id: RowId            │
    ├── list_metadata_id: RowId  │
    ├── state: ListState         │
    └── error_message: Option    │
                                 │
DbListHeaderWithState ◄──────────┘  (JOIN query result)
    ├── state: ListState
    ├── error_message: Option
    ├── current_page: i64
    ├── total_pages: Option
    ├── total_items: Option
    └── per_page: i64

Key Features

• Concurrency control: Version numbers detect stale load-more operations after refresh
• Batch inserts: Items inserted in batches for performance
• Type safety: ListKey newtype prevents misuse of arbitrary strings; ListState stored as INTEGER with ToSql/FromSql
• Race condition handling: get_or_create catches constraint violations and retries
• Atomic upsert: get_or_create_and_increment_version uses INSERT ... ON CONFLICT DO UPDATE ... RETURNING

Repository Operations

ListMetadataRepository (associated functions)
    │
    ├── Read
    │   ├── get_header(site, key)
    │   ├── get_items_by_list_metadata_id / get_items_by_list_key
    │   ├── get_item_count_by_list_metadata_id / get_item_count_by_list_key
    │   ├── get_state_by_list_metadata_id / get_state_by_list_key
    │   ├── get_version_by_list_metadata_id / get_version_by_list_key
    │   └── get_header_with_state(site, key)
    │
    ├── Write
    │   ├── get_or_create(site, key, per_page)
    │   ├── get_or_create_and_increment_version(site, key, per_page)
    │   ├── set_items_by_list_metadata_id / set_items_by_list_key
    │   ├── append_items_by_list_metadata_id / append_items_by_list_key
    │   ├── update_header_by_list_metadata_id / update_header_by_list_key
    │   ├── update_state_by_list_metadata_id / update_state_by_list_key
    │   └── delete_list(list_metadata_id)
    │
    └── Utility
        └── reset_stale_fetching_states()  ─► runs on migration

Error Handling

• ConstraintViolation - detected from rusqlite::Error for race condition handling
• PerPageMismatch { expected, actual } - when existing header has different per_page than requested

Design Decisions

• Repository is primitive-only: No orchestration/concurrency helpers; these belong in a future service layer
• per_page is required: Must be passed by caller to match networking config; returns error on mismatch rather than silently using existing value
• Dual method variants: _by_list_metadata_id for callers with cached rowid, _by_list_key for convenience
• PRAGMA-based tests: Column enum indices verified against actual database schema

Changes

• Add migration 0007-create-list-metadata-tables.sql
• Add ListKey, ListState, and DB types in list_metadata.rs
• Add column enums in db_types/db_list_metadata.rs
• Add ListMetadataRepository with associated functions
• Add ConstraintViolation and PerPageMismatch error variants to SqliteDbError
• Add log crate dependency for structured logging
• Call reset_stale_fetching_states after migrations complete

[jkmassel]

Left one thought about potential enhancement, but not critical.

[jkmassel]

I wonder if it'd make sense to store this as an integer (in the DB too)? Seems faster than string parsing, and more space-efficient?

Not 100% convinced we need that particular performance win, just noting it because it came to mind.

[oguzkocer]

Makes sense. We need these to be consistent across the board too, let me add a personal TODO for this and handle it on its own PR in the next 2 weeks.