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

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/.github/workflows/ci-pr.yml

@@ -91,6 +91,41 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+  model-python-314:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        run: |
+          pip install --only-binary :all: "uv==0.10.2"
+
+      - name: Run the model tests with coverage
+        shell: bash
+        env:
+          COVERAGE_FILE: .coverage.model
+        run: |
+          set -euo pipefail
+          uv run --frozen --python 3.14 --no-default-groups --extra testing \
+            --with "pytest-cov==7.1.0" pytest tests/unit/core/model --cov --cov-report=
+
+      - name: Store model coverage
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: test-results-model
+          path: .coverage.model
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
+
   # Serial: each xdist worker starts its own JVM, which under coverage cancels
   # the parallelism out.
   tests-spark:
@@ -141,7 +176,7 @@ jobs:
   # The gate: cheap checks plus the merged results, so a failure in either lane
   # still blocks here.
   validate:
-    needs: [tests-fast, tests-spark]
+    needs: [tests-fast, tests-spark, model-python-314]
     runs-on: ubuntu-latest
     env:
       SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
@@ -186,7 +221,12 @@ jobs:
         with:
           name: test-results-spark
 
-      - name: Combine the results of both lanes
+      - name: Download model coverage
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: test-results-model
+
+      - name: Combine the results of every lane
         shell: bash
         run: |
           set -euo pipefail
@@ -194,7 +234,7 @@ jobs:
             --junit junit-fast.xml --junit junit-slow.xml --junit junit-spark.xml \
             --junit-output junit.xml
           uv run --frozen --with "pytest-cov==7.1.0" coverage combine \
-            .coverage.fast .coverage.slow .coverage.spark
+            .coverage.fast .coverage.slow .coverage.spark .coverage.model
           uv run --frozen --with "pytest-cov==7.1.0" coverage json -o coverage.json
           uv run --frozen --with "pytest-cov==7.1.0" coverage xml -o coverage.xml
 

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

@@ -2,6 +2,61 @@
 
 ## 🐛 Fixes
 
+### core
+
+- **core:** a model with a relation or projection field imports again on
+  Python 3.12.4 and later when its module uses
+  `from __future__ import annotations`. It failed with
+  `TypeError: ForwardRef._evaluate() missing 1 required keyword-only argument: 'recursive_guard'`,
+  because the string annotation went through a private `typing` API whose
+  signature changed; it is now evaluated with `typing.get_type_hints`.
+- **core:** a model keeps its fields on Python 3.14. Class annotations are lazy
+  there, so the model metaclass found no `__annotations__` in the class body and
+  replaced them with an empty mapping: the struct had no fields and
+  `compile_model` failed with `could not assemble any primary key columns`. The
+  metaclass now evaluates them with `annotationlib` when the class is created,
+  so an undefined name still fails at import; the model class carries the
+  evaluated `__annotations__` and no `__annotate__` function.
+
+### etl
+
+- **etl:** `IntoHistory(..., mode="snapshot")` no longer reopens a row on
+  every run when a tracked column is null. Classification joined existing
+  and incoming rows on `keys + track`, and a plain equi-join never matches
+  two nulls (SQL semantics): an entity whose tracked value was null looked
+  "changed" forever, closed its open version and opened an identical one on
+  every write, stamping `valid_to` each time even though nothing changed.
+  The same null-mismatch broke `overwrite` — the refreshed value silently
+  never landed on the open row. The Polars and Spark join now treat two
+  nulls as equal (`nulls_equal` on Polars, `eqNullSafe` on
+  Spark) for both the SNAPSHOT classification joins and the overwrite join;
+  LOG mode was already null-safe and is unaffected.
+  The `etl-polars` extra now requires `polars>=1.24`, the release that
+  named that join option `nulls_equal`.
+
+## ♻️ Refactor
+
+### etl
+
+- **etl:** the reader registry is gone. Nothing registered a per-kind
+  reader: the Mongo, ClickHouse and DynamoDB readers are built from
+  configuration and injected into the Polars reader, so the registry wrapped
+  one reader and forwarded to it. `PolarsProvider.create_backends` now
+  returns that reader directly, as the Spark provider already did. The
+  executor's own `StreamingSourceReader` check consequently inspects the
+  reader instead of the wrapper, which satisfied the protocol whatever it
+  wrapped, and a step that asks for a streaming read its reader cannot serve
+  is now refused by that check, naming the reader.
+- **etl:** the writer registry names the `TargetWriter` protocol instead of
+  `Any`. That surfaced `ClickHouseTargetWriter.write` declaring a narrower
+  spec type than the protocol it is dispatched through; it now accepts the
+  protocol's type and refuses a spec of another kind with a `TypeError`,
+  which the registry's dispatch by kind already made unreachable.
+
+# 🚀 Release 2.1.2 ([#238](https://github.com/the-reacher-data/loom-py/pull/238))
+
+## 🐛 Fixes
+
 ### prefect
 
 - **prefect:** a correlation id renders its datetime's UTC instant instead of
