Delete HF storage by explicit file commit; allow remote-only player delete

Player/session deletes left the folder behind on the private HF dataset.
delete_folder can fail to resolve a prefix on a Xet-backed dataset, so the
remote folder survived while the local copy was already removed (hence the app
showed it gone after refresh but HF still had it).

- _delete_folder_from_hf now lists the actual files under the path and deletes
them explicitly via create_commit(CommitOperationDelete...), then confirms by
re-listing. Success is judged purely by the end state (nothing remaining).
- delete_player now checks the remote up front: if the local copy is already
gone but the player still exists on HF, it still deletes the remote folder
instead of 404-ing and orphaning it. Only "absent locally AND remotely" 404s.

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

api.py

@@ -19,7 +19,7 @@ from fastapi.concurrency import run_in_threadpool
 from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 from typing import List
-from huggingface_hub import hf_hub_download, snapshot_download, HfApi
+from huggingface_hub import hf_hub_download, snapshot_download, HfApi, CommitOperationDelete
 
 app = FastAPI(title="Sporalize Labs 3D Analysis Engine")
 
@@ -159,65 +159,74 @@ def push_session_to_hf(player_id: str, session_id: str, session_dir: str):
     )
 
 
-def _hf_path_exists(api, path_in_repo: str) -> bool:
-    """True if any tracked file remains under path_in_repo on the remote."""
+def _hf_files_under(api, path_in_repo: str):
+    """All tracked files at or under path_in_repo on the remote (fresh listing)."""
     prefix = path_in_repo.strip("/") + "/"
-    try:
-        files = api.list_repo_files(
-            repo_id=STORAGE_DATASET_REPO_ID,
-            repo_type=STORAGE_DATASET_REPO_TYPE,
-            token=get_hf_token(),
-        )
-    except Exception as error:
-        # If we cannot even list the repo, we cannot confirm the delete.
-        raise error
-    return any(f == path_in_repo or f.startswith(prefix) for f in files)
+    files = api.list_repo_files(
+        repo_id=STORAGE_DATASET_REPO_ID,
+        repo_type=STORAGE_DATASET_REPO_TYPE,
+        revision="main",
+        token=get_hf_token(),
+    )
+    return [f for f in files if f == path_in_repo or f.startswith(prefix)]
 
 
 def _delete_folder_from_hf(path_in_repo: str, commit_message: str):
-    """Delete a folder from the HF storage dataset.
+    """Delete everything under path_in_repo from the HF storage dataset.
 
-    Returns (deleted, error_message). Correctness is judged by the *end state*:
-    if nothing remains under the path on the remote, the delete succeeded —
-    regardless of whether delete_folder raised (e.g. it raises when the folder
-    is already absent, or on a benign race). Only a path that still exists after
-    the attempt, or an inability to confirm, is reported as a failure.
+    Instead of relying on delete_folder (which can mis-resolve a prefix on a
+    Xet-backed dataset and leave the folder behind), we list the actual files
+    under the path and delete them explicitly in one commit. Success is judged
+    by the end state: nothing remaining under the path. Returns (deleted, error).
     """
     if not hf_storage_enabled():
         return True, None
 
     api = HfApi(token=get_hf_token())
 
-    # Fast path: nothing there to begin with.
     try:
-        if not _hf_path_exists(api, path_in_repo):
-            return True, None
-    except Exception:
-        pass  # fall through to attempt the delete and re-check
+        targets = _hf_files_under(api, path_in_repo)
+    except Exception as error:
+        message = str(error)
+        print(f"[SPORALIZE] HF delete: could not list '{path_in_repo}': {message}", flush=True)
+        return False, message
 
-    delete_error = None
+    if not targets:
+        # Already gone on the remote — desired end state.
+        return True, None
+
+    operations = [CommitOperationDelete(path_in_repo=f) for f in targets]
     try:
-        api.delete_folder(
+        api.create_commit(
             repo_id=STORAGE_DATASET_REPO_ID,
             repo_type=STORAGE_DATASET_REPO_TYPE,
-            path_in_repo=path_in_repo,
+            operations=operations,
             commit_message=commit_message,
+            token=get_hf_token(),
         )
     except Exception as error:
-        delete_error = error
+        delete_error = str(error)
+        print(f"[SPORALIZE] HF delete commit failed for '{path_in_repo}' ({len(targets)} files): {delete_error}", flush=True)
+        # Confirm by end state anyway — a benign race may still have removed it.
+        try:
+            if not _hf_files_under(api, path_in_repo):
+                return True, None
+        except Exception:
+            pass
+        return False, delete_error
 
-    # Confirm by the actual end state rather than the raised exception.
+    # Confirm the files are actually gone.
     try:
-        if not _hf_path_exists(api, path_in_repo):
-            return True, None
-    except Exception as confirm_error:
-        message = str(delete_error or confirm_error)
-        print(f"[SPORALIZE] HF delete could not be confirmed for '{path_in_repo}': {message}", flush=True)
+        remaining = _hf_files_under(api, path_in_repo)
+    except Exception:
+        remaining = []
+    if remaining:
+        message = f"{len(remaining)} file(s) still present under '{path_in_repo}' after delete"
+        print(f"[SPORALIZE] HF delete incomplete: {message}", flush=True)
         return False, message
 
-    message = str(delete_error) if delete_error else "folder still present on remote after delete"
-    print(f"[SPORALIZE] HF delete failed for '{path_in_repo}': {message}", flush=True)
-    return False, message
+    print(f"[SPORALIZE] HF delete ok: removed {len(targets)} file(s) under '{path_in_repo}'", flush=True)
+    return True, None
 
 
 def delete_session_from_hf(player_id: str, session_id: str):
@@ -1209,10 +1218,26 @@ def delete_session(session_id: str):
 @app.delete("/api/players/{player_id}")
 def delete_player(player_id: str):
     player_dir = player_storage_path(player_id)
-    if not os.path.isdir(player_dir):
+    local_exists = os.path.isdir(player_dir)
+
+    # Check the remote up front so we can tell "nothing anywhere" (real 404)
+    # apart from "still on the remote" (must be deleted even if local is gone).
+    remote_path = hf_storage_path(safe_name(player_id))
+    remote_exists = False
+    if hf_storage_enabled():
+        try:
+            remote_exists = bool(_hf_files_under(HfApi(token=get_hf_token()), remote_path))
+        except Exception:
+            remote_exists = False
+
+    if not local_exists and not remote_exists:
         raise HTTPException(status_code=404, detail="Player storage not found")
 
-    shutil.rmtree(player_dir, ignore_errors=True)
+    if local_exists:
+        shutil.rmtree(player_dir, ignore_errors=True)
+
+    # Always mirror to the remote (even when the local copy was already gone but
+    # a previous remote delete failed, leaving an orphaned HF folder).
     hf_deleted, hf_error = delete_player_from_hf(player_id)
     if hf_storage_enabled() and not hf_deleted:
         raise HTTPException(