contractforge-databricks 0.1.0__py3-none-any.whl

contractforge_databricks/execution/hash_diff_latest.py

@@ -0,0 +1,142 @@
+"""Target-latest selection helpers for SCD1 hash-diff writes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from contractforge_core.runtime import QueryOne
+from contractforge_core.semantic import SemanticContract
+from contractforge_databricks.sql import quote_identifier, quote_table_name
+
+
+@dataclass(frozen=True)
+class HashDiffLatestSelection:
+    order_by: str | None = None
+    reason: str = "none"
+
+
+def resolve_hash_diff_latest_selection(
+    contract: SemanticContract,
+    target_schema: dict[str, str] | None = None,
+) -> HashDiffLatestSelection:
+    explicit = _explicit_order_by(contract)
+    if explicit:
+        return HashDiffLatestSelection(explicit, "contract")
+    columns = set(target_schema or {})
+    if "ingestion_sequence" in columns:
+        return HashDiffLatestSelection("ingestion_sequence DESC NULLS LAST", "ingestion_sequence")
+    if "ingestion_ts_utc" in columns:
+        if "__run_id" in columns:
+            return HashDiffLatestSelection(
+                "ingestion_ts_utc DESC NULLS LAST, __run_id DESC NULLS LAST",
+                "ingestion_ts_utc",
+            )
+        return HashDiffLatestSelection("ingestion_ts_utc DESC NULLS LAST", "ingestion_ts_utc")
+    if "source_loaded_at_utc" in columns:
+        return HashDiffLatestSelection("source_loaded_at_utc DESC NULLS LAST", "source_loaded_at_utc")
+    return HashDiffLatestSelection()
+
+
+def validate_hash_diff_target_latest(
+    *,
+    query_one: QueryOne | None,
+    target_table: str,
+    merge_keys: tuple[str, ...],
+    selection: HashDiffLatestSelection,
+) -> None:
+    if query_one is None:
+        return
+    if selection.reason == "ingestion_ts_utc":
+        ambiguous = query_one(render_null_ingestion_ts_ambiguity_sql(target_table, merge_keys))
+        if _count(ambiguous):
+            raise ValueError(
+                "scd1_hash_diff found multiple target versions per key with null ingestion_ts_utc. "
+                "Provide transform.deduplicate.order_by for history migration or rewrite the target with "
+                "ingestion_ts_utc/ingestion_sequence."
+            )
+    if selection.order_by is None:
+        duplicate = query_one(render_hash_diff_duplicate_target_keys_sql(target_table, merge_keys))
+        if _count(duplicate):
+            raise ValueError(
+                "scd1_hash_diff found multiple target versions per key, but no deterministic ordering exists "
+                "to select the latest state. Provide transform.deduplicate.order_by or rewrite the target with "
+                "ingestion_ts_utc/ingestion_sequence."
+            )
+
+
+def render_null_ingestion_ts_ambiguity_sql(target_table: str, hash_keys: tuple[str, ...]) -> str:
+    keys = ", ".join(quote_identifier(key) for key in hash_keys)
+    return "\n".join(
+        [
+            "SELECT COUNT(*) AS ambiguous_key_count",
+            "FROM (",
+            f"  SELECT {keys}, COUNT(*) AS __cnt, MAX({quote_identifier('ingestion_ts_utc')}) AS __max_ingestion_ts_utc",
+            f"  FROM {quote_table_name(target_table)}",
+            f"  GROUP BY {keys}",
+            ") target_versions",
+            "WHERE __cnt > 1 AND __max_ingestion_ts_utc IS NULL",
+        ]
+    )
+
+
+def render_hash_diff_duplicate_target_keys_sql(target_table: str, hash_keys: tuple[str, ...]) -> str:
+    keys = ", ".join(quote_identifier(key) for key in hash_keys)
+    return "\n".join(
+        [
+            "SELECT COUNT(*) AS duplicate_key_count",
+            "FROM (",
+            f"  SELECT {keys}, COUNT(*) AS __cnt",
+            f"  FROM {quote_table_name(target_table)}",
+            f"  GROUP BY {keys}",
+            ") target_versions",
+            "WHERE __cnt > 1",
+        ]
+    )
+
+
+def _explicit_order_by(contract: SemanticContract) -> str | None:
+    deduplicate = contract.transform.raw.get("deduplicate") if contract.transform else None
+    if not isinstance(deduplicate, dict):
+        return None
+    merge_keys = contract.write.merge_keys or contract.write.hash_keys
+    keys = _as_tuple(deduplicate.get("keys"))
+    if keys and keys != merge_keys:
+        return None
+    return _render_order_by(deduplicate.get("order_by"))
+
+
+def _render_order_by(value: Any) -> str | None:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    if not isinstance(value, list):
+        return None
+    parts: list[str] = []
+    for item in value:
+        if not isinstance(item, dict) or not item.get("column"):
+            continue
+        clause = quote_identifier(str(item["column"]))
+        clause += f" {str(item.get('direction', 'desc')).upper()}"
+        if item.get("nulls"):
+            clause += f" NULLS {str(item['nulls']).upper()}"
+        parts.append(clause)
+    return ", ".join(parts) or None
+
+
+def _as_tuple(value: Any) -> tuple[str, ...]:
+    if isinstance(value, str):
+        return (value,)
+    if isinstance(value, (list, tuple)):
+        return tuple(str(item) for item in value)
+    return ()
+
+
+def _count(row: dict[str, Any] | None) -> int:
+    if not row:
+        return 0
+    for value in row.values():
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            continue
+    return 0

contractforge_databricks/execution/replace_partitions.py

@@ -0,0 +1,40 @@
+"""Databricks selective partition replacement helpers."""
+
+from __future__ import annotations
+
+from contractforge_core.execution import ExecutionOutcome
+from contractforge_core.semantic import SemanticContract
+from contractforge_databricks.execution.sql_merge import SqlRunner
+from contractforge_databricks.rendering.names import target_full_name
+from contractforge_databricks.sql import quote_table_name
+
+
+def render_replace_partitions_sql(*, target_table: str, source_view: str, predicate: str) -> str:
+    if not predicate:
+        raise ValueError("replace_partitions requires a non-empty partition predicate")
+    return (
+        f"INSERT INTO TABLE {quote_table_name(target_table)} BY NAME\n"
+        f"REPLACE WHERE {predicate}\n"
+        f"SELECT * FROM {quote_table_name(source_view)}"
+    )
+
+
+def execute_replace_partitions(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    source_view: str,
+    predicate: str | None,
+) -> ExecutionOutcome:
+    if contract.write.mode != "scd1_upsert":
+        raise ValueError(f"execute_replace_partitions only supports scd1_upsert, got {contract.write.mode}")
+    target = target_full_name(contract)
+    statement = render_replace_partitions_sql(target_table=target, source_view=source_view, predicate=predicate or "")
+    runner.sql(statement)
+    return ExecutionOutcome(
+        status="SUCCESS",
+        operation="delta_replace_partitions",
+        target=target,
+        metrics={"replace_predicate": predicate},
+        sql=statement,
+    )

contractforge_databricks/execution/results.py

@@ -0,0 +1,5 @@
+"""Compatibility exports for platform-neutral execution result models."""
+
+from contractforge_core.execution import ExecutionOutcome, ExecutionStatus
+
+__all__ = ["ExecutionOutcome", "ExecutionStatus"]

contractforge_databricks/execution/retry.py

@@ -0,0 +1,36 @@
+"""Retry helpers for Databricks Delta concurrency operations."""
+
+from __future__ import annotations
+
+import random
+import time
+from collections.abc import Callable
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def is_retryable_delta_concurrency_error(exc: Exception) -> bool:
+    text = str(exc).upper()
+    return any(token in text for token in ("CONCURRENT", "CONFLICT", "RETRY", "DELTA_CONCURRENT"))
+
+
+def with_delta_retry(
+    fn: Callable[[], T],
+    *,
+    attempts: int = 3,
+    backoff_seconds: float = 1.0,
+    jitter: Callable[[], float] | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> T:
+    last_exc: Exception | None = None
+    jitter_fn = jitter or random.random
+    for attempt in range(1, attempts + 1):
+        try:
+            return fn()
+        except Exception as exc:
+            last_exc = exc
+            if not is_retryable_delta_concurrency_error(exc) or attempt == attempts:
+                raise
+            sleep(backoff_seconds * attempt + jitter_fn())
+    raise last_exc  # type: ignore[misc]

contractforge_databricks/execution/scd2.py

@@ -0,0 +1,213 @@
+"""ContractForge-compatible SCD2 Delta MERGE SQL."""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from contractforge_core.semantic import SemanticContract
+from contractforge_core.execution import ExecutionOutcome
+from contractforge_databricks.execution.scd2_deletes import render_scd2_delete_merge_sql
+from contractforge_databricks.execution.scd2_late import (
+    joined_sequence_select,
+    late_arriving_condition,
+    late_arriving_filter,
+    reject_guard_join,
+    target_sequence_select,
+)
+from contractforge_databricks.execution.sql_merge import SqlRunner
+from contractforge_databricks.rendering.names import target_full_name
+from contractforge_databricks.sql import quote_identifier, quote_table_name
+
+
+def render_scd2_merge_sql(
+    *,
+    target_table: str,
+    source_view: str,
+    merge_keys: tuple[str, ...],
+    insert_columns: tuple[str, ...],
+) -> str:
+    """Render SCD2 MERGE over a prepared staging view.
+
+    The staging view must already contain ContractForge-managed SCD2 columns:
+    `valid_from`, `valid_to`, `is_current`, `row_hash`, and `changed_columns`.
+    """
+    if not merge_keys:
+        raise ValueError("scd2_historical requires merge_keys")
+    _require_columns(insert_columns, tuple(f"__merge_key_{key}" for key in merge_keys), "merge key staging columns")
+    _require_columns(insert_columns, ("valid_from", "valid_to", "is_current", "row_hash", "changed_columns"))
+
+    target_insert_columns = _target_insert_columns(insert_columns, merge_keys)
+    key_condition = " AND ".join(
+        f"t.{quote_identifier(key)} <=> s.{quote_identifier('__merge_key_' + key)}" for key in merge_keys
+    )
+    insert_cols = ", ".join(quote_identifier(column) for column in target_insert_columns)
+    insert_vals = ", ".join(f"s.{quote_identifier(column)}" for column in target_insert_columns)
+    changed_expr = _changed_columns_expr(target_insert_columns, merge_keys)
+
+    return "\n".join(
+        [
+            f"MERGE INTO {quote_table_name(target_table)} t",
+            f"USING {quote_table_name(source_view)} s",
+            f"ON {key_condition} AND t.`is_current` = true",
+            "WHEN MATCHED AND t.`row_hash` <> s.`row_hash` THEN UPDATE SET",
+            "  t.`valid_to` = current_timestamp(),",
+            "  t.`is_current` = false,",
+            f"  t.`changed_columns` = {changed_expr}",
+            f"WHEN NOT MATCHED THEN INSERT ({insert_cols}) VALUES ({insert_vals})",
+        ]
+    )
+
+
+def execute_scd2_merge(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    source_view: str,
+    insert_columns: tuple[str, ...],
+) -> ExecutionOutcome:
+    if contract.write.mode != "scd2_historical":
+        raise ValueError(f"execute_scd2_merge only supports scd2_historical, got {contract.write.mode}")
+    target = target_full_name(contract)
+    stage_view = f"__cf_scd2_stage_{uuid4().hex}"
+    stage_statement = render_scd2_stage_sql(
+        target_table=target,
+        source_view=source_view,
+        stage_view=stage_view,
+        merge_keys=contract.write.merge_keys,
+        source_columns=insert_columns,
+        sequence_by=contract.write.scd2_sequence_by,
+        late_arriving_policy=contract.write.scd2_late_arriving_policy,
+        apply_as_deletes=contract.write.scd2_apply_as_deletes,
+    )
+    statement = render_scd2_merge_sql(
+        target_table=target,
+        source_view=stage_view,
+        merge_keys=contract.write.merge_keys,
+        insert_columns=insert_columns,
+    )
+    if contract.write.scd2_apply_as_deletes:
+        runner.sql(
+            render_scd2_delete_merge_sql(
+                target_table=target,
+                source_view=source_view,
+                merge_keys=contract.write.merge_keys,
+                apply_as_deletes=contract.write.scd2_apply_as_deletes,
+                sequence_by=contract.write.scd2_sequence_by,
+                late_arriving_policy=contract.write.scd2_late_arriving_policy,
+            )
+        )
+    runner.sql(stage_statement)
+    try:
+        runner.sql(statement)
+    finally:
+        runner.sql(f"DROP VIEW IF EXISTS {quote_table_name(stage_view)}")
+    return ExecutionOutcome(
+        status="SUCCESS",
+        operation="core_managed_scd2_delta_merge",
+        target=target,
+        metrics={
+            "insert_columns": len(_target_insert_columns(insert_columns, contract.write.merge_keys)),
+            "merge_keys": len(contract.write.merge_keys),
+            "stage_view": stage_view,
+        },
+        sql=statement,
+    )
+
+
+def render_scd2_stage_sql(
+    *,
+    target_table: str,
+    source_view: str,
+    stage_view: str,
+    merge_keys: tuple[str, ...],
+    source_columns: tuple[str, ...],
+    sequence_by: str | None = None,
+    late_arriving_policy: str = "apply",
+    apply_as_deletes: str | None = None,
+) -> str:
+    if not merge_keys:
+        raise ValueError("scd2_historical requires merge_keys")
+    _require_columns(source_columns, ("valid_from", "valid_to", "is_current", "row_hash", "changed_columns"))
+    data_columns = _target_insert_columns(source_columns, merge_keys)
+    if sequence_by and sequence_by not in data_columns:
+        raise ValueError(f"prepared SCD2 source is missing scd2_sequence_by: {sequence_by}")
+    key_join = " AND ".join(f"t.{quote_identifier(key)} <=> s.{quote_identifier(key)}" for key in merge_keys)
+    target_keys = ", ".join(quote_identifier(key) for key in merge_keys)
+    select_data = ", ".join(f"s.{quote_identifier(column)}" for column in data_columns)
+    null_merge_keys = ", ".join(f"NULL AS {quote_identifier('__merge_key_' + key)}" for key in merge_keys)
+    update_merge_keys = ", ".join(f"{quote_identifier(key)} AS {quote_identifier('__merge_key_' + key)}" for key in merge_keys)
+    stage_columns = ", ".join(quote_identifier(column) for column in (*data_columns, *(f"__merge_key_{key}" for key in merge_keys)))
+
+    lines = [
+        f"CREATE OR REPLACE TEMP VIEW {quote_table_name(stage_view)} AS",
+        "WITH target_current AS (",
+        f"  SELECT {target_keys}, `row_hash` AS `__tgt_row_hash`{target_sequence_select(sequence_by)}",
+        f"  FROM {quote_table_name(target_table)}",
+        "  WHERE `is_current` = true",
+        "), joined AS (",
+        f"  SELECT {select_data}, t.`__tgt_row_hash`{joined_sequence_select(sequence_by)}",
+        f"  FROM {quote_table_name(source_view)} s",
+        f"  LEFT JOIN target_current t ON {key_join}",
+        f"  WHERE {_non_delete_filter(apply_as_deletes)}",
+        ")",
+    ]
+    if late_arriving_policy == "reject" and sequence_by:
+        lines.extend(
+            [
+                ", late_arriving AS (",
+                "  SELECT count(*) AS late_count FROM joined",
+                f"  WHERE {late_arriving_condition(sequence_by)}",
+                "), reject_late_arriving AS (",
+                "  SELECT CASE WHEN late_count > 0 THEN 1 / 0 ELSE 0 END AS __late_guard FROM late_arriving",
+                ")",
+            ]
+        )
+    lines.extend(
+        [
+            ", changed AS (",
+            f"  SELECT * FROM joined{reject_guard_join(sequence_by, late_arriving_policy)}",
+            f"  WHERE {late_arriving_filter(sequence_by, late_arriving_policy)}",
+            "    AND (`__tgt_row_hash` IS NULL OR NOT (`row_hash` <=> `__tgt_row_hash`))",
+            "), insert_stage AS (",
+            f"  SELECT {', '.join(quote_identifier(column) for column in data_columns)}, {null_merge_keys}",
+            "  FROM changed",
+            "), update_stage AS (",
+            f"  SELECT {', '.join(quote_identifier(column) for column in data_columns)}, {update_merge_keys}",
+            "  FROM changed WHERE `__tgt_row_hash` IS NOT NULL",
+            ")",
+            f"SELECT {stage_columns} FROM insert_stage",
+            "UNION ALL",
+            f"SELECT {stage_columns} FROM update_stage",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _require_columns(columns: tuple[str, ...], required: tuple[str, ...], context: str = "required columns") -> None:
+    missing = [column for column in required if column not in columns]
+    if missing:
+        raise ValueError(f"prepared SCD2 source is missing {context}: {missing}")
+
+
+def _target_insert_columns(columns: tuple[str, ...], merge_keys: tuple[str, ...]) -> tuple[str, ...]:
+    staging_columns = {f"__merge_key_{key}" for key in merge_keys}
+    return tuple(column for column in columns if column not in staging_columns)
+
+
+def _changed_columns_expr(columns: tuple[str, ...], merge_keys: tuple[str, ...]) -> str:
+    excluded = {*merge_keys, "valid_from", "valid_to", "is_current", "row_hash", "changed_columns"}
+    candidates = tuple(column for column in columns if column not in excluded)
+    if not candidates:
+        return "s.`changed_columns`"
+    parts = ", ".join(
+        f"CASE WHEN NOT (t.{quote_identifier(column)} <=> s.{quote_identifier(column)}) "
+        f"THEN '{column}' ELSE NULL END"
+        for column in candidates
+    )
+    return f"concat_ws(',', {parts})"
+
+
+def _non_delete_filter(apply_as_deletes: str | None) -> str:
+    if not apply_as_deletes:
+        return "true"
+    return f"NOT coalesce(CAST(({apply_as_deletes}) AS BOOLEAN), false)"

contractforge_databricks/execution/scd2_deletes.py

@@ -0,0 +1,65 @@
+"""Databricks SCD2 delete-expression merge helpers."""
+
+from __future__ import annotations
+
+from contractforge_databricks.execution.scd2_late import late_arriving_condition, late_arriving_filter
+from contractforge_databricks.sql import quote_identifier, quote_table_name
+
+
+def render_scd2_delete_merge_sql(
+    *,
+    target_table: str,
+    source_view: str,
+    merge_keys: tuple[str, ...],
+    apply_as_deletes: str,
+    sequence_by: str | None = None,
+    late_arriving_policy: str = "apply",
+) -> str:
+    if not merge_keys:
+        raise ValueError("SCD2 delete handling requires merge_keys")
+    if not apply_as_deletes or not apply_as_deletes.strip():
+        raise ValueError("SCD2 delete handling requires scd2_apply_as_deletes")
+    key_list = ", ".join(quote_identifier(key) for key in merge_keys)
+    key_join = " AND ".join(f"t.{quote_identifier(key)} <=> d.{quote_identifier(key)}" for key in merge_keys)
+    joined_key_join = " AND ".join(f"t.{quote_identifier(key)} <=> d.{quote_identifier(key)}" for key in merge_keys)
+    source_sequence = f", {quote_identifier(sequence_by)}" if sequence_by else ""
+    target_sequence = f", {quote_identifier(sequence_by)} AS `__tgt_sequence`" if sequence_by else ""
+    joined_sequence = ", t.`__tgt_sequence`" if sequence_by else ""
+    reject_cte = _reject_cte(sequence_by, late_arriving_policy)
+    reject_join = " CROSS JOIN reject_late_arriving" if sequence_by and late_arriving_policy == "reject" else ""
+    return "\n".join(
+        [
+            f"MERGE INTO {quote_table_name(target_table)} t",
+            "USING (",
+            "  WITH delete_candidates AS (",
+            f"    SELECT DISTINCT {key_list}{source_sequence}",
+            f"    FROM {quote_table_name(source_view)}",
+            f"    WHERE coalesce(CAST(({apply_as_deletes}) AS BOOLEAN), false)",
+            "  ), target_current AS (",
+            f"    SELECT {key_list}{target_sequence}",
+            f"    FROM {quote_table_name(target_table)}",
+            "    WHERE `is_current` = true",
+            "  ), joined AS (",
+            f"    SELECT d.*{joined_sequence} FROM delete_candidates d",
+            f"    LEFT JOIN target_current t ON {joined_key_join}",
+            f"  ){reject_cte}",
+            f"  SELECT {key_list} FROM joined{reject_join}",
+            f"  WHERE {late_arriving_filter(sequence_by, late_arriving_policy)}",
+            ") d",
+            f"ON {key_join} AND t.`is_current` = true",
+            "WHEN MATCHED THEN UPDATE SET",
+            "  t.`valid_to` = current_timestamp(),",
+            "  t.`is_current` = false,",
+            "  t.`changed_columns` = 'DELETE'",
+        ]
+    )
+
+
+def _reject_cte(sequence_by: str | None, policy: str) -> str:
+    if not sequence_by or policy != "reject":
+        return ""
+    return (
+        "\n  , late_arriving AS (\n    SELECT count(*) AS late_count FROM joined\n    WHERE "
+        + late_arriving_condition(sequence_by)
+        + "\n  ), reject_late_arriving AS (\n    SELECT CASE WHEN late_count > 0 THEN 1 / 0 ELSE 0 END AS __late_guard FROM late_arriving\n  )"
+    )

contractforge_databricks/execution/scd2_late.py

@@ -0,0 +1,30 @@
+"""Databricks SQL fragments for SCD2 late-arriving policies."""
+
+from __future__ import annotations
+
+from contractforge_databricks.sql import quote_identifier
+
+
+def target_sequence_select(sequence_by: str | None) -> str:
+    return f", {quote_identifier(sequence_by)} AS `__tgt_sequence`" if sequence_by else ""
+
+
+def joined_sequence_select(sequence_by: str | None) -> str:
+    return ", t.`__tgt_sequence`" if sequence_by else ""
+
+
+def reject_guard_join(sequence_by: str | None, policy: str) -> str:
+    return " CROSS JOIN reject_late_arriving" if sequence_by and policy == "reject" else ""
+
+
+def late_arriving_condition(sequence_by: str) -> str:
+    column = quote_identifier(sequence_by)
+    return f"`__tgt_sequence` IS NOT NULL AND ({column} IS NULL OR {column} <= `__tgt_sequence`)"
+
+
+def late_arriving_filter(sequence_by: str | None, policy: str) -> str:
+    if not sequence_by or policy == "apply":
+        return "true"
+    if policy not in {"ignore", "reject"}:
+        raise ValueError("scd2_late_arriving_policy must be one of apply, ignore, reject")
+    return f"NOT ({late_arriving_condition(sequence_by)})"

contractforge_databricks/execution/snapshot.py

@@ -0,0 +1,77 @@
+"""ContractForge-compatible snapshot soft delete Delta MERGE SQL."""
+
+from __future__ import annotations
+
+from contractforge_core.semantic import SemanticContract
+from contractforge_core.execution import ExecutionOutcome
+from contractforge_databricks.execution.sql_merge import SqlRunner
+from contractforge_databricks.rendering.names import target_full_name
+from contractforge_databricks.sql import quote_identifier, quote_table_name
+
+
+def render_snapshot_soft_delete_sql(
+    *,
+    target_table: str,
+    source_view: str,
+    merge_keys: tuple[str, ...],
+    source_columns: tuple[str, ...],
+) -> str:
+    if not merge_keys:
+        raise ValueError("snapshot_soft_delete requires merge_keys")
+    _require_columns(source_columns, merge_keys, "merge_keys")
+    _require_columns(source_columns, ("is_active", "deleted_at", "row_hash"))
+
+    key_condition = " AND ".join(
+        f"t.{quote_identifier(key)} <=> s.{quote_identifier(key)}" for key in merge_keys
+    )
+    update_columns = tuple(column for column in source_columns if column not in merge_keys)
+    update_set = ", ".join(
+        f"t.{quote_identifier(column)} = s.{quote_identifier(column)}" for column in update_columns
+    )
+    insert_columns = ", ".join(quote_identifier(column) for column in source_columns)
+    insert_values = ", ".join(f"s.{quote_identifier(column)}" for column in source_columns)
+
+    return "\n".join(
+        [
+            f"MERGE INTO {quote_table_name(target_table)} t",
+            f"USING {quote_table_name(source_view)} s",
+            f"ON {key_condition}",
+            f"WHEN MATCHED AND (NOT (t.`row_hash` <=> s.`row_hash`) OR t.`is_active` = false) THEN UPDATE SET {update_set}",
+            f"WHEN NOT MATCHED THEN INSERT ({insert_columns}) VALUES ({insert_values})",
+            "WHEN NOT MATCHED BY SOURCE AND t.`is_active` = true THEN UPDATE SET",
+            "  t.`is_active` = false,",
+            "  t.`deleted_at` = current_timestamp()",
+        ]
+    )
+
+
+def execute_snapshot_soft_delete(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    source_view: str,
+    source_columns: tuple[str, ...],
+) -> ExecutionOutcome:
+    if contract.write.mode != "snapshot_soft_delete":
+        raise ValueError(f"execute_snapshot_soft_delete only supports snapshot_soft_delete, got {contract.write.mode}")
+    target = target_full_name(contract)
+    statement = render_snapshot_soft_delete_sql(
+        target_table=target,
+        source_view=source_view,
+        merge_keys=contract.write.merge_keys,
+        source_columns=source_columns,
+    )
+    runner.sql(statement)
+    return ExecutionOutcome(
+        status="SUCCESS",
+        operation="core_managed_snapshot_soft_delete_delta_merge",
+        target=target,
+        metrics={"source_columns": len(source_columns), "merge_keys": len(contract.write.merge_keys)},
+        sql=statement,
+    )
+
+
+def _require_columns(columns: tuple[str, ...], required: tuple[str, ...], context: str = "required columns") -> None:
+    missing = [column for column in required if column not in columns]
+    if missing:
+        raise ValueError(f"prepared snapshot source is missing {context}: {missing}")