prefect-client 3.8.1.dev4__tar.gz → 3.8.2.dev1__tar.gz

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.8.1.dev4
+Version: 3.8.2.dev1
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -22,7 +22,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Requires-Python: <3.15,>=3.10
 Requires-Dist: amplitude-analytics<2.0.0,>=1.2.1
-Requires-Dist: anyio!=4.14.2,<5.0.0,>=4.4.0
+Requires-Dist: anyio<5.0.0,>=4.4.0
 Requires-Dist: asgi-lifespan<3.0,>=1.0
 Requires-Dist: cachetools<8.0,>=5.3
 Requires-Dist: cloudpickle<4.0,>=2.0

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2.dev1}/pyproject.toml

@@ -26,7 +26,7 @@ classifiers = [
 dependencies = [
     # Client dependencies
     "amplitude-analytics>=1.2.1,<2.0.0",
-    "anyio>=4.4.0,<5.0.0,!=4.14.2",
+    "anyio>=4.4.0,<5.0.0",
     "asgi-lifespan>=1.0,<3.0",
     "cachetools>=5.3,<8.0",
     "cloudpickle>=2.0,<4.0",

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

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.2.dev1"
+__build_date__ = "2026-08-01 08:50:43.060957+00:00"
+__git_commit__ = "ef4286181588e579f72854d9344f4a2f6d66a090"
+__dirty__ = False

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2.dev1}/src/prefect/_internal/control_listener.py

@@ -13,7 +13,7 @@ Protocol:
    one-shot env vars without connecting yet.
 3. The outermost `capture_sigterm()` calls `start()`, which connects back to
    the runner and spawns a daemon thread blocked on the socket.
-4. The runner writes a single-byte intent (`b"c"` today).
+4. The runner writes a single-byte intent (`b"c"`, `b"r"` or `b"q"`).
 5. If Prefect still owns the live SIGTERM bridge, the child writes `b"a"`,
    commits the intent for engine dispatch, and on Windows triggers
    `_thread.interrupt_main(SIGTERM)`.
@@ -37,10 +37,12 @@ from typing import Literal
 
 from prefect.utilities.engine import commit_control_intent_and_ack
 
-Intent = Literal["cancel"]
+Intent = Literal["cancel", "reschedule", "relinquish"]
 
 _INTENT_FOR_BYTE: dict[bytes, Intent] = {
     b"c": "cancel",
+    b"r": "reschedule",
+    b"q": "relinquish",
 }
 
 _intent: Intent | None = None

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2.dev1}/src/prefect/_internal/observers.py

@@ -1,8 +1,11 @@
 from __future__ import annotations
 
 import asyncio
+import logging
+import time
 import uuid
 from contextlib import AsyncExitStack
+from datetime import datetime
 from typing import Any, Protocol
 
 from prefect._flow_run_suspension import is_suspended_flow_run_state
@@ -17,9 +20,16 @@ from prefect.client.schemas.filters import (
 from prefect.client.schemas.objects import State, StateType
 from prefect.events.clients import PrefectEventSubscriber, get_events_subscriber
 from prefect.events.filters import EventFilter, EventNameFilter
+from prefect.exceptions import ObjectNotFound
 from prefect.logging.loggers import get_logger
 from prefect.utilities.services import critical_service_loop
 
+# How long to wait before warning that a suspension state is still unavailable,
+# how often to look initially, and the retry cap after the warning.
+SUSPENSION_CONFIRMATION_WARNING_AFTER = 30.0
+SUSPENSION_CONFIRMATION_INTERVAL = 0.5
+SUSPENSION_CONFIRMATION_MAX_INTERVAL = 10.0
+
 
 class OnCancellingCallback(Protocol):
     def __call__(self, flow_run_id: uuid.UUID) -> None: ...
@@ -33,6 +43,133 @@ class OnFailureCallback(Protocol):
     def __call__(self, flow_run_ids: set[uuid.UUID]) -> None: ...
 
 
+class _SuspensionWatch:
+    """Reconcile suspension events with durable states for one flow run."""
+
+    def __init__(
+        self,
+        flow_run_id: uuid.UUID,
+        client: PrefectClient,
+        on_suspended: OnSuspendedCallback,
+        logger: logging.Logger,
+    ) -> None:
+        self.flow_run_id = flow_run_id
+        self.is_suspended = False
+        self._client = client
+        self._on_suspended = on_suspended
+        self._logger = logger
+        self._initialized = asyncio.Event()
+        self._replay_checkpoint: datetime | None = None
+        self._confirmation_tasks: dict[uuid.UUID, asyncio.Task[None]] = {}
+        self._closed = False
+
+    def initialize(self, state: State | None) -> None:
+        """Set the initial server checkpoint and release waiting events."""
+        if not self._initialized.is_set():
+            self._replay_checkpoint = state.timestamp if state is not None else None
+            self._initialized.set()
+        self.notify_if_suspended(state)
+
+    def notify_if_suspended(self, state: State | None) -> None:
+        if (
+            not self.is_suspended
+            and state is not None
+            and is_suspended_flow_run_state(state)
+        ):
+            self.is_suspended = True
+            self._on_suspended(self.flow_run_id, state)
+
+    def observe(self, state_id: uuid.UUID, occurred: datetime) -> None:
+        """Confirm a new suspension event without blocking event consumption."""
+        if self._closed or self.is_suspended:
+            return
+        if state_id in self._confirmation_tasks:
+            return
+
+        task = asyncio.create_task(self._confirm(state_id, occurred))
+        self._confirmation_tasks[state_id] = task
+        task.add_done_callback(
+            lambda completed, state_id=state_id: self._confirmation_done(
+                state_id, completed
+            )
+        )
+
+    async def _confirm(self, state_id: uuid.UUID, occurred: datetime) -> None:
+        await self._initialized.wait()
+        if self._closed or self.is_suspended:
+            return
+        if self._replay_checkpoint is not None and occurred <= self._replay_checkpoint:
+            self._logger.debug(
+                "Ignoring replayed suspension event for flow run %s that occurred"
+                " at or before the initial server state.",
+                self.flow_run_id,
+            )
+            return
+
+        warning_deadline = time.monotonic() + SUSPENSION_CONFIRMATION_WARNING_AFTER
+        retry_interval = SUSPENSION_CONFIRMATION_INTERVAL
+        warned = False
+        last_error: Exception | None = None
+
+        while not self._closed and not self.is_suspended:
+            try:
+                state = await self._client.read_flow_run_state(state_id)
+            except ObjectNotFound:
+                pass
+            except Exception as exc:
+                last_error = exc
+            else:
+                if state.state_details.flow_run_id not in (None, self.flow_run_id):
+                    self._logger.warning(
+                        "Suspension event for flow run %s referred to state %s owned"
+                        " by flow run %s.",
+                        self.flow_run_id,
+                        state_id,
+                        state.state_details.flow_run_id,
+                    )
+                    return
+                self.notify_if_suspended(state)
+                return
+
+            if not warned and time.monotonic() >= warning_deadline:
+                self._logger.warning(
+                    "Received a suspension event for flow run %s, but state %s has"
+                    " not become readable within %s seconds; continuing to retry.",
+                    self.flow_run_id,
+                    state_id,
+                    SUSPENSION_CONFIRMATION_WARNING_AFTER,
+                    exc_info=last_error,
+                )
+                warned = True
+
+            await asyncio.sleep(retry_interval)
+            if warned:
+                retry_interval = min(
+                    max(retry_interval * 2, SUSPENSION_CONFIRMATION_INTERVAL),
+                    SUSPENSION_CONFIRMATION_MAX_INTERVAL,
+                )
+
+    def _confirmation_done(self, state_id: uuid.UUID, task: asyncio.Task[None]) -> None:
+        self._confirmation_tasks.pop(state_id, None)
+        if task.cancelled():
+            return
+        if error := task.exception():
+            self._logger.error(
+                "Suspension confirmation failed for flow run %s and state %s.",
+                self.flow_run_id,
+                state_id,
+                exc_info=error,
+            )
+
+    def cancel(self) -> tuple[asyncio.Task[None], ...]:
+        self._closed = True
+        tasks = tuple(self._confirmation_tasks.values())
+        self._confirmation_tasks.clear()
+        for task in tasks:
+            task.cancel()
+        return tasks
+
+
 class FlowRunCancellingObserver:
     def __init__(
         self,
@@ -283,35 +420,59 @@ class FlowRunSuspendingObserver:
             self._event_filter = EventFilter(
                 event=EventNameFilter(name=["prefect.flow-run.Suspended"])
             )
-        self._in_flight_flow_run_ids: set[uuid.UUID] = set()
         self._events_subscriber: PrefectEventSubscriber | None
         self._exit_stack = AsyncExitStack()
         self._consumer_task: asyncio.Task[None] | None = None
         self._polling_task: asyncio.Task[None] | None = None
         self._is_shutting_down = False
         self._client: PrefectClient | None = None
-        self._suspended_flow_run_ids: set[uuid.UUID] = set()
+        self._watches: dict[uuid.UUID, _SuspensionWatch] = {}
+
+    @property
+    def _in_flight_flow_run_ids(self) -> set[uuid.UUID]:
+        return set(self._watches)
 
     def add_in_flight_flow_run_id(self, flow_run_id: uuid.UUID):
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Please use `async with` to initialize the observer."
+            )
         self.logger.debug("Adding in-flight flow run ID: %s", flow_run_id)
-        self._in_flight_flow_run_ids.add(flow_run_id)
+        if flow_run_id not in self._watches:
+            watch = self._watches[flow_run_id] = self._create_watch(flow_run_id)
+            watch.initialize(None)
+
+    def _create_watch(self, flow_run_id: uuid.UUID) -> _SuspensionWatch:
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Please use `async with` to initialize the observer."
+            )
+        return _SuspensionWatch(
+            flow_run_id=flow_run_id,
+            client=self._client,
+            on_suspended=self.on_suspended,
+            logger=self.logger,
+        )
 
     def remove_in_flight_flow_run_id(self, flow_run_id: uuid.UUID):
         self.logger.debug("Removing in-flight flow run ID: %s", flow_run_id)
-        self._in_flight_flow_run_ids.discard(flow_run_id)
-        self._suspended_flow_run_ids.discard(flow_run_id)
+        if watch := self._watches.pop(flow_run_id, None):
+            watch.cancel()
 
     async def watch_flow_run_id(self, flow_run_id: uuid.UUID) -> None:
-        self.add_in_flight_flow_run_id(flow_run_id)
         if self._client is None:
             raise RuntimeError(
                 "Client not initialized. Please use `async with` to initialize the observer."
             )
+        self.logger.debug("Adding in-flight flow run ID: %s", flow_run_id)
+        if flow_run_id not in self._watches:
+            self._watches[flow_run_id] = self._create_watch(flow_run_id)
         retry_interval = max(min(self.polling_interval, 1.0), 0.01)
         attempts = 0
 
         while not self._is_shutting_down:
-            if flow_run_id in self._suspended_flow_run_ids:
+            watch = self._watches.get(flow_run_id)
+            if watch is None or watch.is_suspended:
                 return
 
             try:
@@ -328,26 +489,14 @@ class FlowRunSuspendingObserver:
                 await asyncio.sleep(retry_interval)
                 continue
 
-            self._notify_if_suspended_state(flow_run_id, flow_run.state)
+            watch.initialize(flow_run.state)
             return
 
     def _notify_if_suspended_state(
         self, flow_run_id: uuid.UUID, state: State | None
     ) -> None:
-        if state is not None and is_suspended_flow_run_state(state):
-            self._suspended_flow_run_ids.add(flow_run_id)
-            self.on_suspended(flow_run_id, state)
-
-    async def _notify_if_suspended(self, flow_run_id: uuid.UUID) -> None:
-        if self._client is None:
-            raise RuntimeError(
-                "Client not initialized. Please use `async with` to initialize the observer."
-            )
-        if flow_run_id in self._suspended_flow_run_ids:
-            return
-
-        flow_run = await self._client.read_flow_run(flow_run_id)
-        self._notify_if_suspended_state(flow_run_id, flow_run.state)
+        if watch := self._watches.get(flow_run_id):
+            watch.notify_if_suspended(state)
 
     async def _consume_events(self):
         if self._events_subscriber is None:
@@ -361,9 +510,14 @@ class FlowRunSuspendingObserver:
                         "prefect.flow-run.", ""
                     )
                 )
-                if flow_run_id not in self._in_flight_flow_run_ids:
+                watch = self._watches.get(flow_run_id)
+                if watch is None:
                     continue
-                await self._notify_if_suspended(flow_run_id)
+
+                # State change events carry the ID of the state they report, so the
+                # event identifies the exact transition to confirm. Confirmation is
+                # done in a separate task to keep consuming events while we wait.
+                watch.observe(event.id, event.occurred)
             except ValueError:
                 self.logger.warning(
                     "Received event with invalid flow run ID: %s",
@@ -412,7 +566,11 @@ class FlowRunSuspendingObserver:
                 "Client not initialized. Please use `async with` to initialize the observer."
             )
 
-        flow_run_ids = self._in_flight_flow_run_ids - self._suspended_flow_run_ids
+        flow_run_ids = {
+            flow_run_id
+            for flow_run_id, watch in self._watches.items()
+            if not watch.is_suspended
+        }
         if not flow_run_ids:
             return
 
@@ -434,8 +592,7 @@ class FlowRunSuspendingObserver:
 
         for flow_run in suspended_flow_runs:
             if flow_run.state:
-                self._suspended_flow_run_ids.add(flow_run.id)
-                self.on_suspended(flow_run.id, flow_run.state)
+                self._notify_if_suspended_state(flow_run.id, flow_run.state)
 
     async def __aenter__(self):
         try:
@@ -470,6 +627,10 @@ class FlowRunSuspendingObserver:
     async def __aexit__(self, *exc_info: Any):
         self.logger.debug("Shutting down FlowRunSuspendingObserver")
         self._is_shutting_down = True
+        tasks = [task for watch in self._watches.values() for task in watch.cancel()]
+        self._watches.clear()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
         await self._exit_stack.__aexit__(*exc_info)
         if self._consumer_task is not None:
             self._consumer_task.cancel()

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2.dev1}/src/prefect/blocks/core.py

@@ -424,6 +424,14 @@ class Block(BaseModel, ABC):
     def ser_model(
         self, handler: SerializerFunctionWrapHandler, info: SerializationInfo
     ) -> Any:
+        if info.context and info.context.get("serialize_blocks_as_references"):
+            if self._block_document_id is None:
+                raise BlockNotSavedError(
+                    "Block must be saved with `.save()` before it can be used as a "
+                    "deployment parameter."
+                )
+            return {"$ref": {"block_document_id": str(self._block_document_id)}}
+
         jsonable_self = handler(self)
         if (ctx := info.context) and ctx.get("include_secrets") is True:
             # Add serialization mode to context so handle_secret_render knows how to process nested models

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2.dev1}/src/prefect/client/orchestration/_flow_runs/client.py

@@ -416,6 +416,34 @@ class FlowRunClient(BaseClient):
         )
         return result
 