@@ -15,6 +70,12 @@
   `20260602T220000`), so do not upgrade across a run you intend to resume
   from its manifest.
 
+# 🚀 Release 2.1.1 ([#236](https://github.com/the-reacher-data/loom-py/pull/236))
+
+## 🐛 Fixes
+
+### prefect
+
 - **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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.1.2
+Version: 2.1.4
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed
@@ -57,7 +57,7 @@ Requires-Dist: opentelemetry-api<2.0,>=1.27; extra == 'etl-polars'
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0,>=1.27; extra == 'etl-polars'
 Requires-Dist: opentelemetry-exporter-otlp-proto-http<2.0,>=1.27; extra == 'etl-polars'
 Requires-Dist: opentelemetry-sdk<2.0,>=1.27; extra == 'etl-polars'
-Requires-Dist: polars<2.0,>=1.0; extra == 'etl-polars'
+Requires-Dist: polars<2.0,>=1.24; extra == 'etl-polars'
 Requires-Dist: pyarrow>=14.0; extra == 'etl-polars'
 Provides-Extra: etl-spark
 Requires-Dist: delta-spark<4.0,>=3.2; extra == 'etl-spark'

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/pyproject.toml

@@ -61,7 +61,7 @@ cache = [
     "omegaconf>=2.3,<3.0",
 ]
 etl-polars = [
-    "polars>=1.0,<2.0",
+    "polars>=1.24,<2.0",
     "deltalake>=1.6.2,<2.0",
     "pyarrow>=14.0",
     "fsspec>=2024.2.0",
@@ -230,7 +230,7 @@ dev = [
     "redis>=5.0.0",
     "ruff>=0.9.0,<1.0",
     "sqlalchemy>=2.0,<3.0",
-    "polars>=1.0,<2.0",
+    "polars>=1.24,<2.0",
     "clickhouse-connect>=0.9.2,<1.0",
     "pyarrow>=14.0",
     "deltalake>=1.6.2,<2.0",

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/src/loom/core/model/base.py

@@ -10,6 +10,9 @@ from loom.core.model.projection import Projection
 from loom.core.model.relation import Relation
 from loom.core.model.struct import LoomStruct
 
+if sys.version_info >= (3, 14):
+    import annotationlib
+
 if TYPE_CHECKING:
 
     class _StructMeta(type):
@@ -20,12 +23,25 @@ else:
 
 def _resolve_annotation(annotation: Any, namespace: dict[str, Any]) -> Any:
     """Resolve a stringified annotation to its actual type."""
-    if isinstance(annotation, str):
-        eval_ns: dict[str, Any] = {}
-        eval_ns.update(namespace)
-        eval_ns.setdefault("typing", typing)
-        return typing.ForwardRef(annotation)._evaluate(eval_ns, eval_ns, frozenset[str]())
-    return annotation
+    if not isinstance(annotation, str):
+        return annotation
+    holder = type("_AnnotationHolder", (), {"__annotations__": {"annotation": annotation}})
+    eval_ns = {"typing": typing, **namespace}
+    hints = typing.get_type_hints(holder, globalns=eval_ns, localns=eval_ns, include_extras=True)
+    return hints["annotation"]
+
+
+def _take_class_body_annotations(namespace: dict[str, Any]) -> dict[str, Any]:
+    if "__annotations__" in namespace:
+        annotations: dict[str, Any] = namespace["__annotations__"]
+        return annotations
+    if sys.version_info >= (3, 14):
+        annotate = annotationlib.get_annotate_from_class_namespace(namespace)
+        if annotate is not None:
+            namespace.pop("__annotate__", None)
+            namespace.pop("__annotate_func__", None)
+            return annotationlib.call_annotate_function(annotate, annotationlib.Format.VALUE)
+    return {}
 
 
 def _build_eval_namespace(namespace: dict[str, Any]) -> dict[str, Any]:
@@ -86,7 +102,7 @@ class LoomStructMeta(_StructMeta):
         columns: dict[str, ColumnFieldSpec] = {}
         relations: dict[str, Relation] = {}
         projections: dict[str, Projection] = {}
-        annotations: dict[str, Any] = namespace.get("__annotations__", {})
+        annotations = _take_class_body_annotations(namespace)
 
         eval_ns = _build_eval_namespace(namespace)
 

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/src/loom/etl/backends/polars/_historify.py

@@ -44,10 +44,12 @@ class PolarsHistorifyBackend:
         return frame.filter(pl.col(col) != expr)
 
     def anti_join(self, left: pl.DataFrame, right: pl.DataFrame, on: list[str]) -> pl.DataFrame:
-        return left.join(right, on=on, how="anti")
+        # `on` carries the tracked columns: a null must match itself or the row
+        # reads as changed and reopens on every run.
+        return left.join(right, on=on, how="anti", nulls_equal=True)
 
     def semi_join(self, left: pl.DataFrame, right: pl.DataFrame, on: list[str]) -> pl.DataFrame:
-        return left.join(right, on=on, how="semi")
+        return left.join(right, on=on, how="semi", nulls_equal=True)
 
     def union(self, frames: list[pl.DataFrame]) -> pl.DataFrame:
         return pl.concat([self._utc_datetimes(f) for f in frames], how="diagonal_relaxed")
@@ -90,7 +92,9 @@ class PolarsHistorifyBackend:
         overwrite: tuple[str, ...],
     ) -> pl.DataFrame:
         overwrite_vals = incoming.select(join_key + list(overwrite))
-        return unchanged.drop(list(overwrite)).join(overwrite_vals, on=join_key, how="left")
+        return unchanged.drop(list(overwrite)).join(
+            overwrite_vals, on=join_key, how="left", nulls_equal=True
+        )
 
     def rewind_to(
         self,

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/src/loom/etl/backends/polars/provider.py

@@ -6,7 +6,7 @@ from typing import Any, cast
 
 from loom.etl.backends.polars._reader import PolarsSourceReader
 from loom.etl.backends.polars._writer import PolarsTargetWriter
-from loom.etl.io._registry import ReaderRegistry, WriterRegistry
+from loom.etl.io._registry import WriterRegistry
 from loom.etl.io.sources._clickhouse import ClickHouseSourceReader
 from loom.etl.io.sources._dynamodb import DynamoDbSourceReader
 from loom.etl.io.sources._mongo import MongoSourceReader
@@ -48,7 +48,6 @@ class PolarsProvider(BackendProvider):
             clickhouse_reader=clickhouse_reader,
             dynamodb_reader=dynamodb_reader,
         )
-        reader = ReaderRegistry(polars_reader)
         polars_writer = PolarsTargetWriter(
             locator,
             missing_table_policy=config.missing_table_policy,
@@ -63,7 +62,7 @@ class PolarsProvider(BackendProvider):
             )
         else:
             writer = polars_writer
-        return (reader, writer)
+        return (polars_reader, writer)
 
     def create_lineage_writer(
         self,

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/src/loom/etl/backends/spark/_historify.py

@@ -46,10 +46,22 @@ class SparkHistorifyBackend:
         return frame.filter(F.col(col) != expr)
 
     def anti_join(self, left: DataFrame, right: DataFrame, on: list[str]) -> DataFrame:
-        return left.join(right, on=on, how="left_anti")
+        return left.join(right, on=self._null_safe_condition(left, right, on), how="left_anti")
 
     def semi_join(self, left: DataFrame, right: DataFrame, on: list[str]) -> DataFrame:
-        return left.join(right, on=on, how="left_semi")
+        return left.join(right, on=self._null_safe_condition(left, right, on), how="left_semi")
+
+    @staticmethod
+    def _null_safe_condition(left: DataFrame, right: DataFrame, on: list[str]) -> Any:
+        # eqNullSafe: a null in a tracked column must compare equal to itself,
+        # not act as SQL NULL (never matches). Otherwise a null-valued row is
+        # forever "changed" and reopened on every run. left_semi/left_anti only
+        # project the left side, so an explicit condition (vs. `on=list`) does
+        # not introduce duplicate key columns here.
+        condition = left[on[0]].eqNullSafe(right[on[0]])
+        for col in on[1:]:
+            condition = condition & left[col].eqNullSafe(right[col])
+        return condition
 
     def union(self, frames: list[DataFrame]) -> DataFrame:
         result = frames[0]
@@ -95,8 +107,21 @@ class SparkHistorifyBackend:
         join_key: list[str],
         overwrite: tuple[str, ...],
     ) -> DataFrame:
+        # eqNullSafe join_key: same null-safety as anti_join/semi_join, so an
+        # entity whose join_key includes a null track column still matches its
+        # own overwrite row. An explicit condition (vs. `on=list`) does not
+        # dedupe the key columns, so rename incoming's copy and drop it after.
+        key_rename = {k: f"__ov_key_{k}__" for k in join_key}
         overwrite_vals = incoming.select(join_key + list(overwrite))
-        return unchanged.drop(*overwrite).join(overwrite_vals, on=join_key, how="left")
+        for old, new in key_rename.items():
+            overwrite_vals = overwrite_vals.withColumnRenamed(old, new)
+
+        condition = F.col(join_key[0]).eqNullSafe(F.col(key_rename[join_key[0]]))
+        for k in join_key[1:]:
+            condition = condition & F.col(k).eqNullSafe(F.col(key_rename[k]))
+
+        joined = unchanged.drop(*overwrite).join(overwrite_vals, condition, how="left")
+        return joined.drop(*key_rename.values())
 
     def rewind_to(
         self,

loom_kernel-2.1.4/src/loom/etl/io/_registry.py

@@ -0,0 +1,54 @@
+"""Dispatch registry that routes a target spec to the writer registered for its kind."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from loom.etl.declarative.target import TargetSpec
+from loom.etl.runtime.contracts import TargetWriter
+
+if TYPE_CHECKING:
+    from loom.etl.lineage._records import WriteContext
+
+
+class WriterRegistry:
+    """Dispatch a write to the writer registered for the spec's kind, or to the base writer.
+
+    Args:
+        base: Writer every spec whose kind is not in *extra* is written through.
+        extra: Writers by ``spec.kind``.
+    """
+
+    def __init__(
+        self,
+        base: TargetWriter,
+        *,
+        extra: Mapping[str, TargetWriter] | None = None,
+    ) -> None:
+        self._base = base
+        self._extra: Mapping[str, TargetWriter] = extra or {}
+
+    def write(
+        self,
+        frame: Any,
+        spec: TargetSpec,
+        params: Any,
+        /,
+        *,
+        streaming: bool = False,
+        write_ctx: WriteContext | None = None,
+    ) -> None:
+        """Write *frame* into *spec* through its kind's writer, or through the base writer.
+
+        Args:
+            frame: Frame returned by the step's ``execute()``.
+            spec: Compiled target specification.
+            params: Concrete params for current run.
+            streaming: Hint for lazy backends to use streaming materialization.
+            write_ctx: Execution context for audit-column injection.
+        """
+        kind = getattr(spec, "kind", None)
+        handler = self._extra.get(kind) if kind is not None else None
+        writer = handler if handler is not None else self._base
+        writer.write(frame, spec, params, streaming=streaming, write_ctx=write_ctx)

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/src/loom/etl/io/targets/_clickhouse.py

@@ -15,6 +15,7 @@ except ImportError:
     _clickhouse_connect = None
 
 from loom.core.logger import get_logger
+from loom.etl.declarative.target import TargetSpec
 from loom.etl.declarative.target._client import ClientSpec
 
 _log = get_logger(__name__)
@@ -108,7 +109,7 @@ class ClickHouseTargetWriter:
     def write(
         self,
         frame: Any,
-        spec: ClickHouseTableSpec,
+        spec: ClickHouseTableSpec | TargetSpec,
         params: Any,
         /,
         *,
@@ -137,6 +138,12 @@ class ClickHouseTargetWriter:
                 "ClientStep execution is routed by ETLExecutor before write() is called. "
                 "This is an internal error — ClientSpec should never reach write()."
             )
+        if not isinstance(spec, ClickHouseTableSpec):
+            raise TypeError(
+                f"ClickHouseTargetWriter.write() does not handle {type(spec).__qualname__}. "
+                "The writer registry dispatches a spec to this writer by its 'clickhouse' "
+                "kind, so this is an internal error."
+            )
         _ = write_ctx
         engine: Literal["streaming", "auto"] = "streaming" if streaming else "auto"
         df: pl.DataFrame = (

loom_kernel-2.1.4/tests/unit/core/model/test_annotation_resolution.py

@@ -0,0 +1,59 @@
+import msgspec
+import pytest
+from msgspec import UnsetType
+
+from loom.core.model import BaseModel, Cardinality, ColumnField, ProjectionField, RelationField
+
+
+def _field_types(model: type[msgspec.Struct]) -> dict[str, object]:
+    return {field.name: field.type for field in msgspec.structs.fields(model)}
+
+
+def test_annotations_become_fields_and_relations_are_widened() -> None:
+    class Page(msgspec.Struct):
+        number: int
+
+    class Chapter(BaseModel):
+        __tablename__ = "annotation_resolution_chapters"
+        id: int = ColumnField(primary_key=True, autoincrement=True)
+        pages: list[Page] = RelationField(
+            foreign_key="chapter_id",
+            cardinality=Cardinality.ONE_TO_MANY,
+        )
+        page_count: int = ProjectionField(loader=None, default=0)
+
+    assert _field_types(Chapter) == {
+        "id": int,
+        "pages": list[Page] | UnsetType,
+        "page_count": int | UnsetType,
+    }
+    assert getattr(Chapter, "__annotate__", None) is None
+
+
+def test_subclass_without_annotations_keeps_inherited_fields() -> None:
+    class Shelf(BaseModel):
+        __tablename__ = "annotation_resolution_shelves"
+        id: int = ColumnField(primary_key=True, autoincrement=True)
+
+    class ArchivedShelf(Shelf):
+        pass
+
+    assert _field_types(ArchivedShelf) == _field_types(Shelf)
+
+
+@pytest.mark.parametrize("header", ["", "from __future__ import annotations\n"])
+def test_an_undefined_annotation_name_fails_at_class_creation(header: str) -> None:
+    source = (
+        f"{header}"
+        "class Broken(BaseModel):\n"
+        "    loans: list[Missing] = RelationField(\n"
+        "        foreign_key='broken_id', cardinality=ONE_TO_MANY\n"
+        "    )\n"
+    )
+    namespace = {
+        "BaseModel": BaseModel,
+        "RelationField": RelationField,
+        "ONE_TO_MANY": Cardinality.ONE_TO_MANY,
+    }
+    with pytest.raises(NameError, match="Missing"):
+        exec(source, namespace)

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/tests/unit/core/model/test_model.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
+from typing import Annotated
+
 import msgspec
 import pytest
+from msgspec import UnsetType
 
 from loom.core.model import (
     BaseModel,
@@ -38,6 +41,12 @@ class _Product(BaseModel):
         depends_on=("reviews:product_id",),
         default=0,
     )
+    rating: Annotated[int, "stars"] = ProjectionField(loader=None, default=0)
+
+
+def test_annotated_projection_keeps_its_metadata() -> None:
+    types = {field.name: field.type for field in msgspec.structs.fields(_Product)}
+    assert types["rating"] == Annotated[int, "stars"] | UnsetType
 
 
 class TestModelIntrospection:

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/tests/unit/etl/backends/_historify_contract.py

@@ -337,6 +337,94 @@ class HistorifyContractTests:
         rows = read_table(self._uri(root))
         assert rows[0]["valid_from"] == date(2024, 1, 1)
 
+    # ------------------------------------------------------------------
+    # Null-safe track comparison (no-op when the tracked value is null)
+    # ------------------------------------------------------------------
+
+    def test_null_tracked_value_is_stable_across_runs(
+        self,
+        writer: Any,
+        root: Path,
+        make_frame: Callable,
+        read_table: Callable,
+    ) -> None:
+        """A track column that is null in both existing and incoming rows must
+        compare equal, not "changed" — a null must not reopen the vector on
+        every run."""
+        frame = make_frame([{"player_id": 1, "team_id": None}, {"player_id": 2, "team_id": "RM"}])
+        writer.write(frame, _snapshot_spec(), _Params(run_date=date(2024, 1, 1)))
+        writer.write(frame, _snapshot_spec(), _Params(run_date=date(2024, 1, 2)))
+        rows = read_table(self._uri(root))
+        player_1 = [r for r in rows if r["player_id"] == 1]
+        assert len(player_1) == 1
+        assert player_1[0]["valid_from"] == date(2024, 1, 1)
+        assert player_1[0]["valid_to"] is None
+
+    def test_overwrite_refreshes_open_row_with_null_track(
+        self,
+        writer: Any,
+        root: Path,
+        make_frame: Callable,
+        read_table: Callable,
+    ) -> None:
+        """Overwrite must still land on the open row when join_key includes a
+        null track value — the overwrite join must be null-safe too."""
+        spec = _snapshot_spec(track=("team_id",), overwrite=("email",))
+        writer.write(
+            make_frame(
+                [
+                    {"player_id": 1, "team_id": None, "email": "old@x.com"},
+                    {"player_id": 2, "team_id": "RM", "email": "rm@x.com"},
+                ]
+            ),
+            spec,
+            _Params(run_date=date(2024, 1, 1)),
+        )
+        writer.write(
+            make_frame(
+                [
+                    {"player_id": 1, "team_id": None, "email": "new@x.com"},
+                    {"player_id": 2, "team_id": "RM", "email": "rm@x.com"},
+                ]
+            ),
+            spec,
+            _Params(run_date=date(2024, 6, 1)),
+        )
+        rows = read_table(self._uri(root))
+        player_1 = [r for r in rows if r["player_id"] == 1]
+        assert len(player_1) == 1
+        assert player_1[0]["email"] == "new@x.com"
+        assert player_1[0]["valid_from"] == date(2024, 1, 1)
+
+    def test_null_to_value_transition_closes_and_opens(
+        self,
+        writer: Any,
+        root: Path,
+        make_frame: Callable,
+        read_table: Callable,
+    ) -> None:
+        """A track column flipping null -> value is a real change: it must
+        close the old (null) vector and open a new one, same as any other
+        tracked change."""
+        spec = _snapshot_spec(track=("team_id",))
+        writer.write(
+            make_frame([{"player_id": 1, "team_id": None}, {"player_id": 2, "team_id": "RM"}]),
+            spec,
+            _Params(run_date=date(2024, 1, 1)),
+        )
+        writer.write(
+            make_frame([{"player_id": 1, "team_id": "BCA"}, {"player_id": 2, "team_id": "RM"}]),
+            spec,
+            _Params(run_date=date(2024, 6, 1)),
+        )
+        rows = read_table(self._uri(root))
+        player_1 = sorted((r for r in rows if r["player_id"] == 1), key=lambda r: r["valid_from"])
+        assert len(player_1) == 2
+        assert player_1[0]["team_id"] is None
+        assert player_1[0]["valid_to"] == date(2024, 5, 31)
+        assert player_1[1]["team_id"] == "BCA"
+        assert player_1[1]["valid_to"] is None
+
     # ------------------------------------------------------------------
     # New entity
     # ------------------------------------------------------------------

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/tests/unit/etl/backends/test_polars/test_provider_optional_mongo.py

@@ -38,7 +38,7 @@ def test_provider_imports_with_pymongo_hidden(tmp_path: Path) -> None:
     )
 
     assert result.returncode == 0, result.stderr
-    assert result.stdout.split() == ["ReaderRegistry", "PolarsTargetWriter"]
+    assert result.stdout.split() == ["PolarsSourceReader", "PolarsTargetWriter"]
 
 
 def test_mongo_source_without_pymongo_names_the_extra(

{loom_kernel-2.1.2 → loom_kernel-2.1.4}/tests/unit/etl/io/targets/test_clickhouse_writer.py

@@ -104,3 +104,16 @@ class TestMissingDependency:
             pytest.raises(ImportError, match="clickhouse-connect"),
         ):
             ClickHouseTargetWriter(_URL)
+
+
+class _DeltaSpec:
+    kind = "delta"
+
+
+class TestSpecGuards:
+    def test_a_spec_of_another_kind_is_refused(self) -> None:
+        writer, client = _make_writer()
+
+        with pytest.raises(TypeError, match="does not handle _DeltaSpec"):
+            writer.write(pl.DataFrame({"a": [1]}), _DeltaSpec(), _PARAMS)  # type: ignore[arg-type]
+        client.insert_df.assert_not_called()