loom-kernel 2.1.0__tar.gz → 2.1.2__tar.gz

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
   release:
     permissions:
       contents: write
-    uses: the-reacher-data/loom-actions/.github/workflows/release-on-label.yml@28ac23a8f40757a8e162ba9d4fdc847a69d13c1e # v1.2.2
+    uses: the-reacher-data/loom-actions/.github/workflows/release-on-label.yml@017878a375d4728129792fee009296635884b6d3 # v1.2.3
     with:
       build-distribution: true
       package-name: loom-kernel

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Unreleased
 
+## 🐛 Fixes
+
+### prefect
+
+- **prefect:** a correlation id renders its datetime's UTC instant instead of
+  its wall clock. `strftime` printed the local reading and dropped the
+  offset, so `2026-06-03T00:00+02:00` and `2026-06-03T00:00Z` — two instants
+  two hours apart — produced the same id, and therefore the same manifest
+  store key: the second run opened the first one's manifest and could treat
+  processes it never ran as done. A naive value still means UTC and is
+  unaffected by the machine's zone. The id of a run whose `correlation_field`
+  carries a non-UTC offset changes (`2026-06-03T00:00+02:00` now keys
+  `20260602T220000`), so do not upgrade across a run you intend to resume
+  from its manifest.
+
+- **prefect:** `backfill_flow` resumes from a `start_from` submitted as a
+  string. A flow's run parameters are not validated against its signature
+  (`validate_parameters=False`), so `start_from` reached the chunk algebra
+  exactly as the Prefect API delivered it and an ISO string failed the run
+  with `AttributeError: 'str' object has no attribute 'tzinfo'`. It now goes
+  through the same placeholder resolution and datetime coercion as every
+  other parameter: a `datetime`, a `date`, an ISO string (naive read as UTC,
+  offset-bearing keeping its instant) or a placeholder. A value that resolves to none of those
+  raises `ValueError` naming the parameter instead of `AttributeError`.
+- **prefect:** a `${today}` placeholder reaches a parameter declared
+  `datetime`, read as its midnight in UTC. It used to fail the run with
+  `ValidationError: Expected datetime, got date`, because the placeholder
+  resolves to a `date` and only `date`-declared parameters accepted one.
+  Applies to `etl_flow`, `maintenance_flow` and `backfill_flow` alike. A
+  parameter declared `date` still receives a `date`.
+- **prefect:** a `datetime` parameter submitted as an offset-bearing ISO
+  string is parsed into a `datetime` before the flow decodes its parameters,
+  where the string used to travel on unparsed. Two consequences, both in
+  `etl_flow` as well as `backfill_flow`. A string that Python's ISO parser
+  accepts but msgspec rejects — an offset carrying seconds, say — now decodes
+  instead of failing the run. And a flow whose `correlation_field` is such a
+  parameter gets a different correlation id: the compact `20260603T000000`
+  form the naive-string path already produced, instead of the raw string.
+  Since the correlation id keys the manifest store, do not upgrade across a
+  run you intend to resume from its manifest — start it again instead.
+
+# 🚀 Release 2.1.0 ([#235](https://github.com/the-reacher-data/loom-py/pull/235))
+
+## ✨ Features
+
+### ai
+
+- **ai:** an `on_output` hook receives the run's tool traffic. `messages` used
+  to be `None` unless the run carried a conversation, so a hook could compose
+  only from the answer; it now carries the run's serialised messages either
+  way, bounded by `policies.max_history_bytes` — over that bound the hook
+  receives `None` and the run logs the artifact, the measured size and the
+  bound.
+- **ai:** `policies.retries` states both axes it governs wherever an author
+  reads it — the field's docstring and the published JSON Schema description.
+  It retries a failed tool call and an answer `output_check` rejects inside
+  one run, always; it retries a failed provider call across runs only when the
+  plan holds no capability. The number itself is unchanged.
+
+# 🚀 Release 2.0.0 ([#234](https://github.com/the-reacher-data/loom-py/pull/234))
+
 ## ⚠ Behaviour changes
 
 ### ai
@@ -43,6 +104,27 @@
   be published over A2A; a deployment listing one in `ai.a2a.expose` fails
   start-up naming both the artifact and the conflict. See
   `docs/ai/artifacts.md#the-artifacts-state--deps_type-and-deps_schema`.
+- **ai:** an artefact may declare `output_check`, a `module:Symbol` reference
+  to an `OutputCheck` — aliased publicly as `loom.ai.OutputCheck`
+  (`Callable[[Mapping[str, Any]], str | None]`) — a pure, synchronous
+  predicate over the mapping the engine parsed from the model's answer.
+  `None` accepts the answer; a non-empty string is the text the model must
+  read to correct itself, driving a real retry inside the engine's own run,
+  bounded by `policies.retries`. It is a predicate, not a transformer: a
+  mapping the check builds and returns is discarded, never substituted for
+  the answer, which loom always decodes independently from the model's own
+  bytes. Declaring `output_check` changes how a run streams: loom withholds
+  the answer's deltas until they pass the check, then emits them, instead of
+  relaying them token by token as an artifact with no check does — the
+  trade-off is no partial text on the wire until the check accepts, in
+  exchange for never streaming an answer the check goes on to reject. See
+  `docs/ai/artifacts.md#output_check--demanding-the-shape-of-the-answer`.
+
+# 🚀 Release 1.19.0 ([#224](https://github.com/the-reacher-data/loom-py/pull/224))
+
+## ⚠ Behaviour changes
+
+### ai
 
 - **ai:** the MCP handshake deadline is now `ai.startup_timeout_ms` instead of
   the engine's own undocumented five seconds. Two consequences ship silently
@@ -104,21 +186,6 @@
   consequence, turns `policies.on_unpriced_spend: serve` into `refuse` no
   matter what the artifact declares — see "Spend caps" in
   `docs/ai/artifacts.md` for the mechanism and the remedy.
