prefect-client 3.6.27.dev4__tar.gz → 3.6.28__tar.gz

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/.gitignore

@@ -97,3 +97,4 @@ CLAUDE.md
 
 # Local planning artifacts
 .planning/
+repros/

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.6.27.dev4
+Version: 3.6.28
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -40,7 +40,7 @@ Requires-Dist: jsonpatch<2.0,>=1.32
 Requires-Dist: jsonschema<5.0.0,>=4.18.0
 Requires-Dist: opentelemetry-api<2.0.0,>=1.27.0
 Requires-Dist: orjson<4.0,>=3.7
-Requires-Dist: packaging<26.1,>=21.3
+Requires-Dist: packaging<26.2,>=21.3
 Requires-Dist: pathspec>=0.8.0
 Requires-Dist: pendulum<4,>=3.1.0; python_version < '3.13'
 Requires-Dist: prometheus-client>=0.20.0
@@ -53,7 +53,7 @@ Requires-Dist: python-slugify<9.0,>=5.0
 Requires-Dist: pytz<2027,>=2021.1
 Requires-Dist: pyyaml<7.0.0,>=5.4.1
 Requires-Dist: rfc3339-validator<0.2.0,>=0.1.4
-Requires-Dist: rich<15.0,>=11.0
+Requires-Dist: rich<16.0,>=11.0
 Requires-Dist: ruamel-yaml-clib>=0.2.8; platform_python_implementation == 'CPython'
 Requires-Dist: ruamel-yaml>=0.17.0
 Requires-Dist: sniffio<2.0.0,>=1.3.0

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/pyproject.toml

@@ -44,7 +44,7 @@ dependencies = [
     "jsonschema>=4.18.0,<5.0.0",
     "opentelemetry-api>=1.27.0,<2.0.0",
     "orjson>=3.7,<4.0",
-    "packaging>=21.3,<26.1",
+    "packaging>=21.3,<26.2",
     "pathspec>=0.8.0",
     "pendulum>=3.1.0,<4; python_version<'3.13'",
     "prometheus-client>=0.20.0",
@@ -57,7 +57,7 @@ dependencies = [
     "pytz>=2021.1,<2027",
     "pyyaml>=5.4.1,<7.0.0",
     "rfc3339-validator>=0.1.4,<0.2.0",
-    "rich>=11.0,<15.0",
+    "rich>=11.0,<16.0",
     "ruamel.yaml>=0.17.0",
     "ruamel.yaml.clib>=0.2.8; platform_python_implementation == 'CPython'",
     "sniffio>=1.3.0,<2.0.0",

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/AGENTS.md

@@ -21,10 +21,12 @@ There is no formal public/private boundary beyond the `_` prefix convention. Mod
 
 - **Engine ordering matters.** The engines apply features (retries, caching, result persistence, transactions) in a specific order. Changing the order or forgetting a feature in one engine path is the most common source of breakage.
 - **Sync and async must stay in sync.** Both `flow_engine.py` and `task_engine.py` have sync and async paths. Any behavior change must be applied to both.
+- **Use `whenever` compat helpers for all datetime conversions on Python 3.13+.** `types/_datetime.py` provides `_whenever_to_stdlib()`, `_whenever_zdt_from_py()`, and `_whenever_pdt_from_py()` to abstract over API differences between whenever 0.7.x–0.9.x and ≥ 0.10.0. The `_WHENEVER_NEW_API` flag (True when whenever ≥ 0.10.0) guards version-specific code. Never call `ZonedDateTime.from_py_datetime()`, `PlainDateTime.from_py_datetime()`, or `.py_datetime()` directly — use the helpers instead. Violations will silently break on whichever whenever version the helpers weren't written for.
 - **Flow and task engines advance state differently.** The flow engine makes blocking API calls to the server to propose and advance states. The task engine emits `prefect.task_run.*` events (delivered via WebSockets) but advances state locally through `set_state` calls with polling/backoff — do not assume the two engines work the same way.
 - **Flow state transitions go through the server.** The flow engine proposes states to the server, which accepts or rejects them via orchestration rules. The task engine, by contrast, manages state transitions locally via `set_state` and emits `prefect.task_run.*` events — it does not propose states to the server.
 - **`ProcessPoolTaskRunner` requires picklable data across subprocess boundaries.** `PrefectFuture` objects are not picklable and cannot be passed to worker subprocesses. Any `wait_for` futures must be waited on in the parent process and converted to `State` objects before submission. The subprocess task engine handles `State` objects via `resolve_to_final_result`, which raises `UpstreamTaskError` for non-completed upstreams.
 - **`ProcessPoolTaskRunner` instances may be deserialized without `__init__` running.** When a runner is pickled and restored in a subprocess, `__init__` is not called, so instance attributes set there may be absent. Access any such attribute via `getattr(self, "_attr", default)` rather than `self._attr` directly — both in the property getter and in `duplicate()`. The `subprocess_message_processor_factories` property demonstrates the required pattern.
+- **`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.
 
 ## Logging
 

prefect_client-3.6.28/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.28"
+__build_date__ = "2026-04-24 17:09:10.406247+00:00"
+__git_commit__ = "e4d25f0bafb3b7499c2acafdc06fc7c5f8c67c9d"
+__dirty__ = False

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/_experimental/bundles/__init__.py

@@ -23,7 +23,10 @@ from typing_extensions import Literal, NotRequired, TypeAlias
 
 import anyio
 import cloudpickle  # pyright: ignore[reportMissingTypeStubs]
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.version import Version
 
+import prefect
 from prefect._internal.control_listener import configure_from_env
 from prefect.client.schemas.objects import FlowRun
 from prefect.context import SettingsContext, get_settings_context, serialize_context
@@ -36,7 +39,10 @@ from prefect.settings.models.root import Settings
 from prefect.utilities.processutils import sanitize_subprocess_env
 from prefect.utilities.slugify import slugify
 
-from prefect._experimental._launchers import validate_bundle_step_launcher
+from prefect._experimental._launchers import (
+    get_launcher_for_side,
+    validate_bundle_step_launcher,
+)
 
 from .execute import execute_bundle_from_file
 from ._file_collector import FileCollector
@@ -411,38 +417,48 @@ def create_bundle_for_flow_run(
     """
     context = context or serialize_context()
 
-    dependencies = (
-        subprocess.check_output(
-            [
-                _get_uv_path(),
-                "pip",
-                "freeze",
-                # Exclude editable installs because we won't be able to install them in the execution environment
-                "--exclude-editable",
-            ]
+    # Skip `uv pip freeze` when the execution side of the flow's launcher
+    # opts out of uv-based launchers. The `dependencies` field is only
+    # consumed by `execute_bundle_in_subprocess` (which uses `uv pip install`);
+    # custom execution launchers are responsible for their own environment.
+    # Upload-only launcher overrides still use `uv run` at execution time and
+    # therefore still need the dependency snapshot.
+    flow_launcher = getattr(flow, "launcher", None)
+    if get_launcher_for_side(flow_launcher, "execution") is None:
+        dependencies = (
+            subprocess.check_output(
+                [
+                    _get_uv_path(),
+                    "pip",
+                    "freeze",
+                    # Exclude editable installs because we won't be able to install them in the execution environment
+                    "--exclude-editable",
+                ]
+            )
+            .decode()
+            .strip()
         )
-        .decode()
-        .strip()
-    )
 
-    # Remove dependencies installed from a local file path because we won't be able
-    # to install them in the execution environment. The user will be responsible for
-    # making sure they are available in the execution environment
-    filtered_dependencies: list[str] = []
-    file_dependencies: list[str] = []
-    for line in dependencies.split("\n"):
-        if "file://" in line:
-            file_dependencies.append(line)
-        else:
-            filtered_dependencies.append(line)
-    dependencies = "\n".join(filtered_dependencies)
-    if file_dependencies:
-        logger.warning(
-            "The following dependencies were installed from a local file path and will not be "
-            "automatically installed in the execution environment: %s. If these dependencies "
-            "are not available in the execution environment, your flow run may fail.",
-            "\n".join(file_dependencies),
-        )
+        # Remove dependencies installed from a local file path because we won't be able
+        # to install them in the execution environment. The user will be responsible for
+        # making sure they are available in the execution environment
+        filtered_dependencies: list[str] = []
+        file_dependencies: list[str] = []
+        for line in dependencies.split("\n"):
+            if "file://" in line:
+                file_dependencies.append(line)
+            else:
+                filtered_dependencies.append(line)
+        dependencies = "\n".join(filtered_dependencies)
+        if file_dependencies:
+            logger.warning(
+                "The following dependencies were installed from a local file path and will not be "
+                "automatically installed in the execution environment: %s. If these dependencies "
+                "are not available in the execution environment, your flow run may fail.",
+                "\n".join(file_dependencies),
+            )
+    else:
+        dependencies = ""
 
     # Collect and package included files if specified
     files_key: str | None = None
@@ -603,6 +619,52 @@ def execute_bundle_in_subprocess(
     return process
 
 
+def _pin_prefect_in_bundle_step_requires(requires: list[str]) -> list[str]:
+    """
+    Ensure the `uv run --with` requirements for an outer bundle-step process
+    include the exact current publishable Prefect version.
+
+    The outer bundle-step process imports Prefect before the bundle's frozen
+    dependencies are installed, so transitive constraints like
+    `prefect>=3.6.24` from integration packages can otherwise resolve an
+    older stable Prefect even when the bundle was built against a newer
+    version. Pinning `prefect=={prefect.__version__}` keeps the outer
+    process on the same version the bundle was built with.
+
+    - Rewrites any existing `prefect` (or `prefect[...]`) requirement to the
+      exact current version, preserving extras and markers.
+    - Appends `prefect=={prefect.__version__}` if no Prefect requirement is
+      present.
+    - Returns the requirements unchanged for local/unpublishable versions,
+      matching the behavior of `prefect._internal.installation`.
+    """
+    version = Version(prefect.__version__)
+    if version.local:
+        return requires
+
+    pinned_version = prefect.__version__
+    updated: list[str] = []
+    found_prefect = False
+    for requirement in requires:
+        try:
+            parsed = Requirement(requirement)
+        except InvalidRequirement:
+            updated.append(requirement)
+            continue
+        if parsed.name.lower() != "prefect":
+            updated.append(requirement)
+            continue
+        found_prefect = True
+        extras = f"[{','.join(sorted(parsed.extras))}]" if parsed.extras else ""
+        marker = f" ; {parsed.marker}" if parsed.marker else ""
+        updated.append(f"prefect{extras}=={pinned_version}{marker}")
+
+    if not found_prefect:
+        updated.append(f"prefect=={pinned_version}")
+
+    return updated
+
+
 def convert_step_to_command(
     step: dict[str, Any], key: str, quiet: bool = False
 ) -> list[str]:
@@ -642,6 +704,13 @@ def convert_step_to_command(
         if quiet:
             command.append("--quiet")
 
+        # Pin the outer bundle-step process to the current publishable Prefect
+        # version so integration `requires` like `prefect-aws>=0.5.5` cannot
+        # resolve an older stable Prefect via transitive `prefect>=...`
+        # constraints before the bundle's frozen dependencies are applied.
+        if requires:
+            requires = _pin_prefect_in_bundle_step_requires(requires)
+
         # Add the `--with` argument to handle dependencies for running the step
         if requires:
             command.extend(["--with", ",".join(requires)])

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/_experimental/bundles/execute.py

@@ -39,6 +39,7 @@ async def execute_bundle(bundle: dict) -> None:
                 control_channel=ctx.control_channel,
             ),
             resolve_flow=resolve_flow,
+            propose_submitting=False,
         )
         await executor.submit()
 

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/_internal/compatibility/deprecated.py

@@ -91,8 +91,14 @@ def generate_deprecation_message(
         if sys.version_info >= (3, 13):
             from whenever import PlainDateTime
 
+            _pdt_from_dt = (
+                PlainDateTime
+                if hasattr(PlainDateTime, "to_stdlib")
+                else PlainDateTime.from_py_datetime
+            )
+            _dt = _pdt_from_dt(start_date).add(months=6)
             end_date = (
-                PlainDateTime.from_py_datetime(start_date).add(months=6).py_datetime()
+                _dt.to_stdlib() if hasattr(_dt, "to_stdlib") else _dt.py_datetime()
             )
         else:
             import pendulum

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/_internal/pydantic/v2_schema.py

@@ -5,6 +5,7 @@ import typing as t
 import pydantic
 from pydantic import BaseModel as V2BaseModel
 from pydantic import ConfigDict, PydanticUndefinedAnnotation, create_model
+from pydantic.errors import PydanticUserError
 from pydantic.fields import FieldInfo
 from pydantic.type_adapter import TypeAdapter
 
@@ -115,11 +116,19 @@ def create_v2_schema(
         raise TypeError(exc.message)
 
     # root model references under #definitions
-    schema = adapter.json_schema(
-        by_alias=True,
-        ref_template="#/definitions/{model}",
-        schema_generator=GenerateEmptySchemaForUserClasses,
-    )
+    try:
+        schema = adapter.json_schema(
+            by_alias=True,
+            ref_template="#/definitions/{model}",
+            schema_generator=GenerateEmptySchemaForUserClasses,
+        )
+    except PydanticUserError as exc:
+        # In Pydantic >=2.13, unresolved forward references defer the error
+        # until the schema is built. Surface these as TypeError, matching the
+        # behavior parameter_schema expects for invalid parameter types.
+        if exc.code == "class-not-fully-defined":
+            raise TypeError(str(exc))
+        raise
     # ensure backwards compatibility by copying $defs into definitions
     if "$defs" in schema:
         schema["definitions"] = schema["$defs"]

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/_result_records.py

@@ -17,6 +17,7 @@ from pydantic import (
     BaseModel,
     Field,
     ValidationError,
+    field_validator,
     model_validator,
 )
 
@@ -24,8 +25,9 @@ import prefect
 from prefect.exceptions import (
     SerializationError,
 )
-from prefect.serializers import PickleSerializer, Serializer
+from prefect.serializers import PickleSerializer, Serializer, UnknownSerializer
 from prefect.types import DateTime
+from prefect.utilities.dispatch import lookup_type
 
 if TYPE_CHECKING:
     pass
@@ -49,6 +51,19 @@ class ResultRecordMetadata(BaseModel):
     prefect_version: str = Field(default=prefect.__version__)
     storage_block_id: Optional[uuid.UUID] = Field(default=None)
 
+    @field_validator("serializer", mode="before")
+    @classmethod
+    def _tolerate_unknown_serializer(
+        cls, value: Serializer | dict[str, Any] | Any
+    ) -> Serializer | dict[str, Any] | Any:
+        if isinstance(value, dict) and "type" in value:
+            try:
+                lookup_type(Serializer, dispatch_key=value["type"])
+            except KeyError:
+                return UnknownSerializer.model_construct(**value)
+            return Serializer(**value)
+        return value
+
     def dump_bytes(self) -> bytes:
         """
         Serialize the metadata to bytes.

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/blocks/notifications.py

@@ -13,7 +13,11 @@ from prefect.blocks.abstract import NotificationBlock, NotificationError
 from prefect.logging import LogEavesdropper
 from prefect.types import SecretDict
 from prefect.utilities.templating import apply_values, find_placeholders
-from prefect.utilities.urls import validate_restricted_url
+from prefect.utilities.urls import (
+    SSRFProtectedAsyncHTTPTransport,
+    SSRFProtectedHTTPTransport,
+    validate_restricted_url,
+)
 
 PREFECT_NOTIFY_TYPE_DEFAULT = "info"  # Use a valid apprise type as default
 
@@ -987,13 +991,18 @@ class CustomWebhookNotificationBlock(NotificationBlock):
         import httpx
 
         request_args = self._build_request_args(body, subject)
+        client_kwargs: dict[str, Any] = {
+            "headers": {"user-agent": "Prefect Notifications"},
+        }
         if not self.allow_private_urls:
             validate_restricted_url(request_args["url"])
+            # Re-validate at connection time and pin the resolved IP to close
+            # the DNS-rebinding TOCTOU window.
+            client_kwargs["transport"] = SSRFProtectedAsyncHTTPTransport()
         cookies = request_args.pop("cookies", dict())
+        client_kwargs["cookies"] = cookies
         # make request with httpx
-        async with httpx.AsyncClient(
-            headers={"user-agent": "Prefect Notifications"}, cookies=cookies
-        ) as client:
+        async with httpx.AsyncClient(**client_kwargs) as client:
             resp = await client.request(**request_args)
         resp.raise_for_status()
 
@@ -1002,13 +1011,16 @@ class CustomWebhookNotificationBlock(NotificationBlock):
         import httpx
 
         request_args = self._build_request_args(body, subject)
+        client_kwargs: dict[str, Any] = {
+            "headers": {"user-agent": "Prefect Notifications"},
+        }
         if not self.allow_private_urls:
             validate_restricted_url(request_args["url"])
+            client_kwargs["transport"] = SSRFProtectedHTTPTransport()
         cookies = request_args.pop("cookies", dict())
+        client_kwargs["cookies"] = cookies
         # make request with httpx
-        with httpx.Client(
-            headers={"user-agent": "Prefect Notifications"}, cookies=cookies
-        ) as client:
+        with httpx.Client(**client_kwargs) as client:
             resp = client.request(**request_args)
         resp.raise_for_status()
 

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/blocks/webhook.py

@@ -8,12 +8,21 @@ from typing_extensions import Literal
 
 from prefect.blocks.core import Block
 from prefect.types import SecretDict
-from prefect.utilities.urls import validate_restricted_url
+from prefect.utilities.urls import (
+    SSRFProtectedAsyncHTTPTransport,
+    validate_restricted_url,
+)
 
 # Use a global HTTP transport to maintain a process-wide connection pool for
 # interservice requests
 _http_transport = AsyncHTTPTransport()
 _insecure_http_transport = AsyncHTTPTransport(verify=False)
+# Separate pools for calls that must be protected from DNS-rebinding SSRF.  The
+# protected transport validates the resolved IP at connection time and connects
+# to the pre-resolved address, closing the TOCTOU window exploited by DNS
+# rebinding attacks.
+_safe_http_transport = SSRFProtectedAsyncHTTPTransport()
+_safe_insecure_http_transport = SSRFProtectedAsyncHTTPTransport(verify=False)
 
 
 class Webhook(Block):
@@ -53,10 +62,13 @@ class Webhook(Block):
     )
 
     def block_initialization(self) -> None:
-        if self.verify:
-            self._client = AsyncClient(transport=_http_transport)
+        if self.allow_private_urls:
+            transport = _http_transport if self.verify else _insecure_http_transport
         else:
-            self._client = AsyncClient(transport=_insecure_http_transport)
+            transport = (
+                _safe_http_transport if self.verify else _safe_insecure_http_transport
+            )
+        self._client = AsyncClient(transport=transport)
 
     async def call(self, payload: dict[str, Any] | str | None = None) -> Response:
         """

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/client/AGENTS.md

@@ -9,6 +9,7 @@ HTTP client for communicating with Prefect server and Prefect Cloud.
 - **Methods should accept simple kwargs** (`str`, `int`, `UUID`, etc.) and return Pydantic models. Avoid accepting complex objects as parameters.
 - **Client schemas are separate from server schemas.** This module has its own `schemas/` to avoid tangling with `server/schemas/`. Keep the boundary clean.
 - **Do not import server-only modules** (`server/database`, `server/models`, etc.) from anything in this directory — it would break the `prefect-client` package build.
+- **Task-run submission schemas must be eagerly rebuilt.** Schemas instantiated on the concurrent submission path (`Task.create_local_run()`) are rebuilt at import time via `model_rebuild()` at the bottom of `schemas/objects.py`. Pydantic defers schema construction to first use; under threadpool contention, multiple workers race to build the same schema simultaneously. If you add a new schema used in this hot path, add a corresponding `model_rebuild()` call there.
 
 ## Structure
 

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/client/_version_checking.py

@@ -142,7 +142,7 @@ async def check_server_version(
     if auth_string:
         token = base64.b64encode(auth_string.encode("utf-8")).decode("utf-8")
         headers["Authorization"] = f"Basic {token}"
-    elif api_key:
+    elif api_key and "Authorization" not in headers:
         headers["Authorization"] = f"Bearer {api_key}"
     if headers:
         httpx_kwargs["headers"] = headers

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/client/schemas/objects.py

@@ -942,6 +942,18 @@ class TaskRun(TimeSeriesBaseModel, ObjectBaseModel):
         return get_or_create_run_name(name)
 
 
+# These models are instantiated while task runs are being created locally on the
+# concurrent submission path. Rebuild them eagerly so threadpool workers do not
+# trigger deferred first-use schema builds under contention.
+RunInput.model_rebuild()
+TaskRunPolicy.model_rebuild()
+TaskRunResult.model_rebuild()
+FlowRunResult.model_rebuild()
+Parameter.model_rebuild()
+Constant.model_rebuild()
+TaskRun.model_rebuild()
+
+
 class Workspace(PrefectBaseModel):
     """
     A Prefect Cloud workspace.

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/flow_engine.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import datetime
 import logging
 import multiprocessing
@@ -292,7 +293,19 @@ def _send_heartbeats(
                     return
                 time.sleep(1)
 
-    thread = threading.Thread(target=heartbeat_loop, daemon=True)
+    # Copy the current context so the heartbeat thread sees the same
+    # `SettingsContext` (and therefore the same `PREFECT_API_URL`) as the
+    # calling thread. Without this, `threading.Thread` starts with an empty
+    # context and `SettingsContext.get()` falls back to the process-wide
+    # `GLOBAL_SETTINGS_CONTEXT`, which is initialized at import time and can
+    # have a stale `api.url=None`. That caused `EventsWorker.instance()` from
+    # the heartbeat path to spawn an ephemeral `SubprocessASGIServer` during
+    # flow teardown, racing with interpreter shutdown and aborting the
+    # process.
+    heartbeat_ctx = contextvars.copy_context()
+    thread = threading.Thread(
+        target=heartbeat_ctx.run, args=(heartbeat_loop,), daemon=True
+    )
     thread.start()
     engine.logger.debug("Started flow run heartbeat context")
 

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/futures.py

@@ -194,6 +194,44 @@ class PrefectConcurrentFuture(PrefectWrappedFuture[R, concurrent.futures.Future[
     when the task run is submitted to a ThreadPoolExecutor.
     """
 
+    def __init__(
+        self,
+        task_run_id: uuid.UUID,
+        wrapped_future: concurrent.futures.Future[R],
+    ):
+        super().__init__(task_run_id, wrapped_future)
+        self._prefect_done_callbacks: list[Callable[[PrefectFuture[R]], None]] = []
+        self._prefect_done_callbacks_lock = threading.Lock()
+        self._prefect_done_event = threading.Event()
+
+        # Register Prefect's internal completion notifier before any user callbacks
+        # so wait()/as_completed() do not depend on callback chain ordering.
+        self._wrapped_future.add_done_callback(self._notify_prefect_done_callbacks)
+
+    def _add_prefect_done_callback(
+        self, fn: Callable[[PrefectFuture[R]], None]
+    ) -> None:
+        with self._prefect_done_callbacks_lock:
+            if self._prefect_done_event.is_set():
+                call_immediately = True
+            else:
+                self._prefect_done_callbacks.append(fn)
+                call_immediately = False
+
+        if call_immediately:
+            fn(self)
+
+    def _notify_prefect_done_callbacks(
+        self, future: concurrent.futures.Future[R]
+    ) -> None:
+        with self._prefect_done_callbacks_lock:
+            self._prefect_done_event.set()
+            callbacks = self._prefect_done_callbacks[:]
+            self._prefect_done_callbacks.clear()
+
+        for callback in callbacks:
+            callback(self)
+
     def wait(self, timeout: float | None = None) -> None:
         try:
             result = self._wrapped_future.result(timeout=timeout)
@@ -538,6 +576,17 @@ class PrefectFutureList(list[PrefectFuture[R]], Iterator[PrefectFuture[R]]):
         return results
 
 
+def _register_prefect_done_callback(
+    future: PrefectFuture[R], callback: Callable[[PrefectFuture[R]], None]
+) -> None:
+    add_prefect_done_callback = getattr(future, "_add_prefect_done_callback", None)
+    if add_prefect_done_callback is not None:
+        add_prefect_done_callback(callback)
+        return
+
+    future.add_done_callback(callback)
+
+
 def as_completed(
     futures: list[PrefectFuture[R]], timeout: float | None = None
 ) -> Generator[PrefectFuture[R], None]:
@@ -560,7 +609,7 @@ def as_completed(
                     finished_event.set()
 
             for future in pending:
-                future.add_done_callback(add_to_done)
+                _register_prefect_done_callback(future, add_to_done)
 
             while pending:
                 finished_event.wait()
@@ -651,7 +700,7 @@ def wait(
 
             # Add callbacks to all pending futures
             for future in not_done:
-                future.add_done_callback(mark_done)
+                _register_prefect_done_callback(future, mark_done)
 
             # Wait for futures to complete within timeout
             while not_done:

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/runner/AGENTS.md

@@ -96,7 +96,11 @@ Each execution mode has a ProcessStarter implementation. To add a new execution
 
 `ScheduledRunPoller` now calls `propose_pending` (Scheduled → Pending) before handing off to `FlowRunExecutor`. `FlowRunExecutor` then calls `propose_submitting` (Pending → Submitting sub-state) as step 1 of its lifecycle **when `propose_submitting=True` (the default)**. These are two separate transitions — do not collapse them. The split exists so automations listening for the Pending state fire correctly before the executor begins.
 
-**Exception: `prefect flow-run execute` CLI path sets `propose_submitting=False`** via `FlowRunExecutorContext.create_executor(propose_submitting=False)`. The CLI is invoked by a worker that has already advanced the flow run past the Pending state, so proposing Submitting again would be wrong. The cancelling precheck (step 1a) still runs unconditionally even when `propose_submitting=False`.
+**Two callers set `propose_submitting=False`** via `FlowRunExecutorContext.create_executor(propose_submitting=False)` — both have already advanced the flow run past the Pending state, so proposing Submitting again would be wrong:
+- `prefect flow-run execute` CLI path (invoked by a worker)
+- `execute_bundle()` in `prefect._experimental.bundles.execute` (invoked by bundle dispatch)
+
+The cancelling precheck (step 1a) still runs unconditionally even when `propose_submitting=False`.
 
 ## ProcessWorker Migration (Known Gap)
 

{prefect_client-3.6.27.dev4 → prefect_client-3.6.28}/src/prefect/serializers.py

@@ -132,9 +132,16 @@ class Serializer(BaseModel, Generic[D]):
             except KeyError as exc:
                 raise ValidationError.from_exception_data(
                     title=cls.__name__,
-                    line_errors=[{"type": str(exc), "input": kwargs["type"]}],
+                    line_errors=[
+                        {
+                            "type": "value_error",
+                            "loc": ("type",),
+                            "input": kwargs["type"],
+                            "ctx": {"error": exc},
+                        }
+                    ],
                     input_type="python",
-                )
+                ) from exc
 
             return super().__new__(subcls)
         else:
@@ -158,6 +165,35 @@ class Serializer(BaseModel, Generic[D]):
         return type_str if isinstance(type_str, str) else None
 
 
+class UnknownSerializer(Serializer):
+    """
+    Opaque placeholder for serializers that are unavailable in the current process.
+
+    This allows persisted result metadata to be inspected without importing the custom
+    serializer implementation. Actual serialization work still fails when attempted.
+    """
+
+    type: str
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="allow")
+
+    @classmethod
+    def __dispatch_key__(cls) -> str:
+        return "__unknown__"
+
+    def dumps(self, obj: Any) -> bytes:
+        raise RuntimeError(
+            f"Serializer {self.type!r} is not available in this environment, so "
+            "serialization cannot be performed."
+        )
+
+    def loads(self, blob: bytes) -> Any:
+        raise RuntimeError(
+            f"Serializer {self.type!r} is not available in this environment, so "
+            "deserialization cannot be performed."
+        )
+
+
 class PickleSerializer(Serializer[D]):
     """
     Serializes objects using the pickle protocol.