loom-kernel 1.2.2__tar.gz → 1.4.0__tar.gz

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/CHANGELOG.md

@@ -1,3 +1,127 @@
+# 🚀 Release 1.4.0 ([#129](https://github.com/the-reacher-data/loom-py/pull/129)) ([`71520ce`](https://github.com/the-reacher-data/loom-py/commit/71520ce4840f8a3b9b914081704520f90d46b31e))
+
+
+## ✨ Features
+### streaming
+- **streaming:** structured compiler error codes and public compiler exports<br>
+  > Replace the compiler's bare list[str] failures with structured issues so a
+  > guided platform can map compilation errors to form fields, mirroring
+  > loom.etl's ETLErrorCode:
+  > New loom.streaming.compiler._errors with StreamingErrorCode (StrEnum
+  > covering the binding, validation, and plan-building phases, plus codes
+  > reserved for the delivery-semantics phase) and CompilationIssue
+  > (LoomFrozenStruct with code, message, component, field). All message
+  > formatting lives in per-code factory functions; validator call-sites stay
+  > intention-revealing.
+  > CompilationError now aggregates issues (.issues) while keeping the legacy
+  > .errors accessor and the exact aggregated message format. The constructor
+  > still accepts bare strings, normalized to code UNSPECIFIED.
+  > Branch validation scopes nested issues via CompilationIssue.prefixed(),
+  > preserving the historical "fork/router/broadcast branch X: ..." messages.
+  > Two previously uncoded build-phase failures now raise CompilationError
+  > with codes: STORAGE_SINK_UNSUPPORTED (was a bare ValueError) and
+  > PAYLOAD_TYPE_INVALID (was an unguarded AttributeError).
+  > validate.py no longer constructs UnsupportedNodeError/MissingSinkError just
+  > to str() them; the exception classes remain runtime errors of the adapter.
+  > Export symmetry: loom.streaming now exports CompilationError, CompiledPlan,
+  > CompilationIssue, and StreamingErrorCode; loom.streaming.compiler adds
+  > CompiledMongoCDCSource. Tests migrated from private to public import paths.
+
+
+
+## 🐛 Fixes
+### docs
+- **docs:** keep compilation types canonical in loom.streaming.compiler<br>
+  > The strict docs build (warnings-as-errors) rejected re-exporting
+  > CompilationError/CompilationIssue/CompiledPlan/StreamingErrorCode at the
+  > loom.streaming package level: both the package and loom.streaming.compiler
+  > pages are in the autosummary, so each symbol was documented twice and
+  > cross-references became ambiguous.
+  > Follow the real loom.etl convention instead: compilation types have a single
+  > canonical import path (loom.streaming.compiler) and the package front-page
+  > docstring points there, exactly like loom.etl does with ETLCompilationError.
+  > compile_flow stays exported at the package level as before.
+  > --------
+
+
+
+
+
+
+
+
+
+# 🚀 Release 1.3.0 ([#127](https://github.com/the-reacher-data/loom-py/pull/127)) ([`1fcaa1c`](https://github.com/the-reacher-data/loom-py/commit/1fcaa1ca1520db435d1ba4974284a96a35d2734f))
+
+
+## ✨ Features
+### etl
+- **etl:** update() — matched-only MERGE, the insert-less sibling of upsert<br>
+  > IntoTable(...).update(keys=..., include=/exclude=) issues the upsert
+  > MERGE WITHOUT when_not_matched_insert: source rows whose keys match are
+  > updated, rows without a match are IGNORED — nothing is ever inserted,
+  > by construction. This is the mode for repairing columns of an existing
+  > table (re-attribution), where an insert would be a bug that until now
+  > had to be guarded with row-count assertions outside the write.
+  > UpdateSpec keeps neutral public field names (keys/exclude/include) and
+  > exposes upsert_* read-only aliases that satisfy the shared _UpsertLike
+  > merge protocol, so the MERGE plan, the partition pre-filter and the
+  > compile-time key/exclude/include validators are reused untouched;
+  > compilation errors name update() instead of upsert(). A new compile
+  > guard rejects an include= fully absorbed by keys/partition_cols — in
+  > update() that write is a guaranteed no-op. At write time there is no
+  > creation path: a missing table is an error, never a create. Implemented
+  > in the Polars and Spark writers by factoring the shared merge up to
+  > when_matched_update.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01U65Md2FMcEaEgpZCKkYqGL
+
+- **etl:** IntoHistory joins the declared target union of ETLStep<br>
+  > It worked at runtime but mypy rejected the assignment on every step
+  > with a historified target. One line in the ClassVar (mirrored in
+  > ClientStep, which redeclares the same union — pyright requires the
+  > override to be identical) and a test pinning union membership via
+  > get_type_hints.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01U65Md2FMcEaEgpZCKkYqGL
+
+- **etl:** param exprs and path templates accept read-only params properties<br>
+  > A computed @property (e.g. partition_day) resolves at runtime through
+  > the same getattr chain as a struct field, but compile-time validation
+  > only looked at msgspec.structs.fields — forcing the filter down to
+  > runtime and losing the declarative pushdown. Now names resolving to a
+  > property on the CLASS (public properties only — no methods, no private
+  > names) count as known fields, symmetrically in validate_param_exprs and
+  > validate_file_path_templates; an unknown name still fails with the same
+  > error.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01U65Md2FMcEaEgpZCKkYqGL
+
+
+### prefect
+- **prefect:** "year" chunk in backfill_flow for overhead-dominated backfills<br>
+  > When backfill cost is dominated by per-chunk overhead rather than data
+  > volume (real case: 135 monthly chunks x ~2.5 min ≈ 6 h for a fact that
+  > resolves each chunk in seconds), a multi-year window drops to a handful
+  > of calendar-year chunks. Same algebra as month: floor to January 1,
+  > calendar-year advance, %Y label for correlation/run ids, and start_from
+  > resume intact. The docstrings call out that both documented window
+  > edges — the start floor and the finalize window_end pin — operate at
+  > year scale at this granularity.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01U65Md2FMcEaEgpZCKkYqGL
+  > --------
+  > Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
+
+
+
+
+
+
+
+
+
+
 # 🚀 Release 1.2.2 ([#124](https://github.com/the-reacher-data/loom-py/pull/124)) ([`ced8b6a`](https://github.com/the-reacher-data/loom-py/commit/ced8b6ab8bba62b7d34e57ad334d26f29af1e0c2))
 
 

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/PKG-INFO

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

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/docs/etl/pipelines.md

