prefect-client 3.7.5.dev6__tar.gz → 3.7.6__tar.gz

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.7.5.dev6
+Version: 3.7.6
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/src/prefect/AGENTS.md

@@ -34,6 +34,7 @@ There is no formal public/private boundary beyond the `_` prefix convention. Mod
 - **`ResultRecordMetadata` tolerates unknown serializer types.** When loading persisted metadata, an unrecognized serializer `type` is converted to an `UnknownSerializer` placeholder rather than raising `ValidationError`. This allows inspecting result metadata when the serializer implementation is unavailable in the current environment. However, known serializer types with invalid fields still raise `ValidationError`. `UnknownSerializer.dumps()` and `UnknownSerializer.loads()` raise `RuntimeError` — the tolerance is for inspection only, not actual serialization/deserialization.
 - **`ResultRecord` must be marked persisted after every storage write.** `ResultStore` calls `mark_persisted()` on every record it writes; `to_state_create` in `states.py` consults `is_persisted` as a fallback when `should_persist_result()` returns `False` (e.g., after run context teardown). Any new sync or async persist path that omits `mark_persisted()` will silently drop state metadata for already-written results.
 - **Flow-run suspension is enforced at orchestration boundaries.** Suspension is delivered via `FlowRunSuspensionRequest` and raised with `raise_if_flow_run_suspension_requested()`. When changing engines, futures, task runners, or generator execution, check before returning control to flow user code or proposing a flow state that could leave `Suspended`; keep sync/async paths aligned and avoid per-boundary API reads.
+- **Subflow tracking tasks use UUID dynamic keys when called from within a submitted task.** `flow_engine.py` marks the synthetic tracking `Task` with `_is_subflow_tracking_task=True`; `tasks.py` checks this flag to assign UUID-based (unstable) `dynamic_key` values when the tracking task runs inside a submitted task context. This prevents key collisions between concurrent sibling subflows on parent-flow retry. Direct subflow calls (no enclosing task context) keep stable sequential keys to preserve the retry optimization that reuses completed subflow results.
 
 ## Logging
 

prefect_client-3.7.6/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.7.6"
+__build_date__ = "2026-06-25 23:04:17.505752+00:00"
+__git_commit__ = "7d0d48467f5fc83fe91c22a5722078d4b1fd96a2"
+__dirty__ = False

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/src/prefect/flow_engine.py

@@ -972,6 +972,7 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
             parent_task = Task(
                 name=self.flow.name, fn=self.flow.fn, version=self.flow.version
             )
+            setattr(parent_task, "_is_subflow_tracking_task", True)
 
             parent_task_run = run_coro_as_sync(
                 parent_task.create_run(
@@ -1667,6 +1668,7 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
             parent_task = Task(
                 name=self.flow.name, fn=self.flow.fn, version=self.flow.version
             )
+            setattr(parent_task, "_is_subflow_tracking_task", True)
 
             parent_task_run = await parent_task.create_run(
                 flow_run_context=flow_run_ctx,

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/src/prefect/server/api/server.py

@@ -52,6 +52,7 @@ import prefect.settings
 from prefect._internal.compatibility.starlette import status
 from prefect._internal.observability import configure_logfire
 from prefect.client.constants import SERVER_API_VERSION
+from prefect.locking._filelock import FileLock
 from prefect.logging import get_logger
 from prefect.server.api._ui_static import UIBundle, UIVersion, log_ui_static_copy_error
 from prefect.server.api.background_workers import background_worker
@@ -739,8 +740,20 @@ def create_ui_app(ephemeral: bool) -> FastAPI:
                 continue
 
             if not reference_file_matches_cache_key(bundle):
+                lock_path = os.path.join(
+                    os.path.dirname(bundle.static_dir),
+                    f".{bundle.version}_ui_static.lock",
+                )
+                lock = FileLock(lock_path, timeout=90)
                 try:
-                    create_ui_static_subpath(bundle)
+                    lock.acquire()
+                    try:
+                        # Re-check after acquiring the lock; another worker
+                        # may have completed the copy while we waited.
+                        if not reference_file_matches_cache_key(bundle):
+                            create_ui_static_subpath(bundle)
+                    finally:
+                        lock.release()
                 except OSError as exc:
                     log_ui_static_copy_error(bundle, exc, logger)
                     continue
@@ -843,6 +856,22 @@ def _memoize_block_auto_registration(
     return wrapper
 
 
+def _log_worker_channel_config() -> None:
+    """Log worker channel queue backend and key configuration at startup."""
+    wc_settings = prefect.settings.get_current_settings().server.worker_channel
+    logger.debug(
+        "Worker channel configuration: "
+        "cleanup_queue_storage=%s "
+        "cleanup_lease_seconds=%s "
+        "cleanup_max_delivery_attempts=%s "
+        "cleanup_completed_idempotency_retention_seconds=%s",
+        wc_settings.cleanup_queue_storage,
+        wc_settings.cleanup_lease_seconds,
+        wc_settings.cleanup_max_delivery_attempts,
+        wc_settings.cleanup_completed_idempotency_retention_seconds,
+    )
+
+
 def create_app(
     settings: Optional[prefect.settings.Settings] = None,
     ephemeral: bool = False,
@@ -912,6 +941,8 @@ def create_app(
         await run_migrations()
         await add_block_types()
 
+        _log_worker_channel_config()
+
         Services: type[Service] | None = (
             RunInWebservers
             if webserver_only

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/src/prefect/server/api/workers.py

@@ -409,6 +409,15 @@ async def _build_worker_ready_frame(
         if capability not in accepted_set
     ]
 
+    if rejected:
+        logger.debug(
+            "Worker channel capabilities rejected: "
+            "work_pool=%s worker_name=%s rejected=%s",
+            work_pool_name,
+            hello.payload.worker_name,
+            rejected,
+        )
+
     return (
         WorkerReadyFrame(
             type="worker.ready.v1",
@@ -1154,17 +1163,41 @@ async def worker_channel_connect(
             await connection.run(ready, consumer_kwargs)
 
     except WorkerChannelSetupError as exc:
-        logger.info("Worker channel setup failed: %s", exc.detail)
+        logger.debug(
+            "Worker channel setup failed: work_pool=%s reason=%s detail=%s",
+            work_pool_name,
+            exc.close_reason.value,
+            exc.detail,
+        )
+        if worker_channel_utils.WORKER_CHANNEL_CONNECTIONS is not None:
+            worker_channel_utils.WORKER_CHANNEL_CONNECTIONS.labels(
+                event="setup_failed"
+            ).inc()
         await worker_channel_utils.close_worker_channel(websocket, exc.close_reason)
     except HTTPException as exc:
-        logger.info("Worker channel setup failed HTTP validation: %s", exc.detail)
+        logger.debug(
+            "Worker channel setup failed HTTP validation: work_pool=%s detail=%s",
+            work_pool_name,
+            exc.detail,
+        )
+        if worker_channel_utils.WORKER_CHANNEL_CONNECTIONS is not None:
+            worker_channel_utils.WORKER_CHANNEL_CONNECTIONS.labels(
+                event="setup_failed"
+            ).inc()
         await worker_channel_utils.close_worker_channel(
             websocket, WorkerChannelCloseReason.PROTOCOL_ERROR
         )
     except subscriptions.NORMAL_DISCONNECT_EXCEPTIONS:
         return
     except Exception:
-        logger.exception("Worker channel setup failed due to a transient server error")
+        logger.exception(
+            "Worker channel setup failed due to a transient server error: work_pool=%s",
+            work_pool_name,
+        )
+        if worker_channel_utils.WORKER_CHANNEL_CONNECTIONS is not None:
+            worker_channel_utils.WORKER_CHANNEL_CONNECTIONS.labels(
+                event="setup_failed"
+            ).inc()
         await worker_channel_utils.close_worker_channel(
             websocket, WorkerChannelCloseReason.TRANSIENT_SERVER_ERROR
         )

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/src/prefect/task_engine.py

@@ -299,6 +299,8 @@ class BaseTaskRunEngine(Generic[P, R]):
     def _resolve_parameters(self):
         if not self.parameters:
             return None
+        if getattr(self, "_parameters_resolved", False):
+            return None
 
         resolved_parameters = {}
         for parameter, value in self.parameters.items():
@@ -311,7 +313,7 @@ class BaseTaskRunEngine(Generic[P, R]):
                     remove_annotations=True,
                     context={"parameter_name": parameter},
                 )
-            except UpstreamTaskError:
+            except (UpstreamTaskError, PrefectException):
                 raise
             except Exception as exc:
                 raise PrefectException(
@@ -322,6 +324,7 @@ class BaseTaskRunEngine(Generic[P, R]):
                 ) from exc
 
         self.parameters = resolved_parameters
+        self._parameters_resolved = True
 
     def _set_custom_task_run_name(self):
         from prefect._internal.engine import resolve_custom_task_run_name

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/src/prefect/tasks.py

@@ -900,6 +900,19 @@ class Task(Generic[P, R]):
             if not flow_run_context:
                 dynamic_key = f"{self.task_key}-{str(uuid4().hex)}"
                 task_run_name = self.name
+            elif (
+                getattr(self, "_is_subflow_tracking_task", False)
+                and parent_task_run_context
+                and flow_run_context.flow_run
+                and parent_task_run_context.task_run.flow_run_id
+                == flow_run_context.flow_run.id
+            ):
+                # Subflows called from a task context need UUID keys because
+                # sibling call order is not a reliable identity across retries.
+                dynamic_key = dynamic_key_for_task_run(
+                    context=flow_run_context, task=self, stable=False
+                )
+                task_run_name = f"{self.name}-{dynamic_key}"
             else:
                 dynamic_key = dynamic_key_for_task_run(
                     context=flow_run_context, task=self
@@ -1620,10 +1633,10 @@ class Task(Generic[P, R]):
 
         if deferred:
             parameters_list = expand_mapping_parameters(self.fn, parameters)
-            futures = [
+            futures = PrefectFutureList(
                 self.apply_async(kwargs=parameters, wait_for=wait_for)
                 for parameters in parameters_list
-            ]
+            )
         elif task_runner := getattr(flow_run_context, "task_runner", None):
             assert isinstance(task_runner, TaskRunner)
             futures = task_runner.map(self, parameters, wait_for)

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/src/prefect/utilities/asyncutils/__init__.py

@@ -8,7 +8,7 @@ import threading
 import warnings
 from collections.abc import AsyncGenerator, Awaitable, Coroutine
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
-from contextvars import ContextVar
+from contextvars import Context, ContextVar
 from functools import partial, wraps
 from logging import Logger
 from typing import TYPE_CHECKING, Any, Callable, NoReturn, Optional, Union, overload
@@ -474,6 +474,10 @@ class GatherTaskGroup(anyio.abc.TaskGroup):
         # The concrete task group implementation to use
         self._task_group: anyio.abc.TaskGroup = task_group
 
+    @property
+    def cancel_scope(self) -> Any:
+        return self._task_group.cancel_scope
+
     async def _run_and_store(
         self,
         key: UUID,
@@ -494,6 +498,20 @@ class GatherTaskGroup(anyio.abc.TaskGroup):
         self._task_group.start_soon(self._run_and_store, key, func, *args, name=name)
         return key
 
+    def create_task(
+        self,
+        coro: Coroutine[Any, Any, T],
+        *,
+        name: object = None,
+        context: Context | None = None,
+    ) -> Any:
+        create_task = getattr(self._task_group, "create_task", None)
+        if create_task is None:
+            coro.close()
+            raise RuntimeError("`create_task` requires AnyIO 4.14.0 or newer.")
+
+        return create_task(coro, name=name, context=context)
+
     async def start(self, func: object, *args: object, name: object = None) -> NoReturn:
         """
         Since `start` returns the result of `task_status.started()` but here we must

{prefect_client-3.7.5.dev6 → prefect_client-3.7.6}/src/prefect/utilities/engine/__init__.py

@@ -28,6 +28,7 @@ import prefect.exceptions
 from prefect._internal.concurrency.cancellation import get_deadline
 from prefect.client.schemas import FlowRunResult, OrchestrationResult, TaskRun
 from prefect.client.schemas.objects import (
+    FlowRun,
     RunType,
     TaskRunResult,
 )
@@ -52,7 +53,7 @@ from prefect.results import ResultRecord, should_persist_result
 from prefect.settings import PREFECT_LOGGING_LOG_PRINTS
 from prefect.states import State
 from prefect.tasks import Task
-from prefect.utilities.annotations import allow_failure, quote
+from prefect.utilities.annotations import allow_failure, opaque, quote
 from prefect.utilities.collections import StopVisiting, visit_collection
 from prefect.utilities.text import truncated_to
 
@@ -61,7 +62,34 @@ if TYPE_CHECKING:
 
 API_HEALTHCHECKS: dict[str, float] = {}
 UNTRACKABLE_TYPES: set[type[Any]] = {bool, type(None), type(...), type(NotImplemented)}
+_RUN_SCHEMA_TYPES: tuple[type[Any], ...] = (FlowRun, TaskRun)
 engine_logger: Logger = get_logger("engine")
+
+
+def _raise_on_run_schema_unless_opaque(obj: Any, context: dict[str, Any]) -> None:
+    """Raise a clear error when a Prefect run schema object is passed as a
+    task argument without the `opaque` annotation.
+
+    These Pydantic models contain a `.state` attribute that
+    `visit_collection` would recurse into, causing the embedded state
+    to be mistakenly treated as an upstream task dependency.
+    """
+    if isinstance(obj, _RUN_SCHEMA_TYPES) and not isinstance(
+        context.get("annotation"), opaque
+    ):
+        type_name = type(obj).__name__
+        lower = type_name[0].lower() + type_name[1:]
+        raise PrefectException(
+            f"Passing a `{type_name}` object as a task argument is not supported."
+            " Prefect inspects task arguments for upstream `State` and"
+            " `PrefectFuture` dependencies, which causes the embedded"
+            f" `{type_name}.state` attribute to be mistakenly treated as an"
+            " upstream task dependency. Pass individual fields instead"
+            f" (e.g. `{lower}.id`) or wrap the object with"
+            f" `opaque({lower})` to skip dependency traversal."
+        )
+
+
 T = TypeVar("T")
 _prefect_sigterm_handler_depth = 0
 _prefect_sigterm_bridge_lock = threading.RLock()
@@ -379,6 +407,8 @@ async def resolve_inputs(
         if isinstance(context.get("annotation"), quote):
             raise StopVisiting()
 
+        _raise_on_run_schema_unless_opaque(expr, context)
+
         if isinstance(expr, PrefectFuture):
             fut: PrefectFuture[Any] = expr
             futures.add(fut)
@@ -415,6 +445,8 @@ async def resolve_inputs(
         if isinstance(context.get("annotation"), quote):
             raise StopVisiting()
 
+        _raise_on_run_schema_unless_opaque(expr, context)
+
         if isinstance(expr, PrefectFuture):
             state = expr.state
         elif isinstance(expr, State):
@@ -446,7 +478,9 @@ async def resolve_inputs(
         ):
             return state.data
 
-        return result_by_state.get(state)
+        resolved = result_by_state.get(state)
+        _raise_on_run_schema_unless_opaque(resolved, context)
+        return resolved
 
     resolved_parameters: dict[str, Any] = {}
     for parameter, value in parameters.items():
@@ -460,7 +494,7 @@ async def resolve_inputs(
                 remove_annotations=True,
                 context={},
             )
-        except UpstreamTaskError:
+        except (UpstreamTaskError, PrefectException):
             raise
         except Exception as exc:
             raise PrefectException(
@@ -951,6 +985,8 @@ def resolve_to_final_result(expr: Any, context: dict[str, Any]) -> Any:
     if isinstance(context.get("annotation"), quote):
         raise StopVisiting()
 
+    _raise_on_run_schema_unless_opaque(expr, context)
+
     if isinstance(expr, PrefectFuture):
         upstream_task_run: Optional[TaskRun] = context.get("current_task_run")
         upstream_task: Optional["Task[..., Any]"] = context.get("current_task")
@@ -996,6 +1032,11 @@ def resolve_to_final_result(expr: Any, context: dict[str, Any]) -> Any:
 
     result: Any = state.result(raise_on_failure=False, _sync=True)  # pyright: ignore[reportCallIssue] _sync messes up type inference and can be removed once async_dispatch is removed
 
+    # Check the resolved result: if a task returned a FlowRun/TaskRun, the
+    # caller (visit_collection) would recurse into its Pydantic fields and
+    # misinterpret the embedded .state as an upstream dependency.
+    _raise_on_run_schema_unless_opaque(result, context)
+
     if state.state_details.traceparent:
         parameter_context = propagate.extract(
             {"traceparent": state.state_details.traceparent}
@@ -1046,7 +1087,7 @@ def resolve_inputs_sync(
                 remove_annotations=True,
                 context={"parameter_name": parameter},
             )
-        except UpstreamTaskError:
+        except (UpstreamTaskError, PrefectException):
             raise
         except Exception as exc:
             raise PrefectException(

prefect_client-3.7.5.dev6/src/prefect/_build_info.py

@@ -1,5 +0,0 @@
-# Generated by versioningit
-__version__ = "3.7.5.dev6"
-__build_date__ = "2026-06-18 09:37:15.430042+00:00"
-__git_commit__ = "8f50275cba223bd11612305716bb48581a1cfb91"
-__dirty__ = False