loom-kernel 9.1.0__tar.gz → 9.2.0__tar.gz

{loom_kernel-9.1.0 → loom_kernel-9.2.0}/CHANGELOG.md

@@ -23,6 +23,58 @@
   update and unmatched insert, with no delete clause. `UpsertSpec` gains
   `delete_flag`; `UpsertDeleteFlagError` and
   `UnsupportedUpsertDeleteFlagError` are exported from `loom.etl`.
+- **etl:** `PolarsStepRunner` tests steps that use temps and real Delta
+  targets. `FromTemp`/`IntoTemp` work through an in-memory `CheckpointStore`
+  that keeps the production checks (an `IntoTemp` step returning a
+  `pl.DataFrame` raises `TypeError`, fan-in aligns to the first schema,
+  RUN then CORRELATION lookup); temps persist across `run()` calls of one
+  runner, which keeps a fixed run context. `seed_temp(name, data, columns,
+  *, schema=)` seeds a temp by `temp_name` from row tuples or a Polars frame;
+  `seed_temp(result)` seeds the `StepResult` of an `IntoTemp` step under the
+  name it wrote. A seeded temp lives in RUN scope, which `FromTemp` reads
+  before CORRELATION scope. A step whose target is `IntoTemp` returns, as its
+  `StepResult`, the temp read from the scope the step wrote (the accumulated
+  temp for fan-in) instead of raising "Step produced no output". `seed` and
+  `ETLScenario.with_table` accept `schema=` (loom types) so empty and all-null
+  columns keep their dtype. `PolarsStepRunner(*scenarios, delta_root=)`
+  applies scenarios at construction; with `delta_root` the real
+  `PolarsSourceReader`/`PolarsTargetWriter` run on that directory, seeds are
+  written as Delta tables (a column left without dtype raises `SchemaError`
+  asking for `schema=`), missing targets are created, and `table(ref)`
+  returns the final state. `StepResult` keeps the step's `target` spec and
+  derives `temp_name` and `delete_flag` from it. `StepResult.deletes` counts
+  the rows the step emitted with its upsert `delete_flag` set, and raises
+  `UpsertDeleteFlagError` when the output lacks the flag column or it is not
+  boolean; `StepResult.merged` returns the `MergeMetrics(inserted, updated,
+  deleted)` the Delta MERGE applied, only with `delta_root` and an upsert or
+  update that merged into an existing table. `ETLScenario` gains `with_temp`,
+  `after(step, params)` and `+`. `after()` runs the `IntoTemp` step once, on
+  a fresh in-memory runner seeded only with the scenario entries before it
+  (not the runner's config or other seeds), and seeds the memoized output on
+  every application. The scenario `repr` lists `tables`, `temps` and
+  `after` separately.
+  `SparkStepRunner.seed_temp` and `SparkStepRunner.seed(..., schema=...)`
+  raise `NotImplementedError`. Cache scenarios and frames, not runners: tests
+  that mutate state need a function-scoped runner on their own `tmp_path`.
+
+## ⚠ Behaviour changes
+
+### etl
+
+- **etl:** the `PolarsStepRunner` reader applies what a `FromTable` or
+  `FromFile` declares, as `PolarsSourceReader` does: `.where()` filters,
+  `.columns()` projects (an unknown column raises
+  `polars.exceptions.ColumnNotFoundError`), `with_schema` casts and
+  `parse_json` decodes. Before, the seeded frame reached the step unchanged;
+  a seed that was already decoded for a `parse_json` column must now hold the
+  JSON text.
+- **etl:** `ETLScenario` is immutable: `with_table` returns a new scenario
+  and no longer changes the one it is called on. Chained calls work as before;
+  code that called `scenario.with_table(...)` without using the result must
+  use it.
+- **etl:** `StepRunnerProto` requires `seed(..., *, schema=None)`,
+  `seed_temp` and `run`. `ETLScenario.apply` still calls `seed(ref, data,
+  columns)` positionally when no schema is declared.
 
 # 🚀 Releases 2.1.3 to 9.0.0
 

{loom_kernel-9.1.0 → loom_kernel-9.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 9.1.0
+Version: 9.2.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3

{loom_kernel-9.1.0 → loom_kernel-9.2.0}/src/loom/etl/backends/polars/_reader.py

@@ -296,17 +296,13 @@ class PolarsSourceReader(SourceReader):
             target.location.uri,
             storage_options=target.location.storage_options or None,
         )
-
-        for predicate in spec.predicates:
-            frame = frame.filter(predicate_to_polars(predicate, params))
-
-        return self._finalize_source_frame(frame, spec)
+        return _finalize_source_frame(frame, spec, params)
 
     def _read_file(self, spec: FileSourceSpec, params_instance: Any) -> pl.LazyFrame:
         """Read file (CSV, JSON, XLSX, Parquet), resolving alias if needed."""
         path = self._resolve_file_path(spec, params_instance)
         frame = self._read_file_by_format(path, spec.format, spec.read_options)
-        return self._finalize_source_frame(frame, spec)
+        return _finalize_source_frame(frame, spec, params_instance)
 
     def _resolve_file_path(self, spec: FileSourceSpec, params_instance: Any) -> str:
         """Return the physical URI for *spec*, resolving alias and template."""
@@ -318,20 +314,6 @@ class PolarsSourceReader(SourceReader):
             role="FromFile",
         )
 
