Fix Modal volume hydration helper import

comfyui_modal_sync_cloud.py

@@ -146,6 +146,7 @@ try:  # noqa: E402 - support package and flat Modal-container imports.
     from .cloud_volume_reload import (
         CloudVolumeReloadHooks,
         _emit_modal_volume_reload_skip,
+        _hydrate_missing_payload_volume_paths,
         _modal_volume_reload_marker,
         _reload_modal_volume_for_request,
         _should_reload_modal_volume,
@@ -155,6 +156,7 @@ except ImportError:  # pragma: no cover - exercised by flat cloud imports.
     from cloud_volume_reload import (
         CloudVolumeReloadHooks,
         _emit_modal_volume_reload_skip,
+        _hydrate_missing_payload_volume_paths,
         _modal_volume_reload_marker,
         _reload_modal_volume_for_request,
         _should_reload_modal_volume,

docs/LEARNINGS.md

@@ -1,5 +1,10 @@
 # Learnings
 
+## 2026-08-30: Module compatibility fallback does not populate function globals
+
+- PEP 562 module `__getattr__` preserves callers that read a moved private helper as `module._helper`, but code defined inside that module resolves `_helper` directly from the module globals dictionary and never invokes `__getattr__`. A compatibility-export test can therefore pass while the deployed Modal method raises `NameError`.
+- Stable cloud entrypoints must explicitly import every extracted helper referenced by their own function bodies. Regression tests for such names should inspect `vars(module)` rather than use `hasattr` or `getattr`, because those APIs exercise the compatibility fallback and mask the missing global binding.
+
 ## 2026-08-29: A surviving relay can explain a vanished GPU worker
 
 - OpenSSH writes Vast's generic login greeting to stderr on every successful connection. When a remote stream ends without a terminal frame, that greeting is transport context, not a failure cause, and must never be promoted into the user-facing exception.

tests/test_import_shapes.py

@@ -51,3 +51,14 @@ def test_stable_cloud_entrypoint_exports_host_runtime_surface(
     for exception_name in _CLOUD_EXCEPTION_NAMES:
         exception_type = getattr(cloud_module, exception_name)
         assert exception_type.__module__ == "comfyui_modal_sync_cloud"
+
+
+def test_cloud_entrypoint_eagerly_imports_volume_hydration_helper(
+    extension_package: object,
+) -> None:
+    """Method globals must not depend on the module compatibility fallback."""
+    del extension_package
+    cloud_module = importlib.import_module("comfyui_modal_sync_cloud")
+
+    assert "_hydrate_missing_payload_volume_paths" in vars(cloud_module)
+    assert callable(vars(cloud_module)["_hydrate_missing_payload_volume_paths"])