-- **ai:** an artefact may declare `output_check`, a `module:Symbol` reference
-  to an `OutputCheck` — aliased publicly as `loom.ai.OutputCheck`
-  (`Callable[[Mapping[str, Any]], str | None]`) — a pure, synchronous
-  predicate over the mapping the engine parsed from the model's answer.
-  `None` accepts the answer; a non-empty string is the text the model must
-  read to correct itself, driving a real retry inside the engine's own run,
-  bounded by `policies.retries`. It is a predicate, not a transformer: a
-  mapping the check builds and returns is discarded, never substituted for
-  the answer, which loom always decodes independently from the model's own
-  bytes. Declaring `output_check` changes how a run streams: loom withholds
-  the answer's deltas until they pass the check, then emits them, instead of
-  relaying them token by token as an artifact with no check does — the
-  trade-off is no partial text on the wire until the check accepts, in
-  exchange for never streaming an answer the check goes on to reject. See
-  `docs/ai/artifacts.md#output_check--demanding-the-shape-of-the-answer`.
 - **ai:** `AgentDescription.policies` is now typed
   `Mapping[str, int | float | str | None]`, widened from `Mapping[str, int]`
   to carry `max_usd` (as a JSON number, matching the published schema's

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/PKG-INFO

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

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/src/loom/prefect/flow/__init__.py

@@ -31,7 +31,7 @@ The sub-modules here split the factory's concerns:
 - ``_stages`` — process/step name validation against the compiled plan.
 - ``_common`` — small helpers shared by the factories (tag coercion, …).
 - ``_signature`` — synthesising the flow's parameter signature from a
-  ``msgspec.Struct`` plus naive-datetime → UTC coercion.
+  ``msgspec.Struct`` plus the submitted-datetime coercion to tz-aware.
 - ``_run_name`` — computing each run's display name (cron slot vs.
   correlation id vs. fallback timestamp).
 - ``_hooks`` — Prefect ``on_failure`` hook (deactivate the deployment's

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/src/loom/prefect/flow/_backfill.py

@@ -75,13 +75,19 @@ def backfill_flow(
     Returns:
         A ``@prefect.flow``-decorated callable with ``__loom_etl_meta__``
         attached for the deployer. It accepts ``start_from`` to resume the
-        backfill from a given chunk (earlier chunks are skipped), plus ``env``
+        backfill from a given chunk (earlier chunks are skipped). Its
+        published annotation is ``datetime | None``, which is what the
+        Prefect form renders as a date picker; because Prefect does not
+        validate run parameters, the body also accepts a ``date``, an ISO
+        string and a placeholder. Plus ``env``
         for deploy parity with :func:`~loom.prefect.etl_flow` (logged, not
         used for routing).
 
     Raises:
         TypeError: When a process list is not ``list[str]``.
-        ValueError: When a process/step name does not exist in *pipeline*.
+        ValueError: When a process/step name does not exist in *pipeline*, and
+            at run time when ``start_from`` resolves to neither a datetime nor
+            a date.
     """
     settings = load_flow_settings(config_path)
 

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/src/loom/prefect/flow/_backfill_body.py

@@ -23,7 +23,7 @@ from loom.prefect.flow._runtime import (
     load_or_init_manifest,
     maybe_delete_manifest,
 )
-from loom.prefect.flow._signature import normalize_datetime_fields
+from loom.prefect.flow._signature import coerce_to_utc, normalize_datetime_fields
 from loom.prefect.manifest import ManifestStore
 from loom.prefect.observer._logging_bridge import install_log_bridge, uninstall_log_bridge
 
@@ -119,7 +119,7 @@ def build_backfill_body(
 
     def _flow_body(**kwargs: Any) -> None:
         env = kwargs.pop("env", "prod")
-        start_from = kwargs.pop("start_from", None)
+        start_from = _resolve_start_from(kwargs.pop("start_from", None))
         resolved = {k: resolve_placeholder(v) for k, v in kwargs.items()}
         resolved = normalize_datetime_fields(resolved, params_type)
         params = msgspec.convert(resolved, type=params_type)
@@ -233,6 +233,35 @@ def _chunk_windows(
     return windows
 
 
+def _resolve_start_from(value: Any) -> datetime | None:
+    """Coerce a submitted ``start_from`` into a tz-aware datetime.
+
+    Args:
+        value: ``None``, a ``datetime``, a ``date``, an ISO string, or a
+            placeholder.
+
+    Returns:
+        The resume instant, or ``None`` when none was given.
+
+    Raises:
+        ValueError: When *value* resolves to something other than a datetime
+            or a date.
+    """
+    if value is None:
+        return None
+    try:
+        resolved = resolve_placeholder(value)
+    except ValueError as exc:
+        raise ValueError(f"start_from: {exc}") from exc
+    coerced = coerce_to_utc(resolved)
+    if not isinstance(coerced, datetime):
+        raise ValueError(
+            "start_from: expected a datetime, a date, an ISO string or a placeholder, "
+            f"got {value!r}"
+        )
+    return coerced
+
+
 def _floor_chunk(value: datetime, chunk: BackfillChunk) -> datetime:
     return _CHUNK_ALGEBRA[chunk].floor(_as_utc(value).astimezone(UTC))
 

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/src/loom/prefect/flow/_run_name.py

@@ -14,6 +14,8 @@ _COMPACT_TIMESTAMP_FMT = "%Y%m%dT%H%M%S"
 
 
 def _render_value(value: Any) -> str:
+    if isinstance(value, datetime) and value.tzinfo is not None:
+        return value.astimezone(UTC).strftime(_COMPACT_TIMESTAMP_FMT)
     if isinstance(value, datetime | date):
         return value.strftime(_COMPACT_TIMESTAMP_FMT)
     return str(value)
@@ -61,9 +63,10 @@ def compute_correlation_id(
     """Return a stable correlation id for a flow run.
 
     Falls back to ``"<flow_name>-<random>"`` when no ``correlation_field``
-    is configured. Datetimes are rendered compactly so the value remains
-    safe to use in S3 keys, filesystem paths and the manifest store's
-    correlation_id validator.
+    is configured. A datetime is rendered compactly, by its UTC instant, so
+    the value remains safe to use in S3 keys, filesystem paths and the
+    manifest store's correlation_id validator, and so two different instants
+    never share an id.
 
     Args:
         flow_name: Logical ETL name.

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/src/loom/prefect/flow/_signature.py

@@ -5,17 +5,16 @@ For loom ETLs the parameter set is described by the pipeline's
 ``ParamsT`` ``msgspec.Struct``, so the factory synthesises an
 ``inspect.Signature`` that mirrors its fields.
 
-This module also handles the naive→UTC datetime coercion needed when
-Prefect (or a CLI/UI user) submits a parameter as a naive ISO string
-that has to be compared against UTC-aware Polars columns inside the
-runner.
+This module also handles the datetime coercion needed when Prefect (or a
+CLI/UI user) submits a parameter as an ISO string that has to be compared
+against UTC-aware Polars columns inside the runner.
 """
 
 from __future__ import annotations
 
 import inspect
 from collections.abc import Sequence
-from datetime import UTC, datetime
+from datetime import UTC, date, datetime, time
 from types import UnionType
 from typing import Any, Union, get_args, get_origin, get_type_hints
 
@@ -89,20 +88,24 @@ def is_datetime_annotation(annotation: Any) -> bool:
 
 
 def coerce_to_utc(value: Any) -> Any:
-    """Promote a naive ``datetime`` (or naive ISO string) to UTC-aware.
+    """Promote a ``datetime``, a ``date`` or an ISO string to a tz-aware ``datetime``.
 
-    Returns *value* unchanged when it is already tz-aware, when it is
-    ``None``, or when it is a string that cannot be parsed as a naive
-    ISO datetime.
+    A naive value is read as UTC and a ``date`` as its midnight there; an
+    offset-bearing value keeps its offset, and therefore its instant.
+    Returns *value* unchanged when it is already a tz-aware ``datetime``,
+    when it is a string that does not parse as an ISO datetime, and when it
+    is any other value.
     """
     if isinstance(value, datetime):
         return value.replace(tzinfo=UTC) if value.tzinfo is None else value
+    if isinstance(value, date):
+        return datetime.combine(value, time.min, tzinfo=UTC)
     if isinstance(value, str):
         try:
             parsed = datetime.fromisoformat(value)
         except ValueError:
             return value
-        return parsed.replace(tzinfo=UTC) if parsed.tzinfo is None else value
+        return parsed.replace(tzinfo=UTC) if parsed.tzinfo is None else parsed
     return value
 
 
@@ -110,15 +113,15 @@ def normalize_datetime_fields(
     resolved: dict[str, Any],
     params_type: type[msgspec.Struct],
 ) -> dict[str, Any]:
-    """Promote naive datetime values to UTC-aware where the schema expects it.
+    """Coerce the fields *params_type* declares as ``datetime`` into tz-aware values.
 
     Args:
         resolved: Parameter mapping with placeholders already resolved.
         params_type: ``msgspec.Struct`` describing the expected field types.
 
     Returns:
-        A new dict with naive datetime values promoted to UTC-aware; all
-        other values pass through unchanged.
+        A new dict whose datetime-typed entries went through
+        :func:`coerce_to_utc`; every other value passes through unchanged.
     """
     hints = get_type_hints(params_type)
     datetime_fields = {

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/tests/unit/prefect/test_backfill_flow.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from datetime import UTC, datetime
+from datetime import UTC, date, datetime, timedelta
 from pathlib import Path
 from typing import Any
 from unittest.mock import MagicMock
@@ -320,3 +320,138 @@ def test_factory_accepts_step_names(tmp_path: Path) -> None:
     # include= accepts step names too, so the factory validation must as well.
     flow = _build_flow(tmp_path, per_chunk_processes=["_StageStep"])
     assert flow.name == "backfill"
+
+
+def test_start_from_accepts_a_naive_iso_string(tmp_path: Path, runner: MagicMock) -> None:
+    # Prefect submits run parameters unvalidated, so start_from arrives as the
+    # operator typed it.
+    flow = _build_flow(tmp_path)
+    flow.fn(
+        updated_at_from=datetime(2024, 1, 1, tzinfo=UTC),
+        updated_at_to=datetime(2024, 1, 5, tzinfo=UTC),
+        start_from="2024-01-03T09:00:00",
+    )
+    assert [w[0] for w in _windows(runner)] == [
+        datetime(2024, 1, 3, tzinfo=UTC),
+        datetime(2024, 1, 4, tzinfo=UTC),
+    ]
+
+
+def test_start_from_resumes_at_the_chunk_of_the_instant_not_of_the_local_date(
+    tmp_path: Path, runner: MagicMock
+) -> None:
+    # 00:30 at +02:00 is 22:30 UTC of the previous day: the resume chunk is the
+    # 2nd, not the 3rd.
+    flow = _build_flow(tmp_path)
+    flow.fn(
+        updated_at_from=datetime(2024, 1, 1, tzinfo=UTC),
+        updated_at_to=datetime(2024, 1, 5, tzinfo=UTC),
+        start_from="2024-01-03T00:30:00+02:00",
+    )
+    assert [w[0] for w in _windows(runner)] == [
+        datetime(2024, 1, 2, tzinfo=UTC),
+        datetime(2024, 1, 3, tzinfo=UTC),
+        datetime(2024, 1, 4, tzinfo=UTC),
+    ]
+
+
+def test_start_from_resolves_a_placeholder_in_the_past(tmp_path: Path, runner: MagicMock) -> None:
+    # Clock-independent: a placeholder far enough in the past skips no chunk,
+    # and an unresolved one would not be a datetime at all.
+    flow = _build_flow(tmp_path)
+    flow.fn(
+        updated_at_from=datetime(2024, 1, 1, tzinfo=UTC),
+        updated_at_to=datetime(2024, 1, 3, tzinfo=UTC),
+        start_from="${now-100000d}",
+    )
+    assert [w[0] for w in _windows(runner)] == [
+        datetime(2024, 1, 1, tzinfo=UTC),
+        datetime(2024, 1, 2, tzinfo=UTC),
+    ]
+
+
+def test_start_from_resolves_a_placeholder_in_the_future(tmp_path: Path, runner: MagicMock) -> None:
+    flow = _build_flow(tmp_path)
+    flow.fn(
+        updated_at_from=datetime(2024, 1, 1, tzinfo=UTC),
+        updated_at_to=datetime(2024, 1, 3, tzinfo=UTC),
+        start_from="${now+100000d}",
+    )
+    assert _windows(runner) == []
+
+
+def test_start_from_rejects_a_value_that_is_not_a_datetime(
+    tmp_path: Path, runner: MagicMock
+) -> None:
+    flow = _build_flow(tmp_path)
+    with pytest.raises(ValueError, match="start_from"):
+        flow.fn(
+            updated_at_from=datetime(2024, 1, 1, tzinfo=UTC),
+            updated_at_to=datetime(2024, 1, 3, tzinfo=UTC),
+            start_from="yesterday",
+        )
+
+
+def test_start_from_rejects_an_invalid_placeholder_naming_the_parameter(
+    tmp_path: Path, runner: MagicMock
+) -> None:
+    flow = _build_flow(tmp_path)
+    with pytest.raises(ValueError, match="start_from: invalid placeholder"):
+        flow.fn(
+            updated_at_from=datetime(2024, 1, 1, tzinfo=UTC),
+            updated_at_to=datetime(2024, 1, 3, tzinfo=UTC),
+            start_from="${nope}",
+        )
+
+
+def test_start_from_as_a_date_resumes_at_the_first_hour_of_that_day(
+    tmp_path: Path, runner: MagicMock
+) -> None:
+    flow = _build_flow(tmp_path, chunk="hour")
+    flow.fn(
+        updated_at_from=datetime(2024, 1, 3, tzinfo=UTC),
+        updated_at_to=datetime(2024, 1, 3, 3, tzinfo=UTC),
+        start_from=date(2024, 1, 3),
+    )
+    assert [w[0] for w in _windows(runner)] == [
+        datetime(2024, 1, 3, 0, tzinfo=UTC),
+        datetime(2024, 1, 3, 1, tzinfo=UTC),
+        datetime(2024, 1, 3, 2, tzinfo=UTC),
+    ]
+
+
+def test_start_from_resolves_a_today_placeholder(tmp_path: Path, runner: MagicMock) -> None:
+    flow = _build_flow(tmp_path)
+    flow.fn(
+        updated_at_from=datetime(2024, 1, 1, tzinfo=UTC),
+        updated_at_to=datetime(2024, 1, 3, tzinfo=UTC),
+        start_from="${today+100000d}",
+    )
+    assert _windows(runner) == []
+
+
+def test_start_from_floors_a_year_chunk_after_converting_to_utc(
+    tmp_path: Path, runner: MagicMock
+) -> None:
+    # 2024-01-01T00:30+02:00 is 2023-12-31T22:30 UTC: the resume year is 2023.
+    flow = _build_flow(tmp_path, chunk="year")
+    flow.fn(
+        updated_at_from=datetime(2023, 1, 1, tzinfo=UTC),
+        updated_at_to=datetime(2025, 1, 1, tzinfo=UTC),
+        start_from="2024-01-01T00:30:00+02:00",
+    )
+    assert [w[0] for w in _windows(runner)] == [
+        datetime(2023, 1, 1, tzinfo=UTC),
+        datetime(2024, 1, 1, tzinfo=UTC),
+    ]
+
+
+def test_a_today_placeholder_reaches_the_window_fields(tmp_path: Path, runner: MagicMock) -> None:
+    # Clock-independent: yesterday to today is exactly one day chunk.
+    flow = _build_flow(tmp_path)
+    flow.fn(updated_at_from="${today-1d}", updated_at_to="${today}")
+    windows = _windows(runner)
+    assert len(windows) == 1
+    start, end = windows[0]
+    assert start.tzinfo is UTC
+    assert end - start == timedelta(days=1)

{loom_kernel-2.1.0 → loom_kernel-2.1.2}/tests/unit/prefect/test_etl_flow.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 
 import inspect
 import textwrap
-from datetime import UTC, datetime, timedelta, timezone
+import time
+from datetime import UTC, date, datetime, timedelta, timezone
 from pathlib import Path
 
 import pytest
@@ -16,6 +17,7 @@ from loom.prefect._meta import LOOM_ETL_META_ATTR as _LOOM_ETL_META_ATTR
 from loom.prefect._placeholders import resolve_placeholder
 from loom.prefect.flow._assemble import flow_attribute_name, flow_settings_from_mapping
 from loom.prefect.flow._factory import build_etl_flow
+from loom.prefect.flow._run_name import compute_correlation_id
 from loom.prefect.flow._signature import (
     normalize_datetime_fields as _normalize_datetime_fields,
 )
@@ -252,6 +254,10 @@ def test_etl_flow_rejects_non_string_tags(tmp_path: Path) -> None:
         )
 
 
+class _DateParams(ETLParams, frozen=True):  # type: ignore[misc]
+    day: date
+
+
 class _OptionalDtParams(ETLParams, frozen=True):  # type: ignore[misc]
     updated_at_from: datetime | None = None
     label: str = "x"
@@ -278,6 +284,20 @@ def test_naive_datetime_object_is_normalized_to_utc() -> None:
     assert out["updated_at_from"].replace(tzinfo=None) == naive
 
 
+def test_offset_bearing_datetime_string_is_parsed_keeping_its_instant() -> None:
+    out = _normalize_datetime_fields(
+        {
+            "updated_at_from": "2026-06-03T00:00:00+02:00",
+            "updated_at_to": "2026-06-04T00:00:00Z",
+        },
+        _SampleParams,
+    )
+    assert isinstance(out["updated_at_from"], datetime)
+    assert out["updated_at_from"].utcoffset() == timedelta(hours=2)
+    assert out["updated_at_from"].astimezone(UTC) == datetime(2026, 6, 2, 22, 0, tzinfo=UTC)
+    assert isinstance(out["updated_at_to"], datetime)
+
+
 def test_aware_datetime_passes_through() -> None:
     aware = datetime(2026, 6, 3, 0, 0, 0, tzinfo=UTC)
     out = _normalize_datetime_fields(
@@ -298,6 +318,58 @@ def test_aware_datetime_with_offset_passes_through() -> None:
     assert out["updated_at_from"].utcoffset() == timedelta(hours=2)
 
 
+def test_correlation_id_of_an_offset_bearing_string_uses_its_utc_instant() -> None:
+    # The coercion feeds the correlation id as well as the params struct, so the
+    # string keys the manifest store by the instant it names, not by its wall clock.
+    resolved = _normalize_datetime_fields(
+        {"updated_at_from": "2026-06-03T00:00:00+02:00"},
+        _SampleParams,
+    )
+    assert compute_correlation_id("etl", "updated_at_from", resolved) == "etl-20260602T220000"
+
+
+def test_a_date_on_a_datetime_field_becomes_its_midnight_in_utc() -> None:
+    out = _normalize_datetime_fields(
+        {"updated_at_from": date(2026, 6, 3), "updated_at_to": date(2026, 6, 4)},
+        _SampleParams,
+    )
+    assert out["updated_at_from"] == datetime(2026, 6, 3, tzinfo=UTC)
+    assert out["updated_at_to"] == datetime(2026, 6, 4, tzinfo=UTC)
+
+
+def test_a_date_field_keeps_its_date(tmp_path: Path) -> None:
+    # is_datetime_annotation rejects date, so a date-declared field is untouched.
+    out = _normalize_datetime_fields({"day": date(2026, 6, 3)}, _DateParams)
+    assert out["day"] == date(2026, 6, 3)
+
+
+def test_correlation_id_of_two_offsets_distinguishes_the_instants() -> None:
+    madrid = timezone(timedelta(hours=2))
+    at_madrid = {"updated_at_from": datetime(2026, 6, 3, 0, 0, tzinfo=madrid)}
+    at_utc = {"updated_at_from": datetime(2026, 6, 3, 0, 0, tzinfo=UTC)}
+    assert compute_correlation_id("etl", "updated_at_from", at_madrid) == "etl-20260602T220000"
+    assert compute_correlation_id("etl", "updated_at_from", at_utc) == "etl-20260603T000000"
+
+
+def test_correlation_id_of_a_date_keeps_its_day() -> None:
+    resolved = {"updated_at_from": date(2026, 6, 3)}
+    assert compute_correlation_id("etl", "updated_at_from", resolved) == "etl-20260603T000000"
+
+
+def test_correlation_id_of_a_naive_datetime_ignores_the_local_zone(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # A naive value means UTC here, so the machine's zone must not shift it.
+    monkeypatch.setenv("TZ", "America/New_York")
+    time.tzset()
+    try:
+        resolved = {"updated_at_from": datetime(2026, 6, 3, 0, 0)}
+        assert compute_correlation_id("etl", "updated_at_from", resolved) == "etl-20260603T000000"
+    finally:
+        monkeypatch.undo()
+        time.tzset()
+
+
 def test_non_datetime_fields_untouched() -> None:
     out = _normalize_datetime_fields(
         {"updated_at_from": None, "label": "hello", "count": 42},