@@ -269,6 +269,21 @@ target = IntoTable("events.orders").upsert(
 `partition_cols` is optional but strongly recommended — without it every MERGE
 forces a full table scan.
 
+### update
+
+Matched-only MERGE. Rows whose keys match are updated; source rows without a
+match are ignored — nothing is ever inserted. Use it when an insert would be
+a bug, e.g. repairing columns of an existing table. The target table must
+already exist: a missing table is a write error, not a create.
+
+```python
+target = IntoTable("events.orders").update(
+    keys=("order_id",),
+    partition_cols=("year", "month"),  # strongly recommended for large tables
+    include=("status",),               # only these columns are updated
+)
+```
+
 ---
 
 ## Running only selected stages

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/docs/getting-started/etl.md

@@ -71,6 +71,7 @@ Every `IntoTable` target declares exactly one write mode by chaining a method.
 | `replace_partition` | Overwrite a single known partition | `IntoTable("staging.orders").replace_partition(year=params.run_date.year)` |
 | `replace_where` | Overwrite rows matching a predicate | `IntoTable("staging.orders").replace_where(col("date") == params.run_date)` |
 | `upsert` | Merge on key columns | `IntoTable("staging.orders").upsert(keys=("order_id",))` |
+| `update` | Update matching rows only — never inserts | `IntoTable("staging.orders").update(keys=("order_id",))` |
 
 See the [ETL pipelines guide](../etl/pipelines.md) for the full write-mode reference.
 

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/docs/guides/etl.md

@@ -269,6 +269,21 @@ target = IntoTable("events.orders").upsert(
 `partition_cols` is optional but strongly recommended — without it every MERGE
 forces a full table scan.
 
+### update
+
+Matched-only MERGE. Rows whose keys match are updated; source rows without a
+match are ignored — nothing is ever inserted. Use it when an insert would be
+a bug, e.g. repairing columns of an existing table. The target table must
+already exist: a missing table is a write error, not a create.
+
+```python
+target = IntoTable("events.orders").update(
+    keys=("order_id",),
+    partition_cols=("year", "month"),  # strongly recommended for large tables
+    include=("status",),               # only these columns are updated
+)
+```
+
 ### historify
 
 For SCD Type 2 history tracking use `IntoHistory` instead of `IntoTable`.
@@ -283,6 +298,7 @@ SNAPSHOT vs LOG mode, and configuration of boundary columns.
 | `IntoTable(...).replace_partition(...)` | Replace known partition | Above |
 | `IntoTable(...).replace_where(...)` | Predicate-based overwrite | Above |
 | `IntoTable(...).upsert(...)` | Merge by key | Above |
+| `IntoTable(...).update(...)` | Update matches only, never insert | Above |
 | `IntoHistory(...)` | SCD Type 2 historification | [Below](#historify) |
 
 ---

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "loom-kernel"
-version = "1.2.2"
+version = "1.4.0"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -278,7 +278,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "1.2.2"
+version = "1.4.0"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/src/loom/etl/backends/_merge.py

@@ -35,7 +35,7 @@ TARGET_ALIAS = "t"
 
 
 class _UpsertLike(Protocol):
-    """Structural protocol satisfied by both ``UpsertSpec`` and ``UpsertOp``.
+    """Structural protocol satisfied by the merge specs (``UpsertSpec``, ``UpdateSpec``).
 
     Declared as read-only properties so frozen dataclasses satisfy it.
     """
@@ -214,7 +214,7 @@ def _build_merge_plan(
 
 
 def _warn_no_partition_cols(table_ref: str) -> None:
-    """Emit a WARNING when no partition columns are declared on an UPSERT.
+    """Emit a WARNING when no partition columns are declared on a MERGE write.
 
     Without partition columns the MERGE predicate cannot prune Delta log files,
     forcing a full table scan.  For large tables this can be very expensive.
@@ -223,7 +223,7 @@ def _warn_no_partition_cols(table_ref: str) -> None:
         table_ref: Logical table reference string (for the log message).
     """
     _log.warning(
-        "upsert table=%s has no partition_cols — full table scan on MERGE. "
+        "merge table=%s has no partition_cols — full table scan on MERGE. "
         "Declare partition_cols= to enable Delta log file pruning.",
         table_ref,
     )
@@ -239,7 +239,7 @@ def _log_partition_combos(
         combos:    List of partition combination dicts collected from the frame.
         table_ref: Logical table reference string.
     """
-    _log.debug("upsert table=%s partition_combos=%d", table_ref, len(combos))
+    _log.debug("merge table=%s partition_combos=%d", table_ref, len(combos))
 
 
 def _build_partition_predicate(

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/src/loom/etl/backends/_write_policy.py

@@ -23,6 +23,7 @@ from loom.etl.declarative.target import (
     TargetSpec,
     TempFanInSpec,
     TempSpec,
+    UpdateSpec,
     UpsertSpec,
 )
 from loom.etl.declarative.target._history import HistorifyRepairReport, HistorifySpec
@@ -158,6 +159,7 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
             ReplacePartitionsSpec: self._dispatch_replace_partitions,
             ReplaceWhereSpec: self._dispatch_replace_where,
             UpsertSpec: self._dispatch_upsert,
+            UpdateSpec: self._dispatch_update,
             HistorifySpec: self._dispatch_historify,
         }
 
@@ -213,6 +215,16 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
     ) -> None:
         self._do_upsert(frame, target, cast(UpsertSpec, spec), streaming)
 
+    def _dispatch_update(
+        self,
+        frame: InputFrameT,
+        target: ResolvedTarget,
+        spec: TargetSpec,
+        _params_instance: Any,
+        streaming: bool,
+    ) -> None:
+        self._do_update(frame, target, cast(UpdateSpec, spec), streaming)
+
     def _dispatch_historify(
         self,
         frame: InputFrameT,
@@ -390,6 +402,36 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
             existing_schema=existing,
         )
 
+    def _do_update(
+        self,
+        frame: InputFrameT,
+        target: ResolvedTarget,
+        spec: UpdateSpec,
+        streaming: bool,
+    ) -> None:
+        """Update policy: require exists → align+write.
+
+        Unlike :meth:`_do_upsert` there is no creation path: an update-only
+        MERGE against a missing table has nothing to update, and creating the
+        table from the frame would insert every row — exactly what this mode
+        exists to prevent.
+        """
+        existing = self._physical_schema(target)
+        if existing is None:
+            raise SchemaNotFoundError(
+                f"Destination table does not exist: {target}. "
+                "update() never inserts, so it cannot create the table — "
+                "create it first with append/replace/upsert."
+            )
+        aligned = self._align(frame, existing, spec.schema_mode)
+        materialized = self._materialize_checked(aligned, target, streaming=False)
+        self._update(
+            materialized,
+            target,
+            spec=spec,
+            existing_schema=existing,
+        )
+
     def _do_historify(
         self,
         frame: InputFrameT,
@@ -590,6 +632,17 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
     ) -> None:
         """Upsert/merge into existing table."""
 
+    @abstractmethod
+    def _update(
+        self,
+        frame: WriteFrameT,
+        target: ResolvedTarget,
+        *,
+        spec: UpdateSpec,
+        existing_schema: PhysicalSchemaT,
+    ) -> None:
+        """Matched-only merge into existing table — never inserts."""
+
     @abstractmethod
     def _historify(
         self,

{loom_kernel-1.2.2 → loom_kernel-1.4.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.table import TableMerger
 
 from loom.core.logger import get_logger
 from loom.etl.backends._historify._transform import scd2_transform
@@ -16,6 +17,7 @@ from loom.etl.backends._merge import (
     _build_merge_plan,
     _build_partition_predicate,
     _log_partition_combos,
+    _MergePlan,
     _warn_no_partition_cols,
 )
 from loom.etl.backends._path_template import resolve_file_uri
@@ -33,6 +35,7 @@ from loom.etl.declarative.target._history import HistorifyRepairReport, Historif
 from loom.etl.declarative.target._table import (
     AppendSpec,
     ReplacePartitionsSpec,
+    UpdateSpec,
     UpsertSpec,
 )
 from loom.etl.lineage._records import LineageRecord, WriteContext, get_lineage_schema
@@ -490,9 +493,55 @@ class PolarsTargetWriter(_WritePolicy[pl.LazyFrame, pl.DataFrame, PolarsPhysical
         spec: UpsertSpec,
         existing_schema: PolarsPhysicalSchema,
     ) -> None:
-        """Merge frame into target using Delta MERGE."""
-        path_target = self._as_path_target(target)
+        """Merge frame into target using Delta MERGE (update + insert)."""
+        _ = existing_schema
+        merger, plan, location = self._matched_update_merger(frame, target, spec, mode="upsert")
+        merger.when_not_matched_insert(updates=plan.insert_values).execute()
+        _log_write_commit("upsert", location)
+
+    def _update(
+        self,
+        frame: pl.DataFrame,
+        target: ResolvedTarget,
+        *,
+        spec: UpdateSpec,
+        existing_schema: PolarsPhysicalSchema,
+    ) -> None:
+        """Merge frame into target using a matched-only Delta MERGE.
+
+        No ``when_not_matched_insert`` clause is emitted, so unmatched source
+        rows are ignored and the MERGE inserts zero rows by construction.
+        """
         _ = existing_schema
+        merger, _plan, location = self._matched_update_merger(frame, target, spec, mode="update")
+        merger.execute()
+        _log_write_commit("update", location)
+
+    def _matched_update_merger(
+        self,
+        frame: pl.DataFrame,
+        target: ResolvedTarget,
+        spec: UpsertSpec | UpdateSpec,
+        *,
+        mode: str,
+    ) -> tuple[TableMerger, _MergePlan, TableLocation]:
+        """Build the Delta MERGE up to the shared ``when_matched_update`` clause.
+
+        Both :meth:`_upsert` and :meth:`_update` start from the same merge:
+        partition-combo pre-filter, ON predicate, and the matched-update
+        column map.  The caller chains its remaining clauses and executes.
+
+        Args:
+            frame:  Materialised source frame.
+            target: Resolved path target.
+            spec:   Upsert or update spec (identical merge fields).
+            mode:   Write-mode label for logging.
+
+        Returns:
+            Tuple of the prepared merger, the merge plan, and the target
+            location (for commit logging).
+        """
+        path_target = self._as_path_target(target)
         location = path_target.location
 
         # Collect partition combinations for pre-filter
@@ -512,24 +561,19 @@ class PolarsTargetWriter(_WritePolicy[pl.LazyFrame, pl.DataFrame, PolarsPhysical
 
         dt = DeltaTable(location.uri, storage_options=location.storage_options or {})
         _log_write_start(
-            "upsert",
+            mode,
             location,
             frame,
             partition_cols=spec.partition_cols,
             predicate=merge_plan.predicate,
         )
-        (
-            dt.merge(
-                source=frame,
-                predicate=merge_plan.predicate,
-                source_alias=SOURCE_ALIAS,
-                target_alias=TARGET_ALIAS,
-            )
-            .when_matched_update(updates=merge_plan.update_set)
-            .when_not_matched_insert(updates=merge_plan.insert_values)
-            .execute()
-        )
-        _log_write_commit("upsert", location)
+        merger = dt.merge(
+            source=frame,
+            predicate=merge_plan.predicate,
+            source_alias=SOURCE_ALIAS,
+            target_alias=TARGET_ALIAS,
+        ).when_matched_update(updates=merge_plan.update_set)
+        return merger, merge_plan, location
 
     def _read_existing_data(
         self,

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/src/loom/etl/backends/spark/_writer.py

@@ -7,7 +7,7 @@ import logging
 from collections.abc import Callable, Sequence
 from typing import Any, cast
 
-from delta.tables import DeltaTable
+from delta.tables import DeltaMergeBuilder, DeltaTable
 from pyspark.errors.exceptions.base import AnalysisException
 from pyspark.sql import DataFrame, SparkSession
 from pyspark.sql import types as T
@@ -20,6 +20,7 @@ from loom.etl.backends._merge import (
     TARGET_ALIAS,
     _build_merge_plan,
     _log_partition_combos,
+    _MergePlan,
     _warn_no_partition_cols,
 )
 from loom.etl.backends._path_template import resolve_file_uri
@@ -37,7 +38,7 @@ from loom.etl.declarative._write_options import (
 from loom.etl.declarative.target import SchemaMode
 from loom.etl.declarative.target._file import FileSpec
 from loom.etl.declarative.target._history import HistorifyRepairReport, HistorifySpec
-from loom.etl.declarative.target._table import AppendSpec, UpsertSpec
+from loom.etl.declarative.target._table import AppendSpec, UpdateSpec, UpsertSpec
 from loom.etl.lineage._records import LineageRecord, get_lineage_schema
 from loom.etl.storage._config import MissingTablePolicy
 from loom.etl.storage._file_locator import FileLocator
@@ -250,7 +251,40 @@ class SparkTargetWriter(_WritePolicy[DataFrame, DataFrame, SparkPhysicalSchema])
     ) -> None:
         """Merge frame into target using Delta MERGE (delta-spark)."""
         _ = existing_schema
+        merger, plan = self._matched_update_merger(frame, target, spec)
+        merger.whenNotMatchedInsert(
+            values=cast(dict[str, str | Column], plan.insert_values)
+        ).execute()
 
+    def _update(
+        self,
+        frame: DataFrame,
+        target: ResolvedTarget,
+        *,
+        spec: UpdateSpec,
+        existing_schema: SparkPhysicalSchema,
+    ) -> None:
+        """Merge frame into target using a matched-only Delta MERGE.
+
+        No ``whenNotMatchedInsert`` clause is emitted, so unmatched source
+        rows are ignored and the MERGE inserts zero rows by construction.
+        """
+        _ = existing_schema
+        merger, _plan = self._matched_update_merger(frame, target, spec)
+        merger.execute()
+
+    def _matched_update_merger(
+        self,
+        frame: DataFrame,
+        target: ResolvedTarget,
+        spec: UpsertSpec | UpdateSpec,
+    ) -> tuple[DeltaMergeBuilder, _MergePlan]:
+        """Build the Delta MERGE up to the shared ``whenMatchedUpdate`` clause.
+
+        Both :meth:`_upsert` and :meth:`_update` start from the same merge:
+        partition-combo pre-filter, ON predicate, and the matched-update
+        column map.  The caller chains its remaining clauses and executes.
+        """
         if isinstance(target, CatalogTarget):
             dt = DeltaTable.forName(self._spark, target.catalog_ref.ref)
         else:
@@ -265,13 +299,12 @@ class SparkTargetWriter(_WritePolicy[DataFrame, DataFrame, SparkPhysicalSchema])
             source_alias=SOURCE_ALIAS,
         )
 
-        (
+        merger = (
             dt.alias(TARGET_ALIAS)
             .merge(frame.alias(SOURCE_ALIAS), merge_plan.predicate)
             .whenMatchedUpdate(set=cast(dict[str, str | Column], merge_plan.update_set))
-            .whenNotMatchedInsert(values=cast(dict[str, str | Column], merge_plan.insert_values))
-            .execute()
         )
+        return merger, merge_plan
 
     def _read_existing_data(
         self,

{loom_kernel-1.2.2 → loom_kernel-1.4.0}/src/loom/etl/compiler/_errors.py

@@ -28,6 +28,7 @@ class ETLErrorCode(StrEnum):
     UPSERT_NO_KEYS = "UPSERT_NO_KEYS"
     UPSERT_EXCLUDE_INCLUDE_CONFLICT = "UPSERT_EXCLUDE_INCLUDE_CONFLICT"
     UPSERT_KEY_IN_EXCLUDE = "UPSERT_KEY_IN_EXCLUDE"
+    UPDATE_EMPTY_UPDATE_SET = "UPDATE_EMPTY_UPDATE_SET"
     MISSING_GENERIC_PARAM = "MISSING_GENERIC_PARAM"
     MISSING_TARGET = "MISSING_TARGET"
     INVALID_TARGET_TYPE = "INVALID_TARGET_TYPE"
@@ -171,38 +172,56 @@ class ETLCompilationError(Exception):
         )
 
     @classmethod
-    def upsert_no_keys(cls, step: type) -> ETLCompilationError:
-        """upsert() declared with no key columns."""
+    def upsert_no_keys(cls, step: type, method: str = "upsert") -> ETLCompilationError:
+        """upsert()/update() declared with no key columns."""
         return cls(
             code=ETLErrorCode.UPSERT_NO_KEYS,
             component=step.__qualname__,
             message=(
-                f"{step.__qualname__}: upsert() requires at least one key column. "
+                f"{step.__qualname__}: {method}() requires at least one key column. "
                 'Pass keys=("col",) to identify rows uniquely.'
             ),
         )
 
     @classmethod
-    def upsert_exclude_include_conflict(cls, step: type) -> ETLCompilationError:
-        """upsert() has both exclude= and include= set."""
+    def upsert_exclude_include_conflict(
+        cls, step: type, method: str = "upsert"
+    ) -> ETLCompilationError:
+        """upsert()/update() has both exclude= and include= set."""
         return cls(
             code=ETLErrorCode.UPSERT_EXCLUDE_INCLUDE_CONFLICT,
             component=step.__qualname__,
             message=(
-                f"{step.__qualname__}: upsert() exclude= and include= are mutually exclusive. "
+                f"{step.__qualname__}: {method}() exclude= and include= are mutually exclusive. "
                 "Use one or the other, not both."
             ),
         )
 
     @classmethod
-    def upsert_key_in_exclude(cls, step: type, overlap: frozenset[str]) -> ETLCompilationError:
-        """upsert() exclude= contains columns that are also upsert keys."""
+    def upsert_key_in_exclude(
+        cls, step: type, overlap: frozenset[str], method: str = "upsert"
+    ) -> ETLCompilationError:
+        """upsert()/update() exclude= contains columns that are also merge keys."""
         return cls(
             code=ETLErrorCode.UPSERT_KEY_IN_EXCLUDE,
             component=step.__qualname__,
             message=(
-                f"{step.__qualname__}: upsert() exclude={sorted(overlap)} overlaps with "
-                "upsert keys — key columns are always excluded from UPDATE SET."
+                f"{step.__qualname__}: {method}() exclude={sorted(overlap)} overlaps with "
+                f"{method} keys — key columns are always excluded from UPDATE SET."
+            ),
+        )
+
+    @classmethod
+    def update_empty_update_set(cls, step: type, include: tuple[str, ...]) -> ETLCompilationError:
+        """update() include= is fully absorbed by keys and partition columns."""
+        return cls(
+            code=ETLErrorCode.UPDATE_EMPTY_UPDATE_SET,
+            component=step.__qualname__,
+            message=(
+                f"{step.__qualname__}: update() include={sorted(include)} is fully covered "
+                "by keys/partition_cols, which are always excluded from UPDATE SET — "
+                "the MERGE would update no columns and the write would be a guaranteed "
+                "no-op. List at least one non-key, non-partition column."
             ),
         )