feat(companion): implement contact trimming and retention policies

- Introduced `enforce_companion_contact_capacity` to manage contact limits during companion loading, with an option to trim non-favourite contacts when exceeding capacity.
- Updated `SQLiteHandler` to support message retention limits, allowing for automatic trimming of older messages based on `offline_queue_size`.
- Enhanced API endpoints to handle contact trimming on overflow, providing feedback on trimmed contacts during updates.
- Added utility functions for selecting and trimming contacts while preserving favourites.
- Improved logging for contact management actions and errors related to capacity.

repeater/data_acquisition/sqlite_handler.py

@@ -2600,7 +2600,9 @@ class SQLiteHandler:
             logger.error(f"Failed to load companion messages: {e}")
             return []
 
-    def companion_push_message(self, companion_hash: str, msg: Dict) -> bool:
+    def companion_push_message(
+        self, companion_hash: str, msg: Dict, max_messages: Optional[int] = None
+    ) -> bool:
         """Append a message to the companion's queue.
 
         Deduplicates by (companion_hash, packet_hash) using INSERT OR IGNORE
@@ -2608,6 +2610,9 @@ class SQLiteHandler:
         previous SELECT + INSERT round-trip (two statements, two SD-card reads)
         with a single atomic statement.
 
+        When ``max_messages`` is set, the oldest rows beyond that retention limit
+        are trimmed after a successful insert (power-user ``offline_queue_size``).
+
         Returns True if inserted, False if the message was a duplicate (skipped).
         """
         try:
@@ -2636,8 +2641,23 @@ class SQLiteHandler:
                         time.time(),
                     ),
                 )
+                inserted = cursor.rowcount > 0
+                if inserted and max_messages is not None:
+                    # Keep the newest `max_messages` rows; drop older overflow.
+                    conn.execute(
+                        """
+                        DELETE FROM companion_messages
+                        WHERE companion_hash = ? AND id NOT IN (
+                            SELECT id FROM companion_messages
+                            WHERE companion_hash = ?
+                            ORDER BY created_at DESC, id DESC
+                            LIMIT ?
+                        )
+                        """,
+                        (companion_hash, companion_hash, max_messages),
+                    )
                 conn.commit()
-                return cursor.rowcount > 0
+                return inserted
         except Exception as e:
             logger.error(f"Failed to push companion message: {e}")
             return False