+    def read_flow_run_state(self, flow_run_state_id: "UUID") -> "State":
+        """
+        Read a flow run state by ID.
+
+        Args:
+            flow_run_state_id: The flow run state ID.
+
+        Returns:
+            A State model representation of the flow run state.
+
+        Raises:
+            ObjectNotFound: If the flow run state does not exist.
+        """
+        try:
+            response = self.request(
+                "GET",
+                "/flow_run_states/{id}",
+                path_params={"id": flow_run_state_id},
+            )
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code == 404:
+                raise ObjectNotFound(http_exc=exc) from exc
+            raise
+
+        from prefect.states import State
+
+        return State.model_validate(response.json())
+
     def read_flow_run_states(self, flow_run_id: "UUID") -> "list[State]":
         """
         Query for the states of a flow run
@@ -916,6 +944,34 @@ class FlowRunAsyncClient(BaseAsyncClient):
         )
         return result
 
+    async def read_flow_run_state(self, flow_run_state_id: "UUID") -> "State":
+        """
+        Read a flow run state by ID.
+
+        Args:
+            flow_run_state_id: The flow run state ID.
+
+        Returns:
+            A State model representation of the flow run state.
+
+        Raises:
+            ObjectNotFound: If the flow run state does not exist.
+        """
+        try:
+            response = await self.request(
+                "GET",
+                "/flow_run_states/{id}",
+                path_params={"id": flow_run_state_id},
+            )
+        except httpx.HTTPStatusError as exc:
+            if exc.response.status_code == 404:
+                raise ObjectNotFound(http_exc=exc) from exc
+            raise
+
+        from prefect.states import State
+
+        return State.model_validate(response.json())
+
     async def read_flow_run_states(self, flow_run_id: "UUID") -> "list[State]":
         """
         Query for the states of a flow run

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2.dev1}/src/prefect/client/schemas/filters.py

@@ -2,10 +2,10 @@
 Schemas that define Prefect REST API filtering operations.
 """
 
-from typing import List, Optional
+from typing import ClassVar, List, Optional
 from uuid import UUID
 
-from pydantic import Field
+from pydantic import ConfigDict, Field
 
 from prefect._internal.schemas.bases import PrefectBaseModel
 from prefect.client.schemas.objects import StateType
@@ -20,6 +20,12 @@ class Operator(AutoEnum):
     or_ = AutoEnum.auto()
 
 
+class _FlowRunFilterBaseModel(PrefectBaseModel):
+    """Base model for flow run filters that rejects unknown fields."""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+
 class OperatorMixin:
     """Base model for Prefect filters that combines criteria with a user-provided operator"""
 
@@ -87,7 +93,7 @@ class FlowFilter(PrefectBaseModel, OperatorMixin):
     )
 
 
-class FlowRunFilterId(PrefectBaseModel):
+class FlowRunFilterId(_FlowRunFilterBaseModel):
     """Filter by FlowRun.id."""
 
     any_: Optional[List[UUID]] = Field(
@@ -98,7 +104,7 @@ class FlowRunFilterId(PrefectBaseModel):
     )
 
 
-class FlowRunFilterName(PrefectBaseModel):
+class FlowRunFilterName(_FlowRunFilterBaseModel):
     """Filter by `FlowRun.name`."""
 
     any_: Optional[List[str]] = Field(
@@ -118,7 +124,7 @@ class FlowRunFilterName(PrefectBaseModel):
     )
 
 
-class FlowRunFilterTags(PrefectBaseModel, OperatorMixin):
+class FlowRunFilterTags(_FlowRunFilterBaseModel, OperatorMixin):
     """Filter by `FlowRun.tags`."""
 
     all_: Optional[List[str]] = Field(
@@ -139,7 +145,7 @@ class FlowRunFilterTags(PrefectBaseModel, OperatorMixin):
     )
 
 
-class FlowRunFilterDeploymentId(PrefectBaseModel, OperatorMixin):
+class FlowRunFilterDeploymentId(_FlowRunFilterBaseModel, OperatorMixin):
     """Filter by `FlowRun.deployment_id`."""
 
     any_: Optional[List[UUID]] = Field(
@@ -151,7 +157,7 @@ class FlowRunFilterDeploymentId(PrefectBaseModel, OperatorMixin):
     )
 
 
-class FlowRunFilterWorkQueueName(PrefectBaseModel, OperatorMixin):
+class FlowRunFilterWorkQueueName(_FlowRunFilterBaseModel, OperatorMixin):
     """Filter by `FlowRun.work_queue_name`."""
 
     any_: Optional[List[str]] = Field(
@@ -165,7 +171,7 @@ class FlowRunFilterWorkQueueName(PrefectBaseModel, OperatorMixin):
     )
 
 
-class FlowRunFilterStateType(PrefectBaseModel):
+class FlowRunFilterStateType(_FlowRunFilterBaseModel):
     """Filter by `FlowRun.state_type`."""
 
     any_: Optional[List[StateType]] = Field(
@@ -176,7 +182,7 @@ class FlowRunFilterStateType(PrefectBaseModel):
     )
 
 
-class FlowRunFilterStateName(PrefectBaseModel):
+class FlowRunFilterStateName(_FlowRunFilterBaseModel):
     any_: Optional[List[str]] = Field(
         default=None, description="A list of flow run state names to include"
     )
@@ -185,7 +191,7 @@ class FlowRunFilterStateName(PrefectBaseModel):
     )
 
 
-class FlowRunFilterState(PrefectBaseModel, OperatorMixin):
+class FlowRunFilterState(_FlowRunFilterBaseModel, OperatorMixin):
     type: Optional[FlowRunFilterStateType] = Field(
         default=None, description="Filter criteria for `FlowRun` state type"
     )
@@ -194,7 +200,7 @@ class FlowRunFilterState(PrefectBaseModel, OperatorMixin):
     )
 
 
-class FlowRunFilterFlowVersion(PrefectBaseModel):
+class FlowRunFilterFlowVersion(_FlowRunFilterBaseModel):
     """Filter by `FlowRun.flow_version`."""
 
     any_: Optional[List[str]] = Field(
@@ -202,7 +208,7 @@ class FlowRunFilterFlowVersion(PrefectBaseModel):
     )
 
 
-class FlowRunFilterStartTime(PrefectBaseModel):
+class FlowRunFilterStartTime(_FlowRunFilterBaseModel):
     """Filter by `FlowRun.start_time`."""
 
     before_: Optional[DateTime] = Field(
@@ -218,7 +224,7 @@ class FlowRunFilterStartTime(PrefectBaseModel):
     )
 
 
-class FlowRunFilterEndTime(PrefectBaseModel):
+class FlowRunFilterEndTime(_FlowRunFilterBaseModel):
     """Filter by `FlowRun.end_time`."""
 
     before_: Optional[DateTime] = Field(
@@ -234,7 +240,7 @@ class FlowRunFilterEndTime(PrefectBaseModel):
     )
 
 
-class FlowRunFilterExpectedStartTime(PrefectBaseModel):
+class FlowRunFilterExpectedStartTime(_FlowRunFilterBaseModel):
     """Filter by `FlowRun.expected_start_time`."""
 
     before_: Optional[DateTime] = Field(
@@ -247,7 +253,7 @@ class FlowRunFilterExpectedStartTime(PrefectBaseModel):
     )
 
 
-class FlowRunFilterNextScheduledStartTime(PrefectBaseModel):
+class FlowRunFilterNextScheduledStartTime(_FlowRunFilterBaseModel):
     """Filter by `FlowRun.next_scheduled_start_time`."""
 
     before_: Optional[DateTime] = Field(
@@ -266,7 +272,7 @@ class FlowRunFilterNextScheduledStartTime(PrefectBaseModel):
     )
 
 
-class FlowRunFilterParentFlowRunId(PrefectBaseModel, OperatorMixin):
+class FlowRunFilterParentFlowRunId(_FlowRunFilterBaseModel, OperatorMixin):
     """Filter for subflows of the given flow runs"""
 
     any_: Optional[List[UUID]] = Field(
@@ -274,7 +280,7 @@ class FlowRunFilterParentFlowRunId(PrefectBaseModel, OperatorMixin):
     )
 
 
-class FlowRunFilterParentTaskRunId(PrefectBaseModel, OperatorMixin):
+class FlowRunFilterParentTaskRunId(_FlowRunFilterBaseModel, OperatorMixin):
     """Filter by `FlowRun.parent_task_run_id`."""
 
     any_: Optional[List[UUID]] = Field(
@@ -286,7 +292,7 @@ class FlowRunFilterParentTaskRunId(PrefectBaseModel, OperatorMixin):
     )
 
 
-class FlowRunFilterIdempotencyKey(PrefectBaseModel):
+class FlowRunFilterIdempotencyKey(_FlowRunFilterBaseModel):
     """Filter by FlowRun.idempotency_key."""
 
     any_: Optional[List[str]] = Field(
@@ -297,7 +303,7 @@ class FlowRunFilterIdempotencyKey(PrefectBaseModel):
     )
 
 
-class FlowRunFilterCreatedBy(PrefectBaseModel, OperatorMixin):
+class FlowRunFilterCreatedBy(_FlowRunFilterBaseModel, OperatorMixin):
     """Filter by `FlowRun.created_by`."""
 
     id_: Optional[List[UUID]] = Field(
@@ -318,7 +324,7 @@ class FlowRunFilterCreatedBy(PrefectBaseModel, OperatorMixin):
     )
 
 
-class FlowRunFilter(PrefectBaseModel, OperatorMixin):
+class FlowRunFilter(_FlowRunFilterBaseModel, OperatorMixin):
     """Filter flow runs. Only flow runs matching all criteria will be returned"""
 
     id: Optional[FlowRunFilterId] = Field(

{prefect_client-3.8.1.dev4 → prefect_client-3.8.2.dev1}/src/prefect/concurrency/AGENTS.md

@@ -40,5 +40,5 @@ Layered — public → internal → services, with leases and events as cross-cu
 
 - **Service singleton is keyed on `frozenset(names)`.** Passing the same names in different order reuses the same singleton; passing a strict subset creates a different singleton. Each unique name-set gets its own queue.
 - **Lease renewal runs on a daemon thread.** The thread copies the caller's context variables for settings and logging context, then uses the standard `get_client(sync_client=True)` path instead of lease-specific async-client cloning. Sync callers join the thread briefly on exit; async callers only signal the thread to stop so the event loop is not blocked.
-- **Cancellation during acquire or release** — if a `CancelledError` is raised either during slot acquisition or during `release_concurrency_slots_with_lease` in the `finally` block, the lease ID is appended to `ConcurrencyContext.cleanup_lease_ids`. `ConcurrencyContext.__exit__` releases them via a sync client. If `ConcurrencyContext` is not active, those leases are abandoned until server-side expiry.
+- **Cleanup leases are recorded at acquisition, not reactively on cancellation.** `ConcurrencyContext.cleanup_lease_ids` gets the lease ID the moment a lease is granted, and it's discarded again after a successful release. This closes a race where cancellation fires the instant the lease is granted — before the release call is even reached — which would otherwise leak the slot. `ConcurrencyContext.__exit__` releases any leases still in the list via a sync client; if `ConcurrencyContext` is not active, those leases are abandoned until server-side expiry.
 - **`v1/` subdirectory** contains the legacy slot API (no lease model). New code should use the top-level `concurrency()` / `rate_limit()` APIs.