refactor: improve function naming for clarity and consistency

Rename functions to use clearer verb-based names:
- pick_best_live_path → select_best_live_path
- escape_like_prefix → escape_sql_like_string
- list_tree → list_files_recursively
- check_asset_file_fast → verify_asset_file_unchanged
- _seed_from_paths_batch → _batch_insert_assets_from_paths
- reconcile_cache_states_for_root → sync_cache_states_with_filesystem
- touch_asset_info_by_id → update_asset_info_access_time
- replace_asset_info_metadata_projection → set_asset_info_metadata
- expand_metadata_to_rows → convert_metadata_to_rows
- _rows_per_stmt → _calculate_rows_per_statement
- ensure_within_base → validate_path_within_base
- _cleanup_temp → _delete_temp_file_if_exists
- validate_hash_format → normalize_and_validate_hash
- get_relative_to_root_category_path_of_asset → get_asset_category_and_relative_path

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

tests-unit/assets_test/queries/test_asset_info.py

@@ -13,8 +13,8 @@ from app.assets.database.queries import (
     list_asset_infos_page,
     fetch_asset_info_asset_and_tags,
     fetch_asset_info_and_asset,
-    touch_asset_info_by_id,
-    replace_asset_info_metadata_projection,
+    update_asset_info_access_time,
+    set_asset_info_metadata,
     delete_asset_info_by_id,
     set_asset_info_preview,
     bulk_insert_asset_infos_ignore_conflicts,
@@ -196,7 +196,7 @@ class TestFetchAssetInfoAndAsset:
         assert ret_asset.id == asset.id
 
 
-class TestTouchAssetInfoById:
+class TestUpdateAssetInfoAccessTime:
     def test_updates_last_access_time(self, session: Session):
         asset = _make_asset(session, "hash1")
         info = _make_asset_info(session, asset)
@@ -206,7 +206,7 @@ class TestTouchAssetInfoById:
         import time
         time.sleep(0.01)
 
-        touch_asset_info_by_id(session, asset_info_id=info.id)
+        update_asset_info_access_time(session, asset_info_id=info.id)
         session.commit()
 
         session.refresh(info)
@@ -355,13 +355,13 @@ class TestUpdateAssetInfoTimestamps:
         assert info.preview_id == preview_asset.id
 
 
-class TestReplaceAssetInfoMetadataProjection:
+class TestSetAssetInfoMetadata:
     def test_sets_metadata(self, session: Session):
         asset = _make_asset(session, "hash1")
         info = _make_asset_info(session, asset)
         session.commit()
 
-        replace_asset_info_metadata_projection(
+        set_asset_info_metadata(
             session, asset_info_id=info.id, user_metadata={"key": "value"}
         )
         session.commit()
@@ -379,12 +379,12 @@ class TestReplaceAssetInfoMetadataProjection:
         info = _make_asset_info(session, asset)
         session.commit()
 
-        replace_asset_info_metadata_projection(
+        set_asset_info_metadata(
             session, asset_info_id=info.id, user_metadata={"old": "data"}
         )
         session.commit()
 
-        replace_asset_info_metadata_projection(
+        set_asset_info_metadata(
             session, asset_info_id=info.id, user_metadata={"new": "data"}
         )
         session.commit()
@@ -398,12 +398,12 @@ class TestReplaceAssetInfoMetadataProjection:
         info = _make_asset_info(session, asset)
         session.commit()
 
-        replace_asset_info_metadata_projection(
+        set_asset_info_metadata(
             session, asset_info_id=info.id, user_metadata={"key": "value"}
         )
         session.commit()
 
-        replace_asset_info_metadata_projection(
+        set_asset_info_metadata(
             session, asset_info_id=info.id, user_metadata={}
         )
         session.commit()
@@ -415,7 +415,7 @@ class TestReplaceAssetInfoMetadataProjection:
 
     def test_raises_for_nonexistent(self, session: Session):
         with pytest.raises(ValueError, match="not found"):
-            replace_asset_info_metadata_projection(
+            set_asset_info_metadata(
                 session, asset_info_id="nonexistent", user_metadata={"key": "value"}
             )
 

tests-unit/assets_test/queries/test_cache_state.py

@@ -15,7 +15,7 @@ from app.assets.database.queries import (
     bulk_insert_cache_states_ignore_conflicts,
     get_cache_states_by_paths_and_asset_ids,
 )
-from app.assets.helpers import pick_best_live_path, get_utc_now
+from app.assets.helpers import select_best_live_path, get_utc_now
 
 
 def _make_asset(session: Session, hash_val: str | None = None, size: int = 1024) -> Asset:
@@ -71,9 +71,9 @@ class TestListCacheStatesByAssetId:
         assert paths == ["/path/asset1.bin"]
 
 
-class TestPickBestLivePath:
+class TestSelectBestLivePath:
     def test_returns_empty_for_empty_list(self):
-        result = pick_best_live_path([])
+        result = select_best_live_path([])
         assert result == ""
 
     def test_returns_empty_when_no_files_exist(self, session: Session):
@@ -81,7 +81,7 @@ class TestPickBestLivePath:
         state = _make_cache_state(session, asset, "/nonexistent/path.bin")
         session.commit()
 
-        result = pick_best_live_path([state])
+        result = select_best_live_path([state])
         assert result == ""
 
     def test_prefers_verified_path(self, session: Session, tmp_path):
@@ -103,7 +103,7 @@ class TestPickBestLivePath:
         session.commit()
 
         states = [state_unverified, state_verified]
-        result = pick_best_live_path(states)
+        result = select_best_live_path(states)
         assert result == str(verified_file)
 
     def test_falls_back_to_existing_unverified(self, session: Session, tmp_path):
@@ -116,11 +116,11 @@ class TestPickBestLivePath:
         state = _make_cache_state(session, asset, str(existing_file), needs_verify=True)
         session.commit()
 
-        result = pick_best_live_path([state])
+        result = select_best_live_path([state])
         assert result == str(existing_file)
 
 
-class TestPickBestLivePathWithMocking:
+class TestSelectBestLivePathWithMocking:
     def test_handles_missing_file_path_attr(self):
         """Gracefully handle states with None file_path."""
 
@@ -128,7 +128,7 @@ class TestPickBestLivePathWithMocking:
             file_path = None
             needs_verify = False
 
-        result = pick_best_live_path([MockState()])
+        result = select_best_live_path([MockState()])
         assert result == ""
 
 

tests-unit/assets_test/queries/test_metadata.py

@@ -3,7 +3,7 @@ from sqlalchemy.orm import Session
 
 from app.assets.database.models import Asset, AssetInfo, AssetInfoMeta
 from app.assets.database.queries import list_asset_infos_page
-from app.assets.database.queries.asset_info import expand_metadata_to_rows
+from app.assets.database.queries.asset_info import convert_metadata_to_rows
 from app.assets.helpers import get_utc_now
 
 
@@ -35,7 +35,7 @@ def _make_asset_info(
 
     if metadata:
         for key, val in metadata.items():
-            for row in expand_metadata_to_rows(key, val):
+            for row in convert_metadata_to_rows(key, val):
                 meta_row = AssetInfoMeta(
                     asset_info_id=info.id,
                     key=row["key"],