-    def _finalize_source_frame(
-        self,
-        frame: pl.LazyFrame,
-        spec: TableSourceSpec | FileSourceSpec,
-    ) -> pl.LazyFrame:
-        """Apply post-read transformations: columns, schema, json decode."""
-        if spec.columns:
-            frame = frame.select(list(spec.columns))
-        if spec.schema:
-            frame = self._apply_source_schema(frame, spec.schema)
-        if spec.json_columns:
-            frame = decode_json_columns(frame, spec.json_columns)
-        return frame
-
     @staticmethod
     def _read_file_by_format(path: str, format: Any, options: Any) -> pl.LazyFrame:
         """Dispatch to format-specific reader."""
@@ -380,14 +362,42 @@ class PolarsSourceReader(SourceReader):
     def _read_parquet(path: str, _options: Any) -> pl.LazyFrame:
         return pl.scan_parquet(path)
 
-    @staticmethod
-    def _apply_source_schema(frame: pl.LazyFrame, schema: tuple[ColumnSchema, ...]) -> pl.LazyFrame:
-        """Cast declared columns to their Loom type."""
-        if not schema:
-            return frame
 
-        cast_exprs = [pl.col(col.name).cast(loom_type_to_polars(col.dtype)) for col in schema]
-        return frame.with_columns(cast_exprs)
+def _finalize_source_frame(
+    frame: pl.LazyFrame,
+    spec: TableSourceSpec | FileSourceSpec,
+    params_instance: Any,
+) -> pl.LazyFrame:
+    """Apply what *spec* declares on top of a raw scan, as :class:`PolarsSourceReader` does.
+
+    Filters by the table predicates first, then projects ``columns``, casts the
+    declared ``schema`` and decodes ``json_columns``.  Returns *frame* itself
+    when the spec declares none of them.
+
+    Args:
+        frame: Raw frame scanned or seeded for the source.
+        spec: Compiled table or file source spec.
+        params_instance: Concrete params the predicates resolve against.
+
+    Returns:
+        The lazy frame the step receives.
+    """
+    if isinstance(spec, TableSourceSpec):
+        for predicate in spec.predicates:
+            frame = frame.filter(predicate_to_polars(predicate, params_instance))
+    if spec.columns:
+        frame = frame.select(list(spec.columns))
+    if spec.schema:
+        frame = _apply_source_schema(frame, spec.schema)
+    if spec.json_columns:
+        frame = decode_json_columns(frame, spec.json_columns)
+    return frame
+
+
+def _apply_source_schema(frame: pl.LazyFrame, schema: tuple[ColumnSchema, ...]) -> pl.LazyFrame:
+    """Cast declared columns to their Loom type."""
+    cast_exprs = [pl.col(col.name).cast(loom_type_to_polars(col.dtype)) for col in schema]
+    return frame.with_columns(cast_exprs)
 
 
 def execute_sql(frames: dict[str, pl.LazyFrame], query: str) -> pl.LazyFrame:

{loom_kernel-9.1.0 → loom_kernel-9.2.0}/src/loom/etl/backends/polars/_writer.py

@@ -7,6 +7,7 @@ from typing import Any, Literal
 
 import polars as pl
 from deltalake import CommitProperties, DeltaTable, WriterProperties, write_deltalake
+from deltalake.exceptions import TableNotFoundError
 from deltalake.table import TableMerger
 
 from loom.core.logger import get_logger
@@ -57,6 +58,7 @@ from ._file_writer import PolarsFileWriter
 from ._streaming import partition_rows_from_spool, spool_lazy_to_arrow_reader
 
 _log = get_logger(__name__)
+_COMMIT_EVENT = "delta write commit"
 
 
 def _log_write_start(
@@ -78,23 +80,39 @@ def _log_write_start(
     )
 
 
+def _open_delta_table(location: TableLocation) -> DeltaTable | None:
+    """Open the Delta table at *location*, or return ``None`` when it does not exist."""
+    try:
+        return DeltaTable(location.uri, storage_options=location.storage_options or None)
+    except TableNotFoundError:
+        return None
+
+
+def _last_commit(table: DeltaTable) -> tuple[int, dict[str, Any]]:
+    """Return the version of *table* and its latest commit entry (empty without history)."""
+    history = table.history(1)
+    return table.version(), (history[0] if history else {})
+
+
 def _log_write_commit(mode: str, location: TableLocation) -> None:
     try:
-        dt = DeltaTable(location.uri, storage_options=location.storage_options or {})
-        history = dt.history(1)
-        entry = history[0] if history else {}
+        dt = _open_delta_table(location)
+        if dt is None:
+            _log.info(_COMMIT_EVENT, mode=mode, uri=location.uri, metrics="unavailable")
+            return
+        version, entry = _last_commit(dt)
         metrics = entry.get("operationMetrics") or {}
         _log.info(
-            "delta write commit",
+            _COMMIT_EVENT,
             mode=mode,
             uri=location.uri,
-            version=dt.version(),
+            version=version,
             rows=int(metrics.get("numOutputRows", 0)) or None,
             bytes=int(metrics.get("numOutputBytes", 0)) or None,
             files=int(metrics.get("numAddedFiles", 0)) or None,
         )
     except Exception:  # noqa: BLE001
-        _log.info("delta write commit", mode=mode, uri=location.uri, metrics="unavailable")
+        _log.info(_COMMIT_EVENT, mode=mode, uri=location.uri, metrics="unavailable")
 
 
 def _check_null_dtype_columns_lazy(frame: pl.LazyFrame) -> None:
@@ -133,7 +151,15 @@ def _require_delete_flag(frame: pl.LazyFrame, spec: UpsertSpec, flag: str) -> No
             flag,
             f"conflicts with {conflict}; the flag column is not written to the target",
         )
-    schema = frame.collect_schema()
+    _require_boolean_flag_column(frame.collect_schema(), flag)
+
+
+def _require_boolean_flag_column(schema: pl.Schema, flag: str) -> None:
+    """Check that *schema* has *flag* as a boolean column.
+
+    Raises:
+        UpsertDeleteFlagError: *flag* is missing from *schema*, or is not boolean.
+    """
     if flag not in schema:
         raise UpsertDeleteFlagError(flag, "is missing from the source frame")
     dtype = schema[flag]

loom_kernel-9.2.0/src/loom/etl/checkpoint/_backends/_memory.py

@@ -0,0 +1,60 @@
+"""In-memory Polars backend for CheckpointStore, used by the step test runners."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import polars as pl
+
+from loom.etl.checkpoint._backends._polars import (
+    _align_lazy_to_schema,
+    _checkpoint_key,
+    _require_polars_lazy_frame,
+)
+
+
+class _InMemoryCheckpointBackend:
+    """Polars checkpoint backend holding collected frames in a dict.
+
+    Keeps the checks of the Arrow IPC backend: only a ``LazyFrame`` is accepted,
+    and a fan-in write is aligned to the schema of the first write for that name.
+    Frames are collected at write time, so errors surface at the write like the
+    real materialisation does.  It remembers the last intermediate written, so a
+    runner can return what a step wrote without rebuilding scope paths.  Not
+    thread-safe: one instance serves one runner.
+    """
+
+    def __init__(self) -> None:
+        self._parts: dict[str, list[pl.DataFrame]] = {}
+        self._schemas: dict[str, pl.Schema] = {}
+        self._last_key: str | None = None
+
+    def probe(self, name: str, base: str) -> pl.LazyFrame | None:
+        """Return the concatenated parts stored for *name* under *base*, or ``None``."""
+        return self._probe_key(_checkpoint_key(name, base))
+
+    def probe_last(self) -> pl.LazyFrame | None:
+        """Return the intermediate of the last :meth:`write`, or ``None`` before any."""
+        return None if self._last_key is None else self._probe_key(self._last_key)
+
+    def write(self, name: str, base: str, data: Any, *, append: bool) -> None:
+        """Store *data* for *name* under *base*, appending a part in fan-in mode."""
+        frame = _require_polars_lazy_frame(data)
+        key = _checkpoint_key(name, base)
+        existing = self._schemas.get(key)
+        if existing is None:
+            self._schemas[key] = frame.collect_schema()
+        elif append:
+            frame = _align_lazy_to_schema(frame, existing)
+        collected = frame.collect()
+        if append:
+            self._parts.setdefault(key, []).append(collected)
+        else:
+            self._parts[key] = [collected]
+        self._last_key = key
+
+    def _probe_key(self, key: str) -> pl.LazyFrame | None:
+        parts = self._parts.get(key)
+        if not parts:
+            return None
+        return pl.concat(parts, how="vertical").lazy()

{loom_kernel-9.1.0 → loom_kernel-9.2.0}/src/loom/etl/checkpoint/_backends/_polars.py

@@ -23,6 +23,20 @@ def _is_polars_lazy_frame(value: Any) -> TypeGuard[pl.LazyFrame]:
     return isinstance(value, pl.LazyFrame)
 
 
+def _require_polars_lazy_frame(data: Any) -> pl.LazyFrame:
+    """Return *data* as a LazyFrame, or raise the error every Polars backend raises.
+
+    Raises:
+        TypeError: When *data* is not a :class:`polars.LazyFrame`.
+    """
+    if not _is_polars_lazy_frame(data):
+        raise TypeError(
+            f"Polars backend expects polars.LazyFrame, got {type(data).__qualname__!r}. "
+            "Verify that CheckpointStore was constructed without a SparkSession."
+        )
+    return data
+
+
 class _PolarsCheckpointBackend:
     """Polars Arrow IPC backend with atomic write-then-rename."""
 
@@ -47,14 +61,8 @@ class _PolarsCheckpointBackend:
 
     def write(self, name: str, base: str, data: Any, *, append: bool) -> None:
         """Sink *data* as Arrow IPC atomically (write-then-rename)."""
-        if not _is_polars_lazy_frame(data):
-            raise TypeError(
-                f"Polars backend expects polars.LazyFrame, got {type(data).__qualname__!r}. "
-                "Verify that CheckpointStore was constructed without a SparkSession."
-            )
-
-        frame = data
-        key = f"{base}/{name}"
+        frame = _require_polars_lazy_frame(data)
+        key = _checkpoint_key(name, base)
 
         with self._lock:
             existing = self._schemas.get(key)
@@ -82,6 +90,11 @@ class _PolarsCheckpointBackend:
         return None
 
 
+def _checkpoint_key(name: str, base: str) -> str:
+    """Return the key identifying the intermediate *name* under *base*."""
+    return f"{base}/{name}"
+
+
 def _arrow_path(name: str, base: str) -> str:
     return _join_path(base, f"{name}.arrow")
 

{loom_kernel-9.1.0 → loom_kernel-9.2.0}/src/loom/etl/testing/__init__.py

@@ -6,9 +6,11 @@ Public API
 * :class:`StubSourceReader` — in-memory reader, keyed by table reference.
 * :class:`StubTargetWriter` — in-memory writer that captures written frames.
 * :class:`StubRunObserver` — in-memory observer that records lifecycle events.
-* :class:`PolarsStepRunner` — Polars-backed in-memory step harness.
+* :class:`PolarsStepRunner` — Polars step harness, in memory or on a local
+  Delta root (``delta_root=``).
 * :class:`StepResult` — unified assertion surface for step output.
-* :class:`ETLScenario` — backend-agnostic reusable seed dataset.
+* :class:`MergeMetrics` — rows a Delta MERGE applied (``StepResult.merged``).
+* :class:`ETLScenario` — backend-agnostic, immutable, composable seed dataset.
 * :class:`StepRunnerProto` — protocol satisfied by both runner types.
 
 Pytest fixtures
@@ -36,7 +38,7 @@ except ModuleNotFoundError as exc:  # pragma: no cover - packaging guard
         "loom.etl.testing defines pytest fixtures: install loom-kernel[testing]"
     ) from exc
 
-from loom.etl.testing._result import StepResult
+from loom.etl.testing._result import MergeMetrics, StepResult
 from loom.etl.testing._runners import PolarsStepRunner
 from loom.etl.testing._scenario import ETLScenario, StepRunnerProto
 from loom.etl.testing._stubs import (
@@ -53,6 +55,7 @@ __all__ = [
     "StubRunObserver",
     "PolarsStepRunner",
     "StepResult",
+    "MergeMetrics",
     "ETLScenario",
     "StepRunnerProto",
 ]

loom_kernel-9.2.0/src/loom/etl/testing/_delta.py

@@ -0,0 +1,86 @@
+"""Delta root of a ``PolarsStepRunner(delta_root=...)``: real reader and writer on one root."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+
+from loom.etl.backends.polars import PolarsSourceReader, PolarsTargetWriter
+from loom.etl.backends.polars._writer import _last_commit, _open_delta_table
+from loom.etl.declarative.expr._refs import TableRef
+from loom.etl.declarative.source import TableSourceSpec
+from loom.etl.declarative.target import SchemaMode, TargetSpec
+from loom.etl.declarative.target._table import ReplaceSpec, UpdateSpec, UpsertSpec
+from loom.etl.storage import MissingTablePolicy, PrefixLocator
+from loom.etl.testing._result import MergeMetrics
+
+_MERGE = "MERGE"
+
+
+class _DeltaRoot:
+    """One local Delta root whose tables are read and written as production does.
+
+    :meth:`write` is a target writer: it delegates to the real
+    :class:`PolarsTargetWriter` and keeps, in :attr:`last_merge`, what the
+    MERGE of an upsert or update applied.
+
+    Args:
+        root: Local directory holding the tables, e.g. pytest's ``tmp_path``.
+    """
+
+    def __init__(self, root: str | Path) -> None:
+        self._root = str(root)
+        self._locator = PrefixLocator(self._root)
+        self.reader = PolarsSourceReader(self._root)
+        self.writer = PolarsTargetWriter(self._root, missing_table_policy=MissingTablePolicy.CREATE)
+        self.last_merge: MergeMetrics | None = None
+
+    def seed(self, ref: str, frame: pl.LazyFrame) -> None:
+        """Write *frame* as the whole content of table *ref*, creating it if missing."""
+        spec = ReplaceSpec(table_ref=TableRef(ref), schema_mode=SchemaMode.OVERWRITE)
+        self.writer.write(frame, spec, None)
+
+    def read(self, ref: str) -> pl.DataFrame:
+        """Return the current content of table *ref*."""
+        spec = TableSourceSpec(alias=ref, table_ref=TableRef(ref))
+        return self.reader.read(spec, None).collect()
+
+    def write(
+        self,
+        frame: Any,
+        spec: TargetSpec,
+        params_instance: Any,
+        *,
+        streaming: bool = False,
+        write_ctx: Any = None,
+    ) -> None:
+        """Write with the real writer, recording the MERGE metrics of an upsert or update.
+
+        :attr:`last_merge` is ``None`` when the target is not an upsert or
+        update, or when the table did not exist and this write created it.
+        """
+        self.last_merge = None
+        table = None
+        if isinstance(spec, (UpsertSpec, UpdateSpec)):
+            table = _open_delta_table(self._locator.locate(spec.table_ref))
+        version_before = None if table is None else table.version()
+        self.writer.write(frame, spec, params_instance, streaming=streaming, write_ctx=write_ctx)
+        if table is None:
+            return
+        table.update_incremental()
+        version, commit = _last_commit(table)
+        if version == version_before:
+            self.last_merge = MergeMetrics(inserted=0, updated=0, deleted=0)
+        elif commit.get("operation") == _MERGE:
+            self.last_merge = _merge_metrics(commit.get("operationMetrics") or {})
+
+
+def _merge_metrics(metrics: dict[str, Any]) -> MergeMetrics:
+    """Read delta-rs MERGE ``operationMetrics`` (snake_case keys)."""
+    return MergeMetrics(
+        inserted=int(metrics.get("num_target_rows_inserted", 0)),
+        updated=int(metrics.get("num_target_rows_updated", 0)),
+        deleted=int(metrics.get("num_target_rows_deleted", 0)),
+    )

loom_kernel-9.2.0/src/loom/etl/testing/_result.py

@@ -0,0 +1,173 @@
+"""StepResult — unified assertion interface for step test output."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import polars as pl
+
+from loom.etl.backends.polars._writer import _require_boolean_flag_column
+from loom.etl.declarative.target import TargetSpec
+from loom.etl.declarative.target._table import UpsertSpec
+from loom.etl.declarative.target._temp import TempFanInSpec, TempSpec
+from loom.etl.schema._schema import LoomDtype
+
+
+@dataclass(frozen=True)
+class MergeMetrics:
+    """Rows a Delta MERGE applied to the target table.
+
+    Read from ``operationMetrics`` of the commit the step wrote.
+
+    Args:
+        inserted: Target rows inserted.
+        updated: Target rows updated.
+        deleted: Target rows deleted.
+    """
+
+    inserted: int
+    updated: int
+    deleted: int
+
+
+@dataclass(frozen=True)
+class StepResult:
+    """Output of a :class:`PolarsStepRunner` or :class:`SparkStepRunner` run.
+
+    Provides a backend-agnostic assertion surface.  The internal frame is
+    always a materialised ``polars.DataFrame`` — Spark results are converted
+    before constructing this object.
+
+    Two counts answer different questions about an upsert with ``delete_flag``:
+
+    * :attr:`deletes` — rows the step *emitted* with the flag set, before any
+      MERGE.  Available with or without ``delta_root``.
+    * :attr:`merged` — rows the MERGE *applied* to the table.  Only with
+      ``delta_root`` and an upsert or update target.
+
+    Args:
+        _frame: Materialised output frame.
+        target: Target spec of the step that produced the frame, if known.
+        merge_metrics: Metrics of the MERGE commit, set by a ``delta_root``
+            runner for upsert and update targets.
+
+    Example::
+
+        result = runner.run(MyStep, params)
+        result.assert_count(10)
+        result.assert_schema({"id": LoomDtype.INT64, "amount": LoomDtype.FLOAT64})
+        result.show()
+    """
+
+    _frame: pl.DataFrame
+    target: TargetSpec | None = None
+    merge_metrics: MergeMetrics | None = None
+
+    def to_polars(self) -> pl.DataFrame:
+        """Return the materialised output as a ``polars.DataFrame``."""
+        return self._frame
+
+    @property
+    def temp_name(self) -> str | None:
+        """Temp name when the step's target is ``IntoTemp``, else ``None``."""
+        if isinstance(self.target, (TempSpec, TempFanInSpec)):
+            return self.target.temp_name
+        return None
+
+    @property
+    def delete_flag(self) -> str | None:
+        """``delete_flag`` of the step's upsert target, else ``None``."""
+        if isinstance(self.target, UpsertSpec):
+            return self.target.delete_flag
+        return None
+
+    @property
+    def deletes(self) -> int:
+        """Rows the step emitted with the target's ``delete_flag`` set to true.
+
+        Counts the step output, not what the MERGE did: use :attr:`merged`
+        for that.
+
+        Raises:
+            RuntimeError: When the target is not an upsert with ``delete_flag``.
+            UpsertDeleteFlagError: When the output has no flag column, or it
+                is not boolean.
+        """
+        flag = self.delete_flag
+        if flag is None:
+            raise RuntimeError(
+                "deletes needs a step whose target is IntoTable(...).upsert(delete_flag=...)."
+            )
+        _require_boolean_flag_column(self._frame.schema, flag)
+        return int(self._frame.select(pl.col(flag).fill_null(False).sum()).item())
+
+    @property
+    def merged(self) -> MergeMetrics:
+        """Rows the MERGE applied to the target table.
+
+        Raises:
+            RuntimeError: When the runner has no ``delta_root``, the target is
+                not an upsert or update, or the target table did not exist and
+                was created by this write instead of merged.
+        """
+        if self.merge_metrics is None:
+            raise RuntimeError(
+                "merged is unavailable: no MERGE ran because the runner has no "
+                "delta_root, the target is not an upsert or update, "
+                "or the target table did not exist and was created by this write. "
+                "Check the final table with runner.table(ref).assert_count(n) instead."
+            )
+        return self.merge_metrics
+
+    def assert_schema(self, expected: dict[str, LoomDtype]) -> None:
+        """Assert that the output columns match the expected Loom schema.
+
+        Args:
+            expected: Mapping of column name → :class:`~loom.etl._schema.LoomDtype`.
+
+        Raises:
+            AssertionError: When a column is missing or has a different dtype.
+        """
+        from loom.etl.backends.polars._dtype import loom_type_to_polars
+
+        for col_name, loom_dtype in expected.items():
+            actual = self._frame.schema.get(col_name)
+            if actual is None:
+                raise AssertionError(f"Column '{col_name}' not found in result schema")
+            expected_polars = loom_type_to_polars(loom_dtype)
+            if actual != expected_polars:
+                raise AssertionError(
+                    f"Column '{col_name}': expected {expected_polars}, got {actual}"
+                )
+
+    def assert_count(self, n: int) -> None:
+        """Assert the result contains exactly *n* rows.
+
+        Args:
+            n: Expected row count.
+
+        Raises:
+            AssertionError: When the row count differs.
+        """
+        actual = len(self._frame)
+        if actual != n:
+            raise AssertionError(f"Expected {n} rows, got {actual}")
+
+    def assert_not_empty(self) -> None:
+        """Assert the result contains at least one row.
+
+        Raises:
+            AssertionError: When the result is empty.
+        """
+        if len(self._frame) <= 0:
+            raise AssertionError("Expected non-empty result, got 0 rows")
+
+    def show(self, n: int = 10) -> None:
+        """Print the first *n* rows to stdout.
+
+        Useful for visual inspection during ``pytest -s`` runs.
+
+        Args:
+            n: Number of rows to display. Defaults to 10.
+        """
+        print(self._frame.head(n))