[adapter] refactor: tidy _resolve_checkpoint_path call sites (#161)

* [adapter] refactor: hoist os.path.expanduser into _resolve_checkpoint_path

Move the `path = os.path.expanduser(path)` call out of `load_checkpoint`
and into `_resolve_checkpoint_path` itself. The resolver is now the
single entry point that takes a raw user-provided spec and returns a
usable local directory; callers no longer need to remember to normalize
`~` separately.

Safe in all three input branches:
- Local path with `~`: expanded correctly (unchanged behavior).
- Local path without `~`: no-op.
- HF spec ('owner/repo' or 'hf://...'): no-op since `expanduser`
  only acts on a leading `~`.

Co-authored-by: Cursor <cursoragent@cursor.com>

* [adapter] refactor: drop dead exists-check; collapse `spec` local

Two small cleanups in the HF-checkpoint resolve path, both follow-ups
to the un-gating change:

A. Remove the dead `if not os.path.exists(path)` guard in
   `load_checkpoint`. `_resolve_checkpoint_path` now either:
     - returns a path it has just confirmed via `os.path.exists`, or
     - returns a downloaded path that `download_hf_checkpoint` has
       verified with `os.path.isdir`, or
     - raises `FileNotFoundError` with the actual root cause.
   The guard was useful pre-ungating (the old post-barrier
   `snapshot_download` call could return a non-existent path on
   cache-miss-after-failure); now it's unreachable AND its error
   message would lie about the failure mode.

B. Collapse the redundant `spec` local in `_resolve_checkpoint_path`.
   `parse_hf_checkpoint_path` already strips the `hf://` prefix
   internally, and the local-path `os.path.exists` check is gated on
   `not force_hf` so passing `path` (with the prefix still attached on
   the HF branch) is safe. Removes one variable from the reader's
   mental model.

Pure refactor: no behavior change. The 8 happy-path + 5 original-error
+ 6 path-traversal parser cases all still pass.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Jayce-Ping

src/flow_factory/models/abc.py

@@ -1491,13 +1491,17 @@ def _resolve_checkpoint_path(self, path: str) -> str:
         Raises:
             FileNotFoundError: When the spec is neither a local path nor a reachable HF repo.
         """
+        # Normalize leading ``~`` for local-path inputs; no-op for HF specs since
+        # ``expanduser`` only acts on a leading ``~``.
+        path = os.path.expanduser(path)
         force_hf = path.startswith(HF_PATH_PREFIX)
-        spec = path[len(HF_PATH_PREFIX):] if force_hf else path
 
-        if not force_hf and os.path.exists(spec):
-            return spec
+        # Local path wins unless an explicit ``hf://`` prefix forces remote.
+        if not force_hf and os.path.exists(path):
+            return path
 
-        repo_id, subfolder, revision = parse_hf_checkpoint_path(spec)
+        # ``parse_hf_checkpoint_path`` handles the ``hf://`` prefix internally.
+        repo_id, subfolder, revision = parse_hf_checkpoint_path(path)
 
         try:
             local_path = download_hf_checkpoint(repo_id, subfolder, revision)
@@ -1741,12 +1745,7 @@ def load_checkpoint(
                 - 'state': Load full training state (model + optimizer + scheduler + RNG)
                 - None: Auto-detect based on checkpoint directory contents
         """
-        path = os.path.expanduser(path)
         path = self._resolve_checkpoint_path(path)
-        if not os.path.exists(path):
-            raise FileNotFoundError(
-                f"Checkpoint path not found locally or on Hugging Face Hub: {path!r}"
-            )
 
         # Auto-detect if not specified
         if resume_type is None: