loom-kernel 2.6.0__tar.gz → 2.7.0__tar.gz

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/CHANGELOG.md

@@ -88,6 +88,33 @@
   boundaries already use; `LoomRestAdapter`'s Struct projection goes
   through it too.
 
+### prefect
+
+- **prefect:** a deployment may run each time another one completes, inheriting
+  some of its parameters. The per-flow YAML takes an optional `trigger` block:
+  `after`, the upstream deployment as `<flow>/<deployment>` or, for a loom ETL
+  whose flow and deployment share its name, that name; and `inherit_params`, a
+  list of parameter names. The deployer registers it as a Prefect
+  `DeploymentEventTrigger` on `prefect.flow-run.Completed` whose related
+  resources must include both that flow and that deployment, since a deployment
+  name is only unique within its flow. Each inherited parameter is rendered, as
+  text, from the completed run's stored parameters, which loom records resolved,
+  so `${today-1d}` upstream reaches the downstream run as the concrete date.
+  Only fields declared exactly `str`, `date` or `datetime` can be inherited (a
+  null would render as `"None"`), and each must be stored on the upstream run,
+  that is declared under its YAML `params` or submitted: a value it only took
+  from a signature default renders as empty text, which a `str` field takes as
+  `""` and a `date` field fails to decode. Every other parameter takes the
+  deployment's default, and a placeholder among them resolves against the
+  downstream run's creation time. The block is decoded strictly (an unknown key,
+  a wrong type or an `after` with spaces around either part is refused) when the
+  flow is built and, for YAML declarations, as a `ConfigError` before any
+  deployment is registered. A trigger coexists with `schedule`, in which case
+  the ETL runs on both. If the upstream run failed to record its parameters, the
+  downstream run inherits the placeholder text and resolves it against its own
+  creation time. Without `trigger` the deployment is registered exactly as
+  before.
+
 ## ⚠ Behaviour changes
 
 ### core
@@ -133,6 +160,44 @@
   OpenAPI schemas for request bodies and responses alike, matching the
   untitled document a Struct always produced.
 
+### prefect
+
+- **prefect:** a placeholder counts from the run's scheduled start instead of
+  the wall clock. `${today-1d}`, `${yesterday}` and `${now±N}` counted from
+  `datetime.now()` inside the flow, so a queued run that started after
+  midnight, or a retry the next day, processed another day than its slot's.
+  `etl_flow`, `maintenance_flow` and `backfill_flow` (`start_from` included)
+  and the run name now resolve against the run's scheduled start
+  (`prefect.runtime.flow_run.scheduled_start_time`, read in UTC): the slot of
+  a scheduled run, the same slot on every retry, the creation time of a manual
+  run. A late run's `${now}` therefore covers up to its scheduled time, not up
+  to the moment it started. Outside a flow run the wall clock still applies.
+  The backfill finalize pass still pins `window_end` to the current chunk.
+- **prefect:** resuming from the manifest now works for placeholder
+  parameters. The correlation id was computed from the resolved value, so
+  with `${now}` it carried the seconds of the clock and a retry never found
+  the manifest of the attempt before it; anchored, every attempt of a run
+  computes the same id. The id is now also computed from the decoded
+  parameters rather than the submitted ones, so a value and its recorded ISO
+  string key the same manifest. Two ids change: a `date` field submitted as
+  an ISO string (`"2026-09-21"` now keys `20260921T000000`, as the `date`
+  itself always did), and a `correlation_field` typed as a plain `Enum`,
+  which now keys the member's sanitised name (`Color_RED`) instead of its
+  submitted value (`red`); a `StrEnum` renders as its value and keeps its id.
+  Do not upgrade across a run you intend to resume from its manifest.
+- **prefect:** the run records the parameters it resolved. Prefect stored and
+  showed the placeholder text, so nothing told which days a run processed.
+  After decoding, the flow updates its own run: the parameters the API stored
+  for it, with each placeholder replaced by its value (dates and datetimes in
+  ISO 8601, a backfill's `start_from` included); nothing is added. The UI
+  shows the concrete window, a run resubmitted from the UI ("Retry") or
+  copied reproduces it, and an automation reading `flow_run.parameters` gets
+  dates. A run that stores no placeholder makes no call, so a resubmitted run
+  makes none. A retry inside the same process (`retries`) still holds the
+  placeholders it started with and repeats the call with the same values,
+  which is harmless. The update is one attempt with a 10-second timeout; if
+  it fails, the flow logs it at `ERROR` in the run's logs and goes on.
+
 ## 🐛 Fixes
 
 ### core

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.6.0
+Version: 2.7.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/docs/guides/etl.md

@@ -893,7 +893,7 @@ that matches nothing is a `ConfigError`.
 
 A declaration file has one of two shapes. The first is a **per-ETL document**:
 the YAML `etl_flow` already reads (`schedule`, `params`, `tags`, `environments`,
-`retry`, `notifications`, `correlation_field`) plus the keys that replace the
+`retry`, `notifications`, `correlation_field`, `trigger`) plus the keys that replace the
 Python module:
 
 ```yaml
@@ -958,6 +958,78 @@ declares neither `etls:` nor `pipeline` is a `ConfigError` naming the file, so
 keep ETL declarations in their own directory (`config/etls/`) or in one `etls:`
 file rather than next to the storage YAML.
 
+### Placeholders count from the run's scheduled start
+
+A parameter may hold a placeholder: `${today}`, `${today±Nd}`, `${yesterday}`,
+`${now}` or `${now±N}` with `d`, `h` or `m`. Inside a flow run it counts from
+the run's scheduled start, read in UTC, not from the moment the run executes:
+
+- a scheduled run resolves against its slot, even when it starts late or
+  after midnight;
+- a retry, by the engine or through "Retry" in the UI, resolves against the
+  same slot;
+- a manual run resolves against the time it was created.
+
+A late run's `${now}` therefore covers up to its scheduled time. The run name
+follows the same rule.
+
+Once resolved, the flow writes the values back to its own run: the
+parameters the API stored for it, with each placeholder replaced by its value
+(dates and datetimes in ISO 8601, a backfill's `start_from` included). Nothing
+else is added or changed. The run then shows the window it processed, and a
+run resubmitted from the UI ("Retry") or copied reproduces it exactly: its
+parameters are concrete, so it makes no call. A retry inside the same process
+(`retries`) still holds the placeholders it started with, resolves them to the
+same values and repeats the call, which is harmless.
+
+The update is a single attempt with a 10-second timeout. If it fails, the flow
+logs it at `ERROR`, in the run's logs, and runs anyway; the run then keeps
+showing the placeholders.
+
+Because every attempt of a run resolves the same values, the correlation id,
+and therefore the manifest a retry resumes from, is stable across attempts.
+
+### Running a deployment after another one
+
+A per-flow YAML may name the deployment whose completed runs start this one,
+and the parameters it copies from them:
+
+```yaml
+trigger:
+  after: respondio_messages_daily
+  inherit_params: [updated_at_from, updated_at_to]
+```
+
+`after` is the upstream deployment as `<flow>/<deployment>`, or a single name
+when the flow and the deployment share it, as every loom ETL's do. The
+deployer registers a Prefect `DeploymentEventTrigger` that fires on
+`prefect.flow-run.Completed` of a run related to both that flow and that
+deployment; a deployment name alone is only unique within its flow.
+
+Each name in `inherit_params` is copied from the completed run's stored
+parameters. Since the run records its placeholders resolved, the downstream
+run receives the same concrete window. The name must therefore be stored on the
+upstream run, which means declared under the upstream YAML's `params` (or
+submitted with the run): a value the upstream flow only took from its
+signature default is not stored, so it renders as empty text, which a `str`
+field accepts as `""` and a `date` or `datetime` field fails to decode. The trigger passes each value as text,
+so only a field declared exactly `str`, `date` or `datetime` can be inherited;
+an optional field is refused because a null would arrive as the text `"None"`.
+
+- Parameters not inherited take this deployment's defaults; a placeholder
+  among them resolves against the downstream run's own creation time.
+- If the upstream run could not record its parameters, the downstream run
+  inherits the placeholder text and resolves it against its own creation
+  time, which may not be the upstream slot.
+- `trigger` and `schedule` may both be set, and the ETL then runs on both: on
+  its schedule and after each completed upstream run.
+- The upstream name is not checked against the deployments that exist: a
+  trigger naming no deployment never fires.
+
+The block is decoded strictly: `after` and `inherit_params` are its only keys,
+`after` must name a deployment, without surrounding spaces in either part, and
+each inherited name must be a field of the flow's params type.
+
 ### Validation before any deployment
 
 Every declaration is read and checked before the first deployment is

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/src/loom/prefect/_flow_yaml.py

@@ -11,7 +11,10 @@ from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
 
+import msgspec
+
 from loom.core.config import is_cloud_uri, load_config
+from loom.prefect._meta import FlowTrigger
 
 _ENV_INTERPOLATION = re.compile(r"\$\{oc\.[^}]*\}")
 
@@ -78,6 +81,30 @@ def extract_pool_config(raw_cfg: Mapping[str, Any]) -> dict[str, dict[str, Any]]
     return out
 
 
+def extract_trigger(raw_cfg: Mapping[str, Any]) -> FlowTrigger | None:
+    """Return the ``trigger`` block of the per-flow YAML, or ``None``.
+
+    Raises:
+        ValueError: When the block does not decode into a
+            :class:`~loom.prefect._meta.FlowTrigger` (unknown key, wrong
+            type) or ``after`` does not name a deployment.
+    """
+    raw = raw_cfg.get("trigger")
+    if raw is None:
+        return None
+    try:
+        trigger = msgspec.convert(raw, type=FlowTrigger)
+    except msgspec.ValidationError as exc:
+        raise ValueError(f"trigger: {exc}") from exc
+    parts = trigger.after.split("/")
+    if len(parts) > 2 or not all(part and part == part.strip() for part in parts):
+        raise ValueError(
+            f"trigger.after: expected '<flow>/<deployment>' or a deployment name, "
+            f"got {trigger.after!r}"
+        )
+    return trigger
+
+
 def _ensure_mapping_top_level(config_path: str) -> None:
     """Reject a non-mapping document; unreadable or malformed files are left to ``load_config``."""
     import yaml  # noqa: PLC0415
@@ -115,4 +142,4 @@ def _resolve_string(value: str) -> Any:
     return value
 
 
-__all__ = ["extract_pool_config", "read_yaml", "resolve_config_uri"]
+__all__ = ["extract_pool_config", "extract_trigger", "read_yaml", "resolve_config_uri"]

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/src/loom/prefect/_meta.py

@@ -23,6 +23,32 @@ DEFAULT_STORAGE_CONFIG_PATH = "/app/config.yaml"
 LOOM_ETL_CONFIG = "LOOM_ETL_CONFIG"
 
 
+class FlowTrigger(LoomFrozenStruct, frozen=True, kw_only=True, forbid_unknown_fields=True):
+    """Run a deployment each time another deployment completes a run.
+
+    Args:
+        after: The upstream deployment, as ``<flow>/<deployment>`` or, for a
+            loom ETL whose flow and deployment share its name, that name.
+        inherit_params: Parameters copied from the completed run; every
+            other parameter takes this deployment's default.
+    """
+
+    after: str
+    inherit_params: tuple[str, ...] = ()
+
+    @property
+    def upstream_flow(self) -> str:
+        """Name of the flow the upstream deployment belongs to."""
+        flow, _, _ = self.after.partition("/")
+        return flow
+
+    @property
+    def upstream_deployment(self) -> str:
+        """Name of the upstream deployment."""
+        _, _, deployment = self.after.partition("/")
+        return deployment or self.after
+
+
 class ETLFlowMeta(LoomFrozenStruct, frozen=True, kw_only=True):
     """Per-flow metadata consumed by :func:`discover_and_deploy_etls`.
 
@@ -39,6 +65,7 @@ class ETLFlowMeta(LoomFrozenStruct, frozen=True, kw_only=True):
         pool_config: Per-environment work-pool overrides
             (``environment → {"work_pool", "job_variables"}``).
         tags: Extra deployment tags from the YAML, appended after ``name``.
+        trigger: The ``trigger`` block from the YAML, or ``None``.
     """
 
     name: str
@@ -49,6 +76,13 @@ class ETLFlowMeta(LoomFrozenStruct, frozen=True, kw_only=True):
     raw_params: dict[str, Any]
     pool_config: dict[str, dict[str, Any]]
     tags: tuple[str, ...] = ()
+    trigger: FlowTrigger | None = None
 
 
-__all__ = ["DEFAULT_STORAGE_CONFIG_PATH", "LOOM_ETL_CONFIG", "LOOM_ETL_META_ATTR", "ETLFlowMeta"]
+__all__ = [
+    "DEFAULT_STORAGE_CONFIG_PATH",
+    "LOOM_ETL_CONFIG",
+    "LOOM_ETL_META_ATTR",
+    "ETLFlowMeta",
+    "FlowTrigger",
+]

loom_kernel-2.7.0/src/loom/prefect/_placeholders.py

@@ -0,0 +1,126 @@
+"""Placeholder DSL for dynamic ETL parameters.
+
+Supported tokens (case-sensitive):
+
+- ``${today}``, ``${today+Nd}``, ``${today-Nd}`` → :class:`datetime.date`
+- ``${yesterday}`` → :class:`datetime.date` (alias of ``${today-1d}``)
+- ``${now}``, ``${now±Nd}``, ``${now±Nh}``, ``${now±Nm}`` →
+  timezone-aware UTC :class:`datetime.datetime`
+
+Any value that looks like ``${...}`` but does not match one of the three
+valid patterns raises :class:`ValueError`. Non-string values and strings
+that do not look like placeholders pass through unchanged.
+
+Tokens count from an *anchor* instant, read in UTC. Inside a Prefect flow
+run the anchor is the run's scheduled start, so the processed window belongs
+to the run and not to the moment it happens to execute:
+
+- a scheduled run resolves against its slot, even when it starts late;
+- a retry (by the engine or "Retry" in the UI) resolves against the same slot;
+- a manual run resolves against the time it was created.
+
+A run that starts late therefore gets ``${now}`` up to its scheduled time,
+not up to the wall clock. Without an anchor the tokens use the wall clock.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+_TODAY_RE = re.compile(r"^\$\{today(?:([+-])(\d+)d)?\}$")
+_YESTERDAY_RE = re.compile(r"^\$\{yesterday\}$")
+_NOW_RE = re.compile(r"^\$\{now(?:([+-])(\d+)([dhm]))?\}$")
+_ANY_DOLLAR = re.compile(r"^\$\{.*\}$")
+
+_NOW_UNIT_KW = {"d": "days", "h": "hours", "m": "minutes"}
+
+
+def _signed_int(sign: str | None, amount: str | None) -> int:
+    if sign is None or amount is None:
+        return 0
+    magnitude = int(amount)
+    return magnitude if sign == "+" else -magnitude
+
+
+def utc_datetime(value: datetime) -> datetime:
+    """Return *value* as a stdlib UTC ``datetime``, a naive value read as UTC.
+
+    A subclass such as pendulum's ``DateTime``, which Prefect returns for a
+    run's scheduled start, is rebuilt as a plain ``datetime``: msgspec decodes
+    only the exact stdlib types, and ``DateTime.date()`` is not a stdlib
+    ``date`` either.
+    """
+    utc = value.replace(tzinfo=UTC) if value.tzinfo is None else value.astimezone(UTC)
+    return datetime(
+        utc.year,
+        utc.month,
+        utc.day,
+        utc.hour,
+        utc.minute,
+        utc.second,
+        utc.microsecond,
+        tzinfo=UTC,
+    )
+
+
+def _base(anchor: datetime | None) -> datetime:
+    return datetime.now(UTC) if anchor is None else utc_datetime(anchor)
+
+
+def _resolve_today(match: re.Match[str], base: datetime) -> Any:
+    sign, days = match.groups()
+    return base.date() + timedelta(days=_signed_int(sign, days))
+
+
+def _resolve_now(match: re.Match[str], base: datetime) -> Any:
+    sign, amount, unit = match.groups()
+    if sign is None:
+        return base
+    return base + timedelta(**{_NOW_UNIT_KW[unit]: _signed_int(sign, amount)})
+
+
+def is_placeholder(value: Any) -> bool:
+    """Return ``True`` when *value* is a string written as ``${...}``."""
+    return isinstance(value, str) and value.startswith("${")
+
+
+def resolve_placeholder(value: Any, *, anchor: datetime | None = None) -> Any:
+    """Resolve a placeholder string to a concrete ``date`` / ``datetime``.
+
+    Args:
+        value: Arbitrary parameter value. Only strings matching the DSL are
+            resolved; every other value is returned unchanged.
+        anchor: Instant the tokens count from, read in UTC (a naive value
+            is taken as UTC). ``None`` uses the current time.
+
+    Returns:
+        The resolved date/datetime, or the original value if it is not a
+        placeholder.
+
+    Raises:
+        ValueError: If the value looks like a placeholder (``${...}``) but
+            does not match any of the supported patterns.
+    """
+    if not is_placeholder(value):
+        return value
+
+    base = _base(anchor)
+    today_match = _TODAY_RE.match(value)
+    if today_match is not None:
+        return _resolve_today(today_match, base)
+
+    if _YESTERDAY_RE.match(value) is not None:
+        return base.date() - timedelta(days=1)
+
+    now_match = _NOW_RE.match(value)
+    if now_match is not None:
+        return _resolve_now(now_match, base)
+
+    if _ANY_DOLLAR.match(value) is not None:
+        raise ValueError(f"invalid placeholder: {value!r}")
+    return value
+
+
+__all__ = ["is_placeholder", "resolve_placeholder", "utc_datetime"]

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/src/loom/prefect/deploy/_discovery.py

@@ -11,7 +11,9 @@ from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
 
-from loom.prefect._meta import LOOM_ETL_CONFIG, LOOM_ETL_META_ATTR, ETLFlowMeta
+from prefect.events import DeploymentEventTrigger
+
+from loom.prefect._meta import LOOM_ETL_CONFIG, LOOM_ETL_META_ATTR, ETLFlowMeta, FlowTrigger
 from loom.prefect.deploy import entrypoint
 from loom.prefect.deploy._schedule import build_cron_schedule
 from loom.prefect.deploy._yaml_etls import EtlDeclaration, read_declarations
@@ -167,9 +169,36 @@ def _register(sourced: Any, meta: ETLFlowMeta, plan: _DeploymentPlan) -> str:
     schedule = build_cron_schedule(meta.schedule)
     if schedule is not None:
         kwargs["schedules"] = [schedule]
+    if meta.trigger is not None:
+        kwargs["triggers"] = [_completion_trigger(meta.trigger)]
     return str(sourced.deploy(**kwargs))
 
 
+def _completion_trigger(trigger: FlowTrigger) -> DeploymentEventTrigger:
+    """Start the deployment when a run of the upstream deployment completes.
+
+    Each inherited parameter is rendered from the completed run's stored
+    parameters, which loom records resolved, so placeholders arrive as dates.
+    """
+    inherited = {
+        name: {"__prefect_kind": "jinja", "template": f"{{{{ flow_run.parameters['{name}'] }}}}"}
+        for name in trigger.inherit_params
+    }
+    # Prefect requires every entry of the list to match a related resource; a
+    # deployment name alone is only unique within its flow.
+    return DeploymentEventTrigger(
+        expect={"prefect.flow-run.Completed"},
+        match_related=[
+            {"prefect.resource.role": "flow", "prefect.resource.name": trigger.upstream_flow},
+            {
+                "prefect.resource.role": "deployment",
+                "prefect.resource.name": trigger.upstream_deployment,
+            },
+        ],
+        parameters=inherited or None,
+    )
+
+
 def _file_entrypoint(flow_obj: Any, meta: ETLFlowMeta, working_dir: str) -> str:
     """Return ``<path relative to working_dir>:<flow function>``.
 

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/src/loom/prefect/deploy/_yaml_etls.py

@@ -24,6 +24,7 @@ from loom.etl import ETLPipeline
 from loom.prefect._flow_yaml import read_yaml, resolve_config_uri
 from loom.prefect._meta import DEFAULT_STORAGE_CONFIG_PATH, LOOM_ETL_CONFIG
 from loom.prefect.flow import FlowSettings, flow_attribute_name, flow_settings_from_mapping
+from loom.prefect.flow._assemble import check_inherited_params
 
 
 @dataclass(frozen=True)
@@ -62,7 +63,8 @@ def read_declarations(config: str) -> tuple[EtlDeclaration, ...]:
         ConfigError: When a file declares no ETL, a dotted path does not import
             or has the wrong type, a name yields no identifier, ``job_variables``
             or ``job_variables.env`` is not a mapping, a declaration sets
-            ``LOOM_ETL_CONFIG`` under ``job_variables.env``, or two declarations
+            ``LOOM_ETL_CONFIG`` under ``job_variables.env``, a trigger inherits
+            a parameter the params type does not declare, or two declarations
             share a name or an attribute.
     """
     declarations: list[EtlDeclaration] = []
@@ -122,14 +124,19 @@ def _declaration(name: str, body: Any, uri: str) -> EtlDeclaration:
     if not isinstance(body, Mapping):
         raise ConfigError(f"{uri}: ETL {name!r} must be a mapping")
     pipeline = _import_pipeline(name, body.get("pipeline"), uri)
-    settings = flow_settings_from_mapping(body)
+    params_type = _resolve_params_type(name, body.get("params_type"), pipeline, uri)
+    try:
+        settings = flow_settings_from_mapping(body)
+        check_inherited_params(name, settings.trigger, params_type)
+    except (TypeError, ValueError) as exc:
+        raise ConfigError(f"{uri}: ETL {name!r}: {exc}") from exc
     _reject_reserved_env(name, settings, uri)
     return EtlDeclaration(
         name=name,
         attribute=_attribute_for(name, uri),
         config_uri=uri,
         pipeline=pipeline,
-        params_type=_resolve_params_type(name, body.get("params_type"), pipeline, uri),
+        params_type=params_type,
         settings=settings,
         storage_config_path=str(body.get("storage_config_path", DEFAULT_STORAGE_CONFIG_PATH)),
     )

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/src/loom/prefect/flow/_assemble.py

@@ -12,19 +12,28 @@ from __future__ import annotations
 import inspect
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
+from datetime import date, datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, get_type_hints
 
+import msgspec
 import prefect
 
 from loom.prefect._config import FlowConfig, flow_config_from_mapping
-from loom.prefect._flow_yaml import extract_pool_config, read_yaml, resolve_config_uri
-from loom.prefect._meta import LOOM_ETL_META_ATTR, ETLFlowMeta
+from loom.prefect._flow_yaml import (
+    extract_pool_config,
+    extract_trigger,
+    read_yaml,
+    resolve_config_uri,
+)
+from loom.prefect._meta import LOOM_ETL_META_ATTR, ETLFlowMeta, FlowTrigger
 from loom.prefect.flow._common import coerce_tags
 from loom.prefect.flow._hooks import make_notification_hooks, pause_schedule_on_failure
 from loom.prefect.flow._run_name import make_run_name_callback
 from loom.prefect.notify import Notifier, build_notifiers
 
+_INHERITABLE_TYPES: frozenset[Any] = frozenset({str, date, datetime})
+
 
 @dataclass(frozen=True)
 class FlowSettings:
@@ -37,6 +46,7 @@ class FlowSettings:
     tags: tuple[str, ...]
     notifiers: tuple[Notifier, ...]
     retry_policy: FlowConfig
+    trigger: FlowTrigger | None = None
 
 
 def load_flow_settings(config_path: str) -> FlowSettings:
@@ -68,6 +78,7 @@ def flow_settings_from_mapping(raw_cfg: Mapping[str, Any]) -> FlowSettings:
         tags=coerce_tags(raw_cfg.get("tags")),
         notifiers=build_notifiers(raw_cfg.get("notifications")),
         retry_policy=flow_config_from_mapping(raw_cfg.get("retry")),
+        trigger=extract_trigger(raw_cfg),
     )
 
 
@@ -88,6 +99,7 @@ def assemble_flow(
     name: str,
     body: Callable[..., None],
     signature: inspect.Signature,
+    params_type: type[msgspec.Struct],
     settings: FlowSettings,
     config_path: str,
     source_file: str,
@@ -101,6 +113,7 @@ def assemble_flow(
         name: Logical flow name (Prefect flow name AND deployment name).
         body: The ``**kwargs`` flow-body callable produced by a factory.
         signature: Synthesised ``inspect.Signature`` exposed to Prefect.
+        params_type: Struct the flow's parameters decode into.
         settings: Parsed per-flow YAML settings.
         config_path: Path or URI of the per-flow YAML. A local path is
             resolved into the metadata; a cloud URI is recorded verbatim.
@@ -114,7 +127,12 @@ def assemble_flow(
     Returns:
         The ``@prefect.flow``-decorated callable with ``__loom_etl_meta__``
         attached at :data:`~loom.prefect._meta.LOOM_ETL_META_ATTR`.
+
+    Raises:
+        ValueError: When the trigger inherits a parameter *params_type* does
+            not declare.
     """
+    check_inherited_params(name, settings.trigger, params_type)
     safe_name = flow_attribute_name(name)
     flow_body: Any = body
     flow_body.__signature__ = signature
@@ -143,14 +161,50 @@ def assemble_flow(
             raw_params=settings.raw_params,
             pool_config=settings.pool_config,
             tags=settings.tags,
+            trigger=settings.trigger,
         ),
     )
     return decorated
 
 
+def check_inherited_params(
+    name: str, trigger: FlowTrigger | None, params_type: type[msgspec.Struct]
+) -> None:
+    """Refuse a trigger inheriting a parameter it cannot carry.
+
+    The trigger renders each inherited value as text, so only a field
+    declared exactly ``str``, ``date`` or ``datetime`` decodes back to what
+    the upstream run held. An optional field is refused as well: a null
+    upstream value renders as the text ``"None"``, which a date field
+    rejects and a text field takes silently.
+
+    Raises:
+        ValueError: When an entry of ``trigger.inherit_params`` is not a field
+            of *params_type*, or is not declared ``str``, ``date`` or
+            ``datetime``.
+    """
+    if trigger is None:
+        return
+    fields = {field.name for field in msgspec.structs.fields(params_type)}
+    hints = get_type_hints(params_type)
+    for param in trigger.inherit_params:
+        if param not in fields:
+            raise ValueError(
+                f"flow {name!r}: trigger.inherit_params names {param!r}, "
+                f"not a field of {params_type.__name__}"
+            )
+        if hints.get(param) not in _INHERITABLE_TYPES:
+            raise ValueError(
+                f"flow {name!r}: trigger.inherit_params names {param!r}, declared "
+                f"{hints.get(param)!r}; the trigger passes values as text, so only "
+                "str, date and datetime fields can be inherited"
+            )
+
+
 __all__ = [
     "FlowSettings",
     "assemble_flow",
+    "check_inherited_params",
     "flow_attribute_name",
     "flow_settings_from_mapping",
     "load_flow_settings",

{loom_kernel-2.6.0 → loom_kernel-2.7.0}/src/loom/prefect/flow/_backfill.py

@@ -122,6 +122,7 @@ def backfill_flow(
         name=name,
         body=flow_body,
         signature=signature,
+        params_type=params_type,
         settings=settings,
         config_path=config_path,
         source_file=source_file,