prefect-client 3.6.27.dev5__tar.gz → 3.6.28.dev2__tar.gz

{prefect_client-3.6.27.dev5 → prefect_client-3.6.28.dev2}/PKG-INFO

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

prefect_client-3.6.28.dev2/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.28.dev2"
+__build_date__ = "2026-04-21 08:44:07.216635+00:00"
+__git_commit__ = "6f89b6d66878624ed5e572f85370cb518b630208"
+__dirty__ = False

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

@@ -36,7 +36,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 +414,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

{prefect_client-3.6.27.dev5 → prefect_client-3.6.28.dev2}/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.dev5 → prefect_client-3.6.28.dev2}/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.dev5 → prefect_client-3.6.28.dev2}/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.dev5 → prefect_client-3.6.28.dev2}/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.dev5 → prefect_client-3.6.28.dev2}/src/prefect/task_runners.py

@@ -616,14 +616,19 @@ class _UnpicklingFuture(concurrent.futures.Future[R]):
 
     def __init__(self, wrapped_future: concurrent.futures.Future[bytes]):
         self.wrapped_future = wrapped_future
+        self._deserialization_error: BaseException | None = None
 
     def result(self, timeout: float | None = None) -> R:
+        if self._deserialization_error is not None:
+            raise self._deserialization_error
         pickled_result = self.wrapped_future.result(timeout)
         import cloudpickle
 
         return cloudpickle.loads(pickled_result)
 
     def exception(self, timeout: float | None = None) -> BaseException | None:
+        if self._deserialization_error is not None:
+            return self._deserialization_error
         return self.wrapped_future.exception(timeout)
 
     def done(self) -> bool:
@@ -639,10 +644,13 @@ class _UnpicklingFuture(concurrent.futures.Future[R]):
         self, fn: Callable[[concurrent.futures.Future[R]], object]
     ) -> None:
         def _fn(wrapped_future: concurrent.futures.Future[bytes]) -> None:
-            import cloudpickle
+            try:
+                import cloudpickle
 
-            result = cloudpickle.loads(wrapped_future.result())
-            fn(result)
+                cloudpickle.loads(wrapped_future.result())
+            except Exception as e:
+                self._deserialization_error = e
+            fn(self)
 
         return self.wrapped_future.add_done_callback(_fn)
 

prefect_client-3.6.28.dev2/src/prefect/utilities/AGENTS.md

@@ -0,0 +1,57 @@
+# Utilities
+
+General-purpose helpers and cross-cutting tools used throughout the Prefect SDK and server.
+
+## Purpose & Scope
+
+Shared utilities: data manipulation, async helpers, schema tooling, callables introspection, and infrastructure helpers. These modules have no common theme beyond being broadly reused — if something is self-contained and used across two or more subsystems, it lives here.
+
+Does NOT include: server-specific utilities (`server/utilities/`), concurrency slot management (`concurrency/`), or logging infrastructure (`logging/`).
+
+## Cross-cutting rules
+
+- **Don't add server imports to utility modules.** Everything here is used client-side too. `HydrationContext.build()` in `schema_tools/` is an explicit, documented exception (async, server-only); no new server-touching code should creep into other modules.
+
+## Subpackages (focused intent nodes)
+
+Each subpackage owns its own `AGENTS.md` with entry points and pitfalls specific to that domain.
+
+- `schema_tools/` → Hydration and validation of `__prefect_kind` template structures (see `schema_tools/AGENTS.md`)
+- `processutils/` → Subprocess execution, output streaming, and command serialization (see `processutils/AGENTS.md`)
+- `callables/` → Function signature introspection, parameter coercion, parameter schema generation (see `callables/AGENTS.md`)
+- `asyncutils/` → Async/sync bridging, thread coordination, concurrency primitives (see `asyncutils/AGENTS.md`)
+- `templating/` → Placeholder detection and value application for Prefect's `{{ }}` templating (see `templating/AGENTS.md`)
+- `engine/` → Result-to-state linking, SIGTERM bridge management, and control-intent coordination (see `engine/AGENTS.md`)
+- `filesystem/` → File filtering, path normalization, `tmpchdir` (see `filesystem/AGENTS.md`)
+
+## Flat modules
+
+These modules have no dedicated intent node yet. Promote any one of them to a subpackage (`foo.py` → `foo/__init__.py` + `foo/AGENTS.md`) when non-obvious invariants accrue — the import path is preserved.
+
+- `annotations.py` — Custom Prefect type annotations used in flow/task signatures (`unmapped`, `allow_failure`, `quote`, `NotSet`)
+- `collections.py` — Extended collection helpers (`visit_collection`, `flatten`, `remove_nested_keys`)
+- `dispatch.py` — Dynamic type dispatch registry
+- `importtools.py` — Dynamic imports, aliased module loading, script-to-module conversion
+- `pydantic.py` — Pydantic v1/v2 compatibility shims, custom serializers, type dispatch integration
+- `hashing.py` — Stable hashing (`stable_hash`, `file_hash`, `hash_objects`)
+- `dockerutils.py` — Docker image building, Python version detection, Docker client helpers
+- `timeout.py` — Timeout context managers for async/sync code
+- `services.py` — Client metrics server and resilient service loop with backoff
+- `visualization.py` — Flow/task graph visualization via Graphviz
+- `urls.py` — URL validation and UI path formatting
+- `names.py` — Slug generation and obfuscation helpers
+- `math.py` — Distribution sampling and clamping utilities
+- `text.py` — String truncation and fuzzy matching
+- `context.py` — Context variable accessors
+- `compat.py` — Python version compatibility shims
+- `slugify.py` — Thin wrapper around `unicode-slugify`
+- `generics.py` — Generic type validation
+- `render_swagger.py` — MkDocs plugin for rendering Swagger/OpenAPI schemas
+
+Private (`_`-prefixed):
+
+- `_ast.py` — AST-based flow-decorator discovery in source files
+- `_engine.py` — Naming and hook-resolution helpers for custom flow/task run names
+- `_git.py` — Git origin/branch introspection for deployment metadata
+- `_infrastructure_exit_codes.py` — Registry of exit-code explanations for infrastructure processes
+- `_deprecated.py` — Legacy wrappers retained for backward compat

prefect_client-3.6.28.dev2/src/prefect/utilities/asyncutils/AGENTS.md

@@ -0,0 +1,20 @@
+# asyncutils
+
+Async/sync bridging, thread coordination, and concurrency primitives used throughout the SDK.
+
+## Purpose & Scope
+
+Bridges Prefect's async engine with user-written sync code (and vice versa) without deadlocking the event loop or losing context. Also provides a handful of async-aware primitives (`LazySemaphore`, timed task creation) used by higher layers.
+
+## Entry Points
+
+- `run_coro_as_sync(coro)` — run an async coroutine from sync code, reusing the global loop when available.
+- `run_sync_in_worker_thread(fn, *args, **kwargs)` — execute a blocking sync callable off the event loop.
+- `sync_compatible(fn)` — decorator letting a single `async def` be called from both sync and async callers.
+- `LazySemaphore` — a semaphore whose capacity is resolved on first acquisition (used for managing open-file limits at import time without evaluating `resource` limits eagerly).
+- `gather(*calls)` / `create_gather_task_group()` — run a collection of coroutine-returning callables concurrently and collect their results positionally.
+- `create_task(coro)` — create an `asyncio.Task` with Prefect's logging-and-cancellation-friendly wiring.
+
+## Pitfalls
+
+_No pitfalls documented yet. Add here when non-obvious behaviors surface during debugging — especially around context propagation, thread-to-loop hand-off, and cancellation semantics, which tend to bite in subtle ways._

prefect_client-3.6.28.dev2/src/prefect/utilities/callables/AGENTS.md

@@ -0,0 +1,22 @@
+# callables
+
+Function signature introspection, parameter coercion, and JSON Schema generation for flow and task parameters.
+
+## Purpose & Scope
+
+Inspects user-written flow/task functions to produce:
+- Bindable `args`/`kwargs` from a parameters dict (`parameters_to_args_kwargs`, `get_call_parameters`).
+- JSON Schema representations of function signatures for UI parameter forms and server-side validation (`parameter_schema`).
+
+## Entry Points
+
+- `parameters_to_args_kwargs(fn, parameters) -> (args, kwargs)` — split a parameters dict into positional and keyword slots based on the function's signature.
+- `get_call_parameters(fn, call_args, call_kwargs) -> dict` — inverse: bind actual call args/kwargs into a parameters dict.
+- `parameter_schema(fn) -> ParameterSchema` — introspect the function signature into a Pydantic-backed JSON Schema.
+
+## Pitfalls
+
+- **`parameters_to_args_kwargs` adjusts the positional/keyword split based on the wrapper's signature, not the wrapped function's.** For `@functools.wraps`-decorated callables, it inspects the *wrapper* (via `follow_wrapped=False`) to count how many positional slots are actually available and routes excess parameters to `**kwargs`. This means `args` and `kwargs` from this function are shaped for the *wrapper* call, not the inner function — callers must not assume all POSITIONAL_OR_KEYWORD parameters end up in `args`.
+- **`parameters_to_args_kwargs` skips the positional-to-keyword rewrite entirely when the function signature contains `*args`.** Inserting KEYWORD_ONLY parameters before a VAR_POSITIONAL parameter is invalid in Python, so the original signature is used as-is in that case.
+- **Passing the same key in both an explicit parameter and a `**kwargs` dict raises `TypeError`.** `parameters_to_args_kwargs` detects when a VAR_KEYWORD (`**kwargs`) dict contains a key that also appears as an explicit parameter and raises rather than silently letting the variadic entry win. Exception: POSITIONAL_ONLY parameters are exempt because `fn(1, **{'a': 2})` is legal when `a` is positional-only.
+- **`generate_parameter_schema` silently downgrades unsupported parameter types to `Any`.** When a parameter's type raises `ValueError`, `TypeError`, or `PydanticInvalidForJsonSchema` during JSON schema generation (e.g., `Callable`, custom types Pydantic can't serialize), the type is replaced with `Any` in the output schema without warning. If a flow parameter shows up as `Any` in the schema, the declared type is not JSON-schema-compatible.

prefect_client-3.6.28.dev2/src/prefect/utilities/engine/AGENTS.md

@@ -0,0 +1,31 @@
+# engine
+
+Result-to-state linking, SIGTERM bridge management, and helpers shared by the flow/task engines.
+
+## Purpose & Scope
+
+Two responsibilities live here:
+
+1. **Result-to-state linking** — glue between Python return values (which callers receive) and the `State` objects that represent them on the server. Maintains the identity-keyed `run_results` map inside `EngineContext` and exposes safe accessors.
+
+2. **SIGTERM bridge** — installs and tears down Prefect's SIGTERM handler (`TerminationSignal`), coordinates control-intent acknowledgement with the runner, and exposes locked helpers so the engine can atomically commit cancellation intent before signalling readiness to the runner.
+
+Naming and hook-resolution helpers for custom flow/task run names live in sibling `../_engine.py` (flat module), not here.
+
+## Entry Points
+
+**Result linking:**
+- `link_state_to_result(state, result, run_type)` — associate a `State` with a Python object under a specific `RunType` for later lookup via `get_state_for_result`.
+- `link_state_to_flow_run_result(state, result)` / `link_state_to_task_run_result(state, result)` — scoped variants used by the flow and task engines respectively.
+- `get_state_for_result(obj) -> tuple[State, RunType] | None` — identity-verified lookup that handles `id()` collisions safely.
+
+**SIGTERM bridge:**
+- `capture_sigterm()` — context manager that installs Prefect's SIGTERM bridge; outermost scope installs it, nested scopes reuse or reinstall as needed. The runner's control listener connects only while this context is active.
+- `is_prefect_sigterm_handler_installed() -> bool` — check (under lock) whether Prefect's bridge is the active SIGTERM handler.
+- `can_ack_control_intent() -> bool` — check (under the same lock) whether the child can safely acknowledge a queued control intent.
+- `commit_control_intent_and_ack(commit_intent, clear_intent, send_ack, trigger_cancel)` — atomically commit a control intent and write the ack byte to the runner, all under `_prefect_sigterm_bridge_lock`.
+
+## Pitfalls
+
+- **Never access `EngineContext.run_results` directly via `id(obj)`.** Always call `get_state_for_result(obj)` — the accessor verifies object identity in addition to the ID match, avoiding false hits when Python reuses an id for a different object after GC.
+- **All SIGTERM-state reads and writes must hold `_prefect_sigterm_bridge_lock`.** The lock is a `threading.RLock` that serializes handler install/restore with ack writes. Reading `signal.getsignal(SIGTERM)` outside the lock creates a TOCTOU race where the handler is restored after the child decides it's safe to ack but before the runner observes the ack byte.

prefect_client-3.6.28.dev2/src/prefect/utilities/filesystem/AGENTS.md

@@ -0,0 +1,17 @@
+# filesystem
+
+File path utilities, pathspec-based filtering, and local filesystem context managers.
+
+## Purpose & Scope
+
+Path normalization, file filtering compatible with `.gitignore`/`.prefectignore`-style pattern lists (`filter_files`), open-file-limit introspection (`get_open_file_limit`), and a `tmpchdir` context manager for scoped working-directory changes.
+
+## Entry Points
+
+- `filter_files(root, ignore_patterns, include_dirs=True) -> set[str]` — return the set of paths under `root` that should be *ignored* according to pathspec patterns. Intended as input to `shutil.copytree`'s `ignore` callback.
+- `tmpchdir(path)` — context manager that `chdir`s into `path` and restores the previous cwd on exit.
+- `get_open_file_limit() -> int` — platform-specific maximum open-file count, with a conservative Windows default.
+
+## Pitfalls
+
+- **`filter_files` with `include_dirs=True` (the default) always includes all ancestor directories of matched files**, even if those directories weren't directly matched by the ignore patterns. This ensures `shutil.copytree`'s `ignore_func` doesn't skip directories containing files that should be copied. Side effect: callers expecting only pathspec-matched entries will receive additional directory paths. The parent-dir expansion does NOT run when `include_dirs=False`.

prefect_client-3.6.28.dev2/src/prefect/utilities/processutils/AGENTS.md

@@ -0,0 +1,22 @@
+# processutils
+
+Subprocess execution, output streaming, command serialization, and signal forwarding.
+
+## Purpose & Scope
+
+Cross-platform subprocess primitives used by workers, runners, bundle execution, and the CLI. Handles process launch (`run_process`), output consumption (`consume_process_output`, `stream_text`), and platform-neutral command serialization (`command_to_string`, `command_from_string`).
+
+## Entry Points
+
+- `sanitize_subprocess_env(env) -> dict[str, str]` — strip `None` values from an env mapping before passing to subprocess launch APIs; `None` means "omit this key", which `subprocess` and `anyio.open_process` do not accept.
+- `run_process(command, ...)` — async subprocess runner with output streaming and signal forwarding.
+- `consume_process_output(process, stdout_sink, stderr_sink)` — drain a running process's streams into writers.
+- `stream_text(source, *sinks)` — fan out a text stream to multiple sinks.
+- `command_to_string(command: list[str]) -> str` / `command_from_string(s: str) -> list[str]` — platform-neutral serialize/deserialize of command arrays for storage and cross-platform bundles.
+- `get_sys_executable() -> str` — `sys.executable` with platform-appropriate handling (see pitfalls).
+
+## Pitfalls
+
+- **Non-UTF-8 subprocess output is silently replaced.** `consume_process_output` and `stream_text` (via `TextReceiveStream(errors="replace")`) replace invalid bytes with the Unicode replacement character `\ufffd` rather than raising. If captured output contains `\ufffd`, the subprocess emitted bytes that were not valid UTF-8.
+- **`command_to_string` always uses POSIX quoting (`shlex.join`), even on Windows.** This is intentional for platform-neutral storage — bundle commands are serialized by one platform and may be deserialized by another. `command_from_string` uses a dual-path approach: if the string was POSIX-serialized by Prefect (round-trips cleanly through `shlex.split`/`shlex.join`), it uses POSIX parsing; otherwise it falls back to native Windows command-line parsing (`CommandLineToArgvW`). Do not use `" ".join(command)` or `shlex.split(command)` directly when working with stored Prefect commands — use these helpers instead.
+- **`get_sys_executable()` no longer quotes the Python path on Windows.** It previously returned `'"path/to/python"'` (with embedded quotes) on Windows; now it returns the raw path. Code relying on the old quoted form (e.g., joining into a shell string) will break — use `subprocess.list2cmdline` or `command_to_string` for shell-safe serialization instead.

prefect_client-3.6.28.dev2/src/prefect/utilities/schema_tools/AGENTS.md

@@ -0,0 +1,53 @@
+# schema_tools
+
+Hydration and validation of `__prefect_kind` template structures used in deployment parameters and automation action payloads.
+
+## Purpose & Scope
+
+Resolves `__prefect_kind` structures into real Python values (hydration) and validates JSON Schema parameter specs with first-class support for Prefect's placeholder types (validation).
+
+## Entry Point
+
+```python
+from prefect.utilities.schema_tools.hydration import hydrate, HydrationContext
+
+ctx = HydrationContext(render_jinja=True, jinja_context={"event": event})
+result = hydrate(parameters, ctx)
+```
+
+## `__prefect_kind` Contracts
+
+| Kind | Input structure | Output | Notes |
+|------|----------------|--------|-------|
+| `"jinja"` | `{"__prefect_kind": "jinja", "template": "..."}` | `str` | **Always returns a string** — even if the template renders a number |
+| `"json"` | `{"__prefect_kind": "json", "value": ...}` | parsed value | If `value` is already a non-string (int, bool, list, dict, None), it is returned as-is without JSON decoding |
+| `"workspace_variable"` | `{"__prefect_kind": "workspace_variable", "variable_name": "..."}` | variable value | Requires `render_workspace_variables=True` in context |
+
+**Critical non-obvious invariant:** `jinja` kind always returns a `str`. To preserve the original type of a templated value (int, float, bool, list, dict), use the json+jinja pattern with `| tojson`:
+
+```python
+# Type-preserving round-trip for a single expression:
+{
+    "__prefect_kind": "json",
+    "value": {
+        "__prefect_kind": "jinja",
+        "template": "{{ value | tojson }}"
+    }
+}
+# Renders {{ value | tojson }} → JSON string → json.loads() → original type
+```
+
+This is the pattern used by `RunDeployment._wrap_v1_template` for single-expression Jinja parameters.
+
+## Placeholder Protocol
+
+Handlers return `Placeholder` subclasses (e.g. `RemoveValue`, `InvalidJSON`, `InvalidJinja`) when values are missing or rendering fails. `hydrate()` removes keys with `RemoveValue` and propagates error placeholders unless `raise_on_error=True` in the context.
+
+## Anti-Patterns
+
+- **Don't use `jinja` kind and expect a typed value** — it always returns a string. Use `json` + `jinja` + `| tojson` for type preservation.
+- **Don't add server imports to this module** — it's used client-side too. `HydrationContext.build()` is an explicit exception (async, server-only); the rest of `hydration.py` must remain importable without a running server.
+
+## Pitfalls
+
+- **`HydrationContext` workspace variables are loaded once at build time.** Stale contexts don't reflect variable updates made after context creation.

prefect_client-3.6.28.dev2/src/prefect/utilities/templating/AGENTS.md

@@ -0,0 +1,19 @@
+# templating
+
+Placeholder detection and value application for Prefect's `{{ }}` templating used in block references, workspace variables, and parameter templating.
+
+## Purpose & Scope
+
+Finds `{{ ... }}` placeholders inside nested structures (`find_placeholders`) and substitutes their resolved values back in (`apply_values`). Distinguishes between standard placeholders, block-document references, and environment variable placeholders via `PlaceholderType`.
+
+Note: this module is *not* a Jinja renderer. For Jinja hydration of `__prefect_kind: "jinja"` structures, see `../schema_tools/`. For user-facing Jinja templates in automation actions, see `prefect/server/utilities/user_templates.py`.
+
+## Entry Points
+
+- `find_placeholders(template) -> set[Placeholder]` — walk any dict/list/str and collect `{{ name }}` placeholders, classified by `PlaceholderType`.
+- `apply_values(template, values) -> template` — substitute resolved values back into the nested structure.
+- `determine_placeholder_type(name) -> PlaceholderType` — classify a placeholder name as STANDARD / BLOCK_DOCUMENT / ENV_VAR.
+
+## Pitfalls
+
+- **`resolve_block_document_references` raises `ValueError` for malformed block placeholders.** Placeholders must follow the format `prefect.blocks.<block-type-slug>.<block-document-name>` (at least two dot-separated parts after the prefix). A placeholder like `{{ prefect.blocks.only-type }}` (missing the document name) raises `ValueError` before any network call is made.