prefect-client 3.9.1.dev7__tar.gz → 3.9.2.dev1__tar.gz

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prefect-client
-Version: 3.9.1.dev7
+Version: 3.9.2.dev1
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://www.prefect.io/docs
@@ -163,7 +163,7 @@ describing the functionality you are interested in using and we will do our best
 ## Next steps
 
 There's lots more you can do to orchestrate and observe your workflows with Prefect!
-Start with our [friendly tutorial](https://www.prefect.io/docs/tutorials) or explore the [core concepts of Prefect workflows](https://www.prefect.io/docs/concepts/).
+Start with our [friendly tutorial](https://www.prefect.io/docs/v3/get-started/quickstart) or explore the [core concepts of Prefect workflows](https://www.prefect.io/docs/concepts/).
 
 ## Join the community
 
@@ -173,6 +173,6 @@ All community forums, including code contributions, issue discussions, and Slack
 
 ## Contribute
 
-See our [documentation on contributing to Prefect](https://www.prefect.io/docs/contributing/overview/).
+See our [documentation on contributing to Prefect](https://www.prefect.io/docs/contribute).
 
 Thanks for being part of the mission to build a new kind of workflow system and, of course, **happy engineering!**

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/README.md

@@ -94,7 +94,7 @@ describing the functionality you are interested in using and we will do our best
 ## Next steps
 
 There's lots more you can do to orchestrate and observe your workflows with Prefect!
-Start with our [friendly tutorial](https://www.prefect.io/docs/tutorials) or explore the [core concepts of Prefect workflows](https://www.prefect.io/docs/concepts/).
+Start with our [friendly tutorial](https://www.prefect.io/docs/v3/get-started/quickstart) or explore the [core concepts of Prefect workflows](https://www.prefect.io/docs/concepts/).
 
 ## Join the community
 
@@ -104,6 +104,6 @@ All community forums, including code contributions, issue discussions, and Slack
 
 ## Contribute
 
-See our [documentation on contributing to Prefect](https://www.prefect.io/docs/contributing/overview/).
+See our [documentation on contributing to Prefect](https://www.prefect.io/docs/contribute).
 
 Thanks for being part of the mission to build a new kind of workflow system and, of course, **happy engineering!**

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/AGENTS.md

@@ -29,7 +29,7 @@ Runtime flow/task parameter values must come from `utilities.callables.get_call_
 - **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.
 - **Event and log WebSocket subscribers are parallel implementations.** `events/clients.py::PrefectEventSubscriber` and `logging/clients.py::PrefectLogsSubscriber` duplicate the same reconnect/backoff/dedup logic, including the `reconnect_on_clean_close` option (used by `events/subscribers.py::FlowRunSubscriber` so a clean disconnect doesn't hide a terminal event). Mirror any reconnection-behavior change across both.
 - **Flow run observers own their stream recovery.** `_internal/observers.py` observers create subscribers with `reconnection_attempts=0` and delegate polling fallback, reconnect backoff, and setup deadlines to `_internal/_observation_delivery.py::ObservationDelivery`. Subscribers close any socket left by a failed or cancelled `__aenter__`, since callers never exit a context that failed to enter.
-- **Use `whenever` compat helpers for all datetime conversions on Python 3.13+.** `prefect-client` depends on `whenever` only on Python 3.13+, so modules it ships must keep `whenever` imports behind `sys.version_info >= (3, 13)`; only server code that the client build strips may import it unconditionally (see `client/AGENTS.md`). `types/_datetime.py` provides `now()`, `_whenever_to_stdlib()`, `_whenever_zdt_from_py()`, and `_whenever_pdt_from_py()` to abstract over API differences across supported whenever releases. Version-specific code is guarded by feature-detection flags (`_WHENEVER_NEW_API` for ≥ 0.10.0, `_SYSTEM_TZ` for ≥ 0.11), not version checks. Never call `DateTime.now()` or `pendulum.now()` directly — use `now()` from `types/_datetime.py` instead. Avoid no-argument `datetime.datetime.now()` because it returns a tz-naive datetime that raises `TypeError` when compared to the tz-aware datetimes produced by `now()`. Explicitly timezone-aware stdlib calls such as `datetime.now(ZoneInfo("UTC"))` are allowed when needed to preserve timezone information. Never call `ZonedDateTime.from_py_datetime()`, `PlainDateTime.from_py_datetime()`, or `.py_datetime()` directly — use the helpers instead. Likewise avoid `.assume_system_tz()`/`.to_system_tz()` (deprecated in 0.11; the warning fails tests under `filterwarnings = error`) — use `in_local_tz()` — and direct `DateTimeDelta` imports (removed in 0.11) — use the `Interval` alias. Violations will silently break on whichever whenever version the helpers weren't written for.
+- **Use `whenever` compat helpers for all datetime conversions on Python 3.13+.** `prefect-client` depends on `whenever` only on Python 3.13+, so modules it ships must keep `whenever` imports behind `sys.version_info >= (3, 13)`; only code that the client build strips may import it unconditionally (see the repo-root `client/AGENTS.md`). `types/_datetime.py` provides `now()`, `_whenever_to_stdlib()`, `_whenever_zdt_from_py()`, and `_whenever_pdt_from_py()` to abstract over API differences across supported whenever releases. Version-specific code is guarded by feature-detection flags (`_WHENEVER_NEW_API` for ≥ 0.10.0, `_SYSTEM_TZ` for ≥ 0.11), not version checks. These flags are only probed on Python 3.13+ (`_WHENEVER_NEW_API` is `False` and `_SYSTEM_TZ` is undefined on 3.11/3.12), so a helper that server-only code calls on every Python must feature-detect on the `whenever` class itself. Never call `DateTime.now()` or `pendulum.now()` directly — use `now()` from `types/_datetime.py` instead. Avoid no-argument `datetime.datetime.now()` because it returns a tz-naive datetime that raises `TypeError` when compared to the tz-aware datetimes produced by `now()`. Explicitly timezone-aware stdlib calls such as `datetime.now(ZoneInfo("UTC"))` are allowed when needed to preserve timezone information. Never call `ZonedDateTime.from_py_datetime()`, `PlainDateTime.from_py_datetime()`, or `.py_datetime()` directly — use the helpers instead. Likewise avoid `.assume_system_tz()`/`.to_system_tz()` (deprecated in 0.11; the warning fails tests under `filterwarnings = error`) — use `in_local_tz()` — and direct `DateTimeDelta` imports (removed in 0.11) — use the `Interval` alias. Violations will silently break on whichever whenever version the helpers weren't written for.
 - **Call Pendulum-only members via `types/_datetime.py::_pendulum_call` on Python 3.11/3.12.** Prefect's `DateTime`/`Date`/`Duration` wrap Pendulum-only members (and some shared stdlib methods like `replace`) with user-facing deprecation warnings; `_pendulum_call` bypasses them so users only see warnings for their own calls. `pyproject.toml` ignores these warnings in pytest, so direct calls from Prefect code pass tests silently unless covered by the guards in `tests/test_datetime.py`.
 - **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.

prefect_client-3.9.2.dev1/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.9.2.dev1"
+__build_date__ = "2026-11-01 08:11:41.429923+00:00"
+__git_commit__ = "2b76fb3da359c20fc5fa4e4db615a6fc76330b1e"
+__dirty__ = False

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/concurrency/AGENTS.md

@@ -18,7 +18,7 @@ Does NOT define concurrency limits (server-side in `server/`). Does NOT handle t
 
 **`raise_on_lease_renewal_failure` (public parameter):** Controls lease renewal failure behavior independently from `strict`. When `None` (default), falls back to the value of `strict` for backward compatibility. Set to `False` to let long-running tasks continue even if a transient renewal error occurs; set to `True` to terminate immediately on renewal failure regardless of `strict`. This means `strict=True, raise_on_lease_renewal_failure=False` gives strict slot acquisition but non-fatal renewal failures, and vice versa.
 
-**Lease renewal:** `_leases.py` starts a daemon thread that renews immediately on entry, then waits for 75% of `lease_duration` between renewals. The renewal thread uses the standard `get_client(sync_client=True)` path and retries each renewal up to 3 times with exponential backoff. If all attempts fail, a shared failure handler either cancels execution with the existing sync/async cancel scope or logs a warning, depending on `raise_on_lease_renewal_failure`.
+**Lease renewal:** `_leases.py` starts a daemon thread that renews immediately on entry, then waits for 75% of `lease_duration` between renewals. The renewal thread uses the standard `get_client(sync_client=True)` path and retries each renewal up to 3 times with exponential backoff. If all attempts fail, a shared failure handler either cancels execution with the existing sync/async cancel scope or logs a warning, depending on `raise_on_lease_renewal_failure`. Exception: when a `flow_run_id` is given and renewal fails with `410 Gone`, the thread reads the flow run and stops without cancelling if its server state is final, because the terminal transition releases the lease before the engine receives the proposal response.
 
 **Sync/async lockstep invariant:** `asyncio.py`/`sync.py` and `_asyncio.py`/`_sync.py` are parallel implementations. Any behavior change to one must be mirrored in the other.
 

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/concurrency/_leases.py

@@ -4,6 +4,9 @@ from contextlib import asynccontextmanager, contextmanager
 from typing import TYPE_CHECKING, AsyncGenerator, Generator
 from uuid import UUID
 
+import httpx
+
+from prefect._internal.compatibility.starlette import status
 from prefect._internal.concurrency.cancellation import (
     AsyncCancelScope,
     WatcherThreadCancelScope,
@@ -90,6 +93,45 @@ def _lease_renewal_loop(
             stop_event.wait(lease_duration * _RENEWAL_FRACTION)
 
 
+def _lease_released_by_final_flow_run(
+    exc: BaseException, lease_id: UUID, flow_run_id: UUID | None
+) -> bool:
+    """
+    Check whether a lease renewal failure is explained by the flow run having
+    reached a final state on the server, which releases the lease before the
+    engine has received the response to its terminal state proposal.
+    """
+    if flow_run_id is None or not (
+        isinstance(exc, httpx.HTTPStatusError)
+        and exc.response.status_code == status.HTTP_410_GONE
+    ):
+        return False
+
+    logger = get_logger("concurrency")
+    try:
+        with get_client(sync_client=True) as client:
+            flow_run = client.read_flow_run(flow_run_id)
+    except Exception:
+        logger.debug(
+            "Failed to read flow run %s after its concurrency lease was not found",
+            flow_run_id,
+            exc_info=True,
+        )
+        return False
+
+    if flow_run.state is None or not flow_run.state.is_final():
+        return False
+
+    logger.debug(
+        "Concurrency lease %s was released because flow run %s reached final "
+        "state %s; stopping lease renewal",
+        lease_id,
+        flow_run_id,
+        flow_run.state.type.value,
+    )
+    return True
+
+
 def _handle_lease_renewal_failure(
     exc: BaseException,
     lease_id: UUID,
@@ -139,6 +181,7 @@ def _start_lease_renewal_thread(
     raise_on_lease_renewal_failure: bool,
     suppress_warnings: bool,
     cancel_scope: AsyncCancelScope | WatcherThreadCancelScope,
+    flow_run_id: UUID | None = None,
 ) -> tuple[threading.Event, threading.Thread]:
     stop_event = threading.Event()
     renewal_ctx = contextvars.copy_context()
@@ -152,14 +195,17 @@ def _start_lease_renewal_thread(
         try:
             _lease_renewal_loop(lease_id, lease_duration, stop_event)
         except Exception as exc:
-            if not stop_event.is_set():
-                _handle_lease_renewal_failure(
-                    exc,
-                    lease_id,
-                    raise_on_lease_renewal_failure,
-                    suppress_warnings,
-                    cancel_scope,
-                )
+            if stop_event.is_set() or _lease_released_by_final_flow_run(
+                exc, lease_id, flow_run_id
+            ):
+                return
+            _handle_lease_renewal_failure(
+                exc,
+                lease_id,
+                raise_on_lease_renewal_failure,
+                suppress_warnings,
+                cancel_scope,
+            )
 
     def renewal_loop() -> None:
         renewal_ctx.run(_run_with_failure_handler)
@@ -179,6 +225,7 @@ def maintain_concurrency_lease(
     lease_duration: float,
     raise_on_lease_renewal_failure: bool = False,
     suppress_warnings: bool = False,
+    flow_run_id: UUID | None = None,
 ) -> Generator[None, None, None]:
     """
     Maintain a concurrency lease for the given lease ID.
@@ -187,6 +234,9 @@ def maintain_concurrency_lease(
         lease_id: The ID of the lease to maintain.
         lease_duration: The duration of the lease in seconds.
         raise_on_lease_renewal_failure: A boolean specifying whether to raise an error if the lease renewal fails.
+        flow_run_id: The ID of the flow run holding the lease. When the lease is
+            not found and this flow run is final on the server, the lease was
+            released by the terminal transition and execution is not terminated.
     """
     with WatcherThreadCancelScope() as cancel_scope:
         stop_event: threading.Event | None = None
@@ -198,6 +248,7 @@ def maintain_concurrency_lease(
                 raise_on_lease_renewal_failure,
                 suppress_warnings,
                 cancel_scope,
+                flow_run_id,
             )
             yield
         finally:
@@ -213,6 +264,7 @@ async def amaintain_concurrency_lease(
     lease_duration: float,
     raise_on_lease_renewal_failure: bool = False,
     suppress_warnings: bool = False,
+    flow_run_id: UUID | None = None,
 ) -> AsyncGenerator[None, None]:
     """
     Maintain a concurrency lease for the given lease ID.
@@ -221,6 +273,9 @@ async def amaintain_concurrency_lease(
         lease_id: The ID of the lease to maintain.
         lease_duration: The duration of the lease in seconds.
         raise_on_lease_renewal_failure: A boolean specifying whether to raise an error if the lease renewal fails.
+        flow_run_id: The ID of the flow run holding the lease. When the lease is
+            not found and this flow run is final on the server, the lease was
+            released by the terminal transition and execution is not terminated.
     """
     with AsyncCancelScope() as cancel_scope:
         stop_event: threading.Event | None = None
@@ -231,6 +286,7 @@ async def amaintain_concurrency_lease(
                 raise_on_lease_renewal_failure,
                 suppress_warnings,
                 cancel_scope,
+                flow_run_id,
             )
             yield
         finally:

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/deployments/runner.py

@@ -1671,14 +1671,14 @@ async def adeploy(
                 " or specify a remote storage location for the flow with `.from_source`."
                 " If you are attempting to deploy a flow to a local process work pool,"
                 " consider using `flow.serve` instead. See the documentation for more"
-                " information: https://www.prefect.io/docs/latest/how-to-guides/deployments/run-flows-in-local-processes"
+                " information: https://www.prefect.io/docs/v3/how-to-guides/deployment_infra/run-flows-in-local-processes"
             )
         elif work_pool.type == "process" and not ignore_warnings:
             console.print(
                 "Looks like you're deploying to a process work pool. If you're creating a"
                 " deployment for local development, calling `.serve` on your flow is a great"
                 " way to get started. See the documentation for more information:"
-                " https://www.prefect.io/docs/latest/how-to-guides/deployments/run-flows-in-local-processes "
+                " https://www.prefect.io/docs/v3/how-to-guides/deployment_infra/run-flows-in-local-processes "
                 " Set `ignore_warnings=True` to suppress this message.",
                 style="yellow",
             )
@@ -1912,14 +1912,14 @@ def deploy(
                 " or specify a remote storage location for the flow with `.from_source`."
                 " If you are attempting to deploy a flow to a local process work pool,"
                 " consider using `flow.serve` instead. See the documentation for more"
-                " information: https://www.prefect.io/docs/latest/how-to-guides/deployments/run-flows-in-local-processes"
+                " information: https://www.prefect.io/docs/v3/how-to-guides/deployment_infra/run-flows-in-local-processes"
             )
         elif work_pool.type == "process" and not ignore_warnings:
             console.print(
                 "Looks like you're deploying to a process work pool. If you're creating a"
                 " deployment for local development, calling `.serve` on your flow is a great"
                 " way to get started. See the documentation for more information:"
-                " https://www.prefect.io/docs/latest/how-to-guides/deployments/run-flows-in-local-processes "
+                " https://www.prefect.io/docs/v3/how-to-guides/deployment_infra/run-flows-in-local-processes "
                 " Set `ignore_warnings=True` to suppress this message.",
                 style="yellow",
             )

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/flow_engine.py

@@ -1137,7 +1137,10 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
             if lease_id := self.state.state_details.deployment_concurrency_lease_id:
                 stack.enter_context(
                     maintain_concurrency_lease(
-                        lease_id, 300, raise_on_lease_renewal_failure=True
+                        lease_id,
+                        300,
+                        raise_on_lease_renewal_failure=True,
+                        flow_run_id=self.flow_run.id,
                     )
                 )
 
@@ -1865,7 +1868,10 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
             if lease_id := self.state.state_details.deployment_concurrency_lease_id:
                 await stack.enter_async_context(
                     amaintain_concurrency_lease(
-                        lease_id, 300, raise_on_lease_renewal_failure=True
+                        lease_id,
+                        300,
+                        raise_on_lease_renewal_failure=True,
+                        flow_run_id=self.flow_run.id,
                     )
                 )
 

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/flow_runs.py

@@ -133,6 +133,7 @@ async def wait_for_flow_run(
     )
 
     with anyio.move_on_after(timeout):
+        received_final_event = False
         async with get_events_subscriber(filter=event_filter) as subscriber:
             flow_run = await client.read_flow_run(flow_run_id)
             if flow_run.state and flow_run.state.is_final():
@@ -151,7 +152,19 @@ async def wait_for_flow_run(
                     logger.info(f"Flow run is in state {state.name!r}")
 
                 if state.is_final():
-                    return await client.read_flow_run(flow_run_id)
+                    received_final_event = True
+                    break
+
+        if received_final_event:
+            # A final state event can be delivered before the state change is
+            # visible to API reads, so read until the run reports a final state
+            poll_delay = 0.1
+            while True:
+                flow_run = await client.read_flow_run(flow_run_id)
+                if flow_run.state and flow_run.state.is_final():
+                    return flow_run
+                await anyio.sleep(poll_delay)
+                poll_delay = min(poll_delay * 2, 5)
 
     raise FlowRunWaitTimeout(
         f"Flow run with ID {flow_run_id} exceeded watch timeout of {timeout} seconds"

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/flows.py

@@ -706,11 +706,11 @@ class Flow(Generic[P, R]):
                 from fastapi.encoders import jsonable_encoder
 
                 serialized_parameters[key] = jsonable_encoder(value)
-            except (TypeError, ValueError, RecursionError):
-                # `jsonable_encoder` recurses into unknown objects with no cycle
-                # or depth limit, so a deeply-nested or self-referential value
-                # raises `RecursionError`. Treat it like any other unserializable
-                # value and fall back to the placeholder below.
+            except Exception:
+                # `jsonable_encoder` can raise arbitrary errors for values it
+                # cannot encode (e.g. `RecursionError` for self-referential
+                # objects, or any error from `__reduce__` while deep-copying a
+                # dataclass). Fall back to the placeholder below.
                 logger.debug(
                     f"Parameter {key!r} for flow {self.name!r} is unserializable. "
                     f"Type {type(value).__name__!r} and will not be stored "

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/runner/_flow_run_executor.py

@@ -51,10 +51,16 @@ class ProcessStarter(Protocol):
 
 @dataclass(frozen=True)
 class FlowRunExecutionResult:
-    """Process handle plus the infrastructure status for a completed attempt."""
+    """Process handle plus the infrastructure status for a completed attempt.
+
+    `crash_unreported` is `True` when the process exited non-zero or failed
+    after starting, and the runner could not record a final state for the flow
+    run in its place.
+    """
 
     handle: ProcessHandle
     status_code: int | None
+    crash_unreported: bool = False
 
 
 class FlowRunExecutor:
@@ -124,6 +130,7 @@ class FlowRunExecutor:
         """
         handle: ProcessHandle | None = None
         attempt_conclusion: AttemptConclusion | None = None
+        process_error: Exception | None = None
         try:
             # Step 1a: already-cancelling precheck (runs regardless of propose_submitting)
             if self._flow_run.state and self._flow_run.state.is_cancelling():
@@ -165,16 +172,26 @@ class FlowRunExecutor:
             handle = await self._start_process(task_status)
 
         except Exception as exc:
+            # A failure after the process exited (e.g. its output stream broke)
+            # still leaves an exit to account for. A live process stays
+            # registered so the process manager can still stop it.
+            started_handle = self._process_manager.get(self._flow_run.id)
+            if started_handle is None or started_handle.returncode is None:
+                self._logger.exception(
+                    "Flow run '%s' could not start: %s",
+                    self._flow_run.id,
+                    exc,
+                )
+                await self._state_proposer.propose_crashed(
+                    self._flow_run,
+                    message=f"Flow run could not start: {exc}",
+                )
+                return
             self._logger.exception(
-                "Flow run '%s' could not start: %s",
-                self._flow_run.id,
-                exc,
-            )
-            await self._state_proposer.propose_crashed(
-                self._flow_run,
-                message=f"Flow run could not start: {exc}",
+                "Flow run '%s' process failed: %s", self._flow_run.id, exc
             )
-            return
+            handle = started_handle
+            process_error = exc
         finally:
             # Step 6: snapshot terminal evidence before process cleanup unregisters
             # the attempt control session, then remove the process handle.
@@ -199,14 +216,23 @@ class FlowRunExecutor:
                     info.resolution,
                     extra={"flow_run_id": self._flow_run.id},
                 )
-            crashed_state = await self._state_proposer.propose_crashed(
-                self._flow_run, message=msg
-            )
-            # Step 8: run crashed hooks
-            if crashed_state is not None:
-                await self._hook_runner.run_crashed_hooks(self._flow_run, crashed_state)
+        elif process_error is not None:
+            msg = f"Flow run process failed: {process_error}"
+        else:
+            return FlowRunExecutionResult(handle=handle, status_code=exit_code)
 
-        return FlowRunExecutionResult(handle=handle, status_code=exit_code)
+        crashed_state = await self._state_proposer.propose_crashed(
+            self._flow_run, message=msg
+        )
+        # Step 8: run crashed hooks
+        if crashed_state is not None:
+            await self._hook_runner.run_crashed_hooks(self._flow_run, crashed_state)
+
+        return FlowRunExecutionResult(
+            handle=handle,
+            status_code=exit_code,
+            crash_unreported=crashed_state is None or not crashed_state.is_final(),
+        )
 
     async def _start_process(
         self,

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/server/api/deployments.py

@@ -20,7 +20,7 @@ from prefect.server.api.validation import (
     validate_job_variables_for_deployment,
     validate_job_variables_for_deployment_flow_run,
 )
-from prefect.server.api.workers import WorkerLookups
+from prefect.server.api.workers import WorkerLookups, schedule_readiness_update
 from prefect.server.database import PrefectDBInterface, provide_database_interface
 from prefect.server.exceptions import MissingVariableError, ObjectNotFoundError
 from prefect.server.models.deployments import mark_deployments_ready
@@ -656,10 +656,16 @@ async def get_scheduled_flow_runs_for_deployments(
             for orm_flow_run in orm_flow_runs
         ]
 
+        becoming_ready = await models.deployments.has_not_ready_deployments(
+            session=session, deployment_ids=deployment_ids
+        )
+
     sorted_deployment_ids = ",".join(str(d) for d in sorted(deployment_ids))
-    await docket.add(
+    await schedule_readiness_update(
+        docket,
         mark_deployments_ready,
         key=f"mark_deployments_ready:deployments:{sorted_deployment_ids}",
+        becoming_ready=becoming_ready,
     )(
         deployment_ids=deployment_ids,
     )

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/server/api/flow_runs.py

@@ -11,6 +11,7 @@ from urllib.parse import quote
 from uuid import UUID
 
 import orjson
+import pydantic_core
 import sqlalchemy as sa
 from docket import Depends as DocketDepends
 from docket import Docket, Retry
@@ -69,6 +70,21 @@ logger: "logging.Logger" = get_logger("server.api")
 router: PrefectRouter = PrefectRouter(prefix="/flow_runs", tags=["Flow Runs"])
 
 
+def _json_response(content: Any) -> Response:
+    """
+    Serialize already JSON-compatible `content` into a JSON response.
+
+    orjson is much faster than the FastAPI encoder, but it rejects integers
+    outside of the 64-bit range. Flow run parameters are arbitrary user data, so
+    fall back to pydantic-core, which supports arbitrarily large integers.
+    """
+    try:
+        body = orjson.dumps(content)
+    except TypeError:
+        body = pydantic_core.to_json(content)
+    return Response(content=body, media_type="application/json")
+
+
 def _get_request_docket(request: Request) -> Docket | None:
     return getattr(request.app.state, "docket", None)
 
@@ -621,10 +637,7 @@ async def read_flow_runs(
             ).model_dump(mode="json")
             for fr in db_flow_runs
         ]
-        return Response(
-            content=orjson.dumps(encoded),
-            media_type="application/json",
-        )
+        return _json_response(encoded)
 
 
 @router.delete("/{id:uuid}", status_code=status.HTTP_204_NO_CONTENT)
@@ -1047,10 +1060,7 @@ async def paginate_flow_runs(
         page=page,
     ).model_dump(mode="json")
 
-    return Response(
-        content=orjson.dumps(response),
-        media_type="application/json",
-    )
+    return _json_response(response)
 
 
 FLOW_RUN_LOGS_DOWNLOAD_PAGE_LIMIT = 1000

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/server/api/work_queues.py

@@ -18,6 +18,7 @@ from sqlalchemy.exc import IntegrityError
 import prefect.server.api.dependencies as dependencies
 import prefect.server.models as models
 import prefect.server.schemas as schemas
+from prefect.server.api.workers import schedule_readiness_update
 from prefect.server.database import (
     PrefectDBInterface,
     provide_database_interface,
@@ -189,19 +190,32 @@ async def read_work_queue_runs(
     if x_prefect_ui:
         return flow_runs
 
-    await docket.add(
+    work_queue_becoming_ready = work_queue.status == WorkQueueStatus.NOT_READY
+    if work_queue_becoming_ready:
+        deployments_becoming_ready = True
+    else:
+        async with db.session_context() as session:
+            deployments_becoming_ready = (
+                await models.deployments.has_not_ready_deployments(
+                    session=session, work_queue_ids=[work_queue_id]
+                )
+            )
+
+    await schedule_readiness_update(
+        docket,
         mark_work_queues_ready,
         key=f"mark_work_queues_ready:{work_queue_id}",
+        becoming_ready=work_queue_becoming_ready,
     )(
         polled_work_queue_ids=[work_queue_id],
-        ready_work_queue_ids=(
-            [work_queue_id] if work_queue.status == WorkQueueStatus.NOT_READY else []
-        ),
+        ready_work_queue_ids=[work_queue_id] if work_queue_becoming_ready else [],
     )
 
-    await docket.add(
+    await schedule_readiness_update(
+        docket,
         mark_deployments_ready,
         key=f"mark_deployments_ready:work_queue:{work_queue_id}",
+        becoming_ready=deployments_becoming_ready,
     )(
         work_queue_ids=[work_queue_id],
     )

{prefect_client-3.9.1.dev7 → prefect_client-3.9.2.dev1}/src/prefect/server/api/workers.py

@@ -4,10 +4,11 @@ Routes for interacting with work queue objects.
 
 from dataclasses import dataclass
 from logging import Logger
-from typing import TYPE_CHECKING, Any, List, Optional
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, List, Optional, ParamSpec
 from uuid import UUID
 
 import sqlalchemy as sa
+from docket import Docket, Execution
 from fastapi import (
     Body,
     Depends,
@@ -67,6 +68,30 @@ router: PrefectRouter = PrefectRouter(
 )
 logger: Logger = get_logger("prefect.server.api.workers")
 
+P = ParamSpec("P")
+
+
+def schedule_readiness_update(
+    docket: Docket,
+    function: Callable[P, Awaitable[None]],
+    key: str,
+    *,
+    becoming_ready: bool,
+) -> Callable[P, Awaitable[Execution]]:
+    """
+    Schedule a keyed readiness update from a poll.
+
+    Polls are deduplicated by `key` so repeated polls don't pile up tasks. When
+    the poll would move something to READY, any pending task is replaced
+    instead: a previous attempt can be left pending with its key still known
+    (for example, when a worker's claim fails during a Redis disruption) and
+    would otherwise block every later poll until docket's `redelivery_timeout`.
+    """
+    if becoming_ready:
+        return docket.replace(function, now("UTC"), key)
+    return docket.add(function, key=key)
+
+
 _OSS_WORKER_CHANNEL_REQUIRED_CAPABILITIES: list[WorkerChannelCapability] = [
     WORKER_HEARTBEAT_CAPABILITY,
     WORK_POOL_SNAPSHOT_CAPABILITY,
@@ -851,6 +876,17 @@ async def get_scheduled_flow_runs(
             ]
             work_queue_ids = [wq.id for wq in work_queues]
 
+        ready_work_queue_ids = [
+            wq.id for wq in work_queues if wq.status == WorkQueueStatus.NOT_READY
+        ]
+        deployments_becoming_ready = bool(ready_work_queue_ids)
+        if not deployments_becoming_ready:
+            deployments_becoming_ready = (
+                await models.deployments.has_not_ready_deployments(
+                    session=session, work_queue_ids=[wq.id for wq in work_queues]
+                )
+            )
+
     async with db.session_context(begin_transaction=True) as session:
         queue_response = await models.workers.get_scheduled_flow_runs(
             session=session,
@@ -861,21 +897,29 @@ async def get_scheduled_flow_runs(
             limit=limit,
         )
 
-    await docket.add(
+    # Filtered polls only carry their own queues, so scope their keys to those
+    # queues; otherwise a poll for one subset could replace another's update.
+    key_scope = f"work_pool:{work_pool_id}"
+    if work_queue_ids is not None:
+        key_scope += ":" + ",".join(sorted(str(id) for id in set(work_queue_ids)))
+
+    await schedule_readiness_update(
+        docket,
         mark_work_queues_ready,
-        key=f"mark_work_queues_ready:work_pool:{work_pool_id}",
+        key=f"mark_work_queues_ready:{key_scope}",
+        becoming_ready=bool(ready_work_queue_ids),
     )(
         polled_work_queue_ids=[
             wq.id for wq in work_queues if wq.status != WorkQueueStatus.NOT_READY
         ],
-        ready_work_queue_ids=[
-            wq.id for wq in work_queues if wq.status == WorkQueueStatus.NOT_READY
-        ],
+        ready_work_queue_ids=ready_work_queue_ids,
     )
 
-    await docket.add(
+    await schedule_readiness_update(
+        docket,
         mark_deployments_ready,
-        key=f"mark_deployments_ready:work_pool:{work_pool_id}",
+        key=f"mark_deployments_ready:{key_scope}",
+        becoming_ready=deployments_becoming_ready,
     )(
         work_queue_ids=[wq.id for wq in work_queues],
     )