contractforge-databricks 0.1.0__py3-none-any.whl

contractforge_databricks/presets/modifiers.py

@@ -0,0 +1,51 @@
+"""Databricks modifier presets ported from ContractForge."""
+
+from __future__ import annotations
+
+from contractforge_databricks.presets.base import PRESET_META_KEY, Preset, meta
+
+DELTA_PRESETS: dict[str, Preset] = {
+    "delta_cdf_enabled": {
+        PRESET_META_KEY: meta("delta_cdf_enabled", "delta", "modifier", "Enable Delta Change Data Feed."),
+        "extensions": {"databricks": {"delta_properties": {"delta.enableChangeDataFeed": "true"}}},
+    },
+    "delta_optimized_writes": {
+        PRESET_META_KEY: meta("delta_optimized_writes", "delta", "modifier", "Optimized Delta write properties."),
+        "extensions": {
+            "databricks": {
+                "delta_properties": {
+                    "delta.autoOptimize.optimizeWrite": "true",
+                    "delta.autoOptimize.autoCompact": "true",
+                }
+            }
+        },
+    },
+    "delta_liquid_clustering": {
+        PRESET_META_KEY: meta(
+            "delta_liquid_clustering",
+            "delta",
+            "modifier",
+            "Databricks Delta liquid clustering.",
+            ["extensions.databricks.cluster_columns"],
+        )
+    },
+}
+
+QUALITY_PRESETS: dict[str, Preset] = {
+    "quality_strict": {
+        PRESET_META_KEY: meta("quality_strict", "quality", "modifier", "Abortive quality policy."),
+        "on_quality_fail": "fail",
+    },
+    "quality_quarantine": {
+        PRESET_META_KEY: meta("quality_quarantine", "quality", "modifier", "Quality quarantine policy."),
+        "on_quality_fail": "quarantine",
+    },
+}
+
+GOVERNANCE_PRESETS: dict[str, Preset] = {
+    "governance_uc_basic": {
+        PRESET_META_KEY: meta("governance_uc_basic", "governance", "modifier", "Basic Unity Catalog governance."),
+        "annotations": {"policy": "warn"},
+        "access": {"access_policy": {"mode": "validate_only", "on_drift": "warn"}},
+    }
+}

contractforge_databricks/presets/runtime.py

@@ -0,0 +1,22 @@
+"""Databricks runtime presets ported from ContractForge."""
+
+from __future__ import annotations
+
+from contractforge_databricks.presets.base import PRESET_META_KEY, Preset, meta
+
+RUNTIME_PRESETS: dict[str, Preset] = {
+    "runtime_databricks_serverless": {
+        PRESET_META_KEY: meta("runtime_databricks_serverless", "runtime", "runtime", "Databricks Serverless defaults."),
+        "extensions": {"databricks": {"cache_source": False, "optimize_after_write": False}},
+    },
+    "runtime_spark_delta_local": {
+        PRESET_META_KEY: meta("runtime_spark_delta_local", "runtime", "runtime", "Local PySpark + Delta defaults."),
+        "extensions": {
+            "databricks": {
+                "cache_source": False,
+                "optimize_after_write": False,
+                "lock_enabled": False,
+            }
+        },
+    },
+}

contractforge_databricks/presets/silver.py

@@ -0,0 +1,101 @@
+"""Silver Databricks presets ported from ContractForge."""
+
+from __future__ import annotations
+
+from contractforge_databricks.presets.base import PRESET_META_KEY, Preset, meta
+
+SILVER_PRESETS: dict[str, Preset] = {
+    "silver_scd1_upsert": {
+        PRESET_META_KEY: meta("silver_scd1_upsert", "silver", "ingestion", "Silver SCD1 Delta MERGE.", ["merge_keys"]),
+        "layer": "silver",
+        "mode": "scd1_upsert",
+        "extensions": {"databricks": {"merge_strategy": "delta"}},
+        "schema_policy": "additive_only",
+        "on_quality_fail": "fail",
+    },
+    "silver_scd1_partition_upsert": {
+        PRESET_META_KEY: meta(
+            "silver_scd1_partition_upsert",
+            "silver",
+            "ingestion",
+            "Silver SCD1 MERGE pruned by partition.",
+            ["merge_keys", "extensions.databricks.merge_partition_column"],
+        ),
+        "layer": "silver",
+        "mode": "scd1_upsert",
+        "extensions": {"databricks": {"merge_strategy": "delta_by_partition"}},
+        "schema_policy": "additive_only",
+        "on_quality_fail": "fail",
+    },
+    "silver_replace_partitions": {
+        PRESET_META_KEY: meta(
+            "silver_replace_partitions",
+            "silver",
+            "ingestion",
+            "Silver replacement of complete partitions.",
+            ["extensions.databricks.merge_partition_column"],
+        ),
+        "layer": "silver",
+        "mode": "scd1_upsert",
+        "extensions": {
+            "databricks": {
+                "merge_strategy": "replace_partitions",
+                "replace_partitions_source_complete": True,
+            }
+        },
+        "schema_policy": "additive_only",
+        "on_quality_fail": "fail",
+    },
+    "silver_incremental_watermark_upsert": {
+        PRESET_META_KEY: meta(
+            "silver_incremental_watermark_upsert",
+            "silver",
+            "ingestion",
+            "Silver SCD1 incremental watermark upsert.",
+            ["merge_keys", "watermark_columns"],
+        ),
+        "layer": "silver",
+        "mode": "scd1_upsert",
+        "extensions": {"databricks": {"merge_strategy": "delta"}},
+        "schema_policy": "additive_only",
+        "on_quality_fail": "fail",
+    },
+    "silver_hash_diff_append": {
+        PRESET_META_KEY: meta("silver_hash_diff_append", "silver", "ingestion", "Silver hash-diff append.", ["hash_keys"]),
+        "layer": "silver",
+        "mode": "scd1_hash_diff",
+        "schema_policy": "additive_only",
+        "on_quality_fail": "fail",
+        "hash_exclude_columns": ["ingestion_ts_utc", "__run_id"],
+    },
+    "silver_quarantine_ingestion": {
+        PRESET_META_KEY: meta(
+            "silver_quarantine_ingestion",
+            "silver",
+            "ingestion",
+            "Silver SCD1 with quarantine for row-level rules.",
+            ["merge_keys"],
+        ),
+        "layer": "silver",
+        "mode": "scd1_upsert",
+        "extensions": {"databricks": {"merge_strategy": "delta"}},
+        "schema_policy": "additive_only",
+        "on_quality_fail": "quarantine",
+    },
+    "silver_snapshot_soft_delete": {
+        PRESET_META_KEY: meta(
+            "silver_snapshot_soft_delete", "silver", "ingestion", "Silver snapshot soft delete.", ["merge_keys"]
+        ),
+        "layer": "silver",
+        "mode": "snapshot_soft_delete",
+        "schema_policy": "additive_only",
+        "on_quality_fail": "fail",
+    },
+    "silver_scd2_historical": {
+        PRESET_META_KEY: meta("silver_scd2_historical", "silver", "ingestion", "Silver SCD2 history.", ["merge_keys"]),
+        "layer": "silver",
+        "mode": "scd2_historical",
+        "schema_policy": "additive_only",
+        "on_quality_fail": "fail",
+    },
+}

contractforge_databricks/presets/write_engine.py

@@ -0,0 +1,57 @@
+"""Databricks write-engine preview presets ported from ContractForge."""
+
+from __future__ import annotations
+
+from contractforge_databricks.presets.base import PRESET_META_KEY, Preset, meta
+
+WRITE_ENGINE_PRESETS: dict[str, Preset] = {
+    "write_engine_native_auto_preview": {
+        PRESET_META_KEY: meta(
+            "write_engine_native_auto_preview",
+            "write_engine",
+            "modifier",
+            "Record Databricks native engine selection evidence without changing execution.",
+        ),
+        "extensions": {
+            "databricks": {
+                "write_engine": {"requested": "auto", "fallback_policy": "preview_only", "explain_selection": True}
+            }
+        },
+    },
+    "write_engine_databricks_sql_merge_preview": {
+        PRESET_META_KEY: meta(
+            "write_engine_databricks_sql_merge_preview",
+            "write_engine",
+            "modifier",
+            "Preview Databricks SQL MERGE eligibility while executing the Delta baseline.",
+            ["merge_keys"],
+        ),
+        "extensions": {
+            "databricks": {
+                "write_engine": {
+                    "requested": "databricks_sql_merge",
+                    "fallback_policy": "preview_only",
+                    "explain_selection": True,
+                }
+            }
+        },
+    },
+    "write_engine_lakeflow_auto_cdc_preview": {
+        PRESET_META_KEY: meta(
+            "write_engine_lakeflow_auto_cdc_preview",
+            "write_engine",
+            "modifier",
+            "Preview Lakeflow AUTO CDC eligibility while executing the Delta baseline.",
+            ["merge_keys"],
+        ),
+        "extensions": {
+            "databricks": {
+                "write_engine": {
+                    "requested": "lakeflow_auto_cdc",
+                    "fallback_policy": "preview_only",
+                    "explain_selection": True,
+                }
+            }
+        },
+    },
+}

contractforge_databricks/quality/__init__.py

@@ -0,0 +1,41 @@
+from contractforge_databricks.quality.persistence import (
+    render_quality_result_insert_sql,
+    render_quality_results_insert_sql,
+    render_quarantine_reference_insert_sql,
+)
+from contractforge_databricks.quality.evaluation import evaluate_quality
+from contractforge_databricks.quality.registry import (
+    clear_quality_rule_registry,
+    evaluate_custom_quality_rules,
+    evaluate_custom_quality_runtime,
+    get_quality_rule,
+    is_abort_only_failure,
+    list_quality_rules,
+    register_quality_rule,
+    unregister_quality_rule,
+)
+from contractforge_core.quality import (
+    QualityRuleResult,
+    quality_status,
+    quarantinable_results,
+)
+from contractforge_databricks.quality.sql import render_quality_check_sql
+
+__all__ = [
+    "QualityRuleResult",
+    "clear_quality_rule_registry",
+    "evaluate_quality",
+    "evaluate_custom_quality_rules",
+    "evaluate_custom_quality_runtime",
+    "get_quality_rule",
+    "is_abort_only_failure",
+    "list_quality_rules",
+    "quality_status",
+    "quarantinable_results",
+    "register_quality_rule",
+    "render_quality_check_sql",
+    "render_quality_result_insert_sql",
+    "render_quality_results_insert_sql",
+    "render_quarantine_reference_insert_sql",
+    "unregister_quality_rule",
+]

contractforge_databricks/quality/evaluation.py

@@ -0,0 +1,178 @@
+"""Databricks runtime evaluation for portable quality intents."""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+from contractforge_core.config import MAX_INLINE_ACCEPTED_VALUES
+from contractforge_core.quality import QualityRuleResult, quality_status
+from contractforge_core.semantic import QualityIntent, SemanticContract
+from contractforge_databricks.quality.registry import evaluate_custom_quality_runtime
+
+
+def evaluate_quality(
+    df: Any,
+    contract_or_quality: SemanticContract | tuple[QualityIntent, ...],
+) -> tuple[str, tuple[QualityRuleResult, ...], Any, Any, int]:
+    quality = contract_or_quality.quality if isinstance(contract_or_quality, SemanticContract) else contract_or_quality
+    custom_rules = _custom_quality_rules(contract_or_quality)
+    if not quality and not custom_rules:
+        return "NOT_CONFIGURED", (), df, df.limit(0), 0
+    functions = _functions()
+    results: list[QualityRuleResult] = []
+    quarantine_condition = functions.lit(False)
+    has_quarantine_condition = False
+    row_count: int | None = None
+
+    for intent in quality:
+        if intent.rule != "required_columns":
+            _validate_columns(df, intent.columns, f"quality.{intent.rule}")
+        if intent.rule == "required_columns":
+            result = _required_columns(df, intent)
+        elif intent.rule == "not_null":
+            result = _not_null(df, intent, functions)
+            if result.failed_count:
+                quarantine_condition = quarantine_condition | functions.col(intent.columns[0]).isNull()
+                has_quarantine_condition = True
+        elif intent.rule == "accepted_values":
+            result = _accepted_values(df, intent, functions)
+            if result.failed_count:
+                column = functions.col(intent.columns[0])
+                values = _values(intent.value)
+                quarantine_condition = quarantine_condition | ((~column.isin(values)) & column.isNotNull())
+                has_quarantine_condition = True
+        elif intent.rule == "max_null_ratio":
+            row_count = _row_count(df) if row_count is None else row_count
+            result = _max_null_ratio(df, intent, functions, row_count)
+            if result.failed_count:
+                quarantine_condition = quarantine_condition | functions.col(intent.columns[0]).isNull()
+                has_quarantine_condition = True
+        elif intent.rule == "unique_key":
+            result = _unique_key(df, intent, functions)
+        elif intent.rule == "row_count_minimum":
+            row_count = _row_count(df) if row_count is None else row_count
+            result = _row_count_minimum(intent, row_count)
+        elif intent.rule == "expression":
+            result, condition = _expression(df, intent, functions)
+            if result.failed_count and result.severity == "quarantine":
+                quarantine_condition = quarantine_condition | condition
+                has_quarantine_condition = True
+        else:
+            result = QualityRuleResult(intent.name, "FAILED", 1, "abort", f"Unsupported quality rule: {intent.rule}")
+        results.append(result)
+
+    custom_results, custom_quarantine_condition = evaluate_custom_quality_runtime(df, custom_rules)
+    results.extend(custom_results)
+    if custom_quarantine_condition is not None:
+        quarantine_condition = (
+            quarantine_condition | custom_quarantine_condition
+            if has_quarantine_condition
+            else custom_quarantine_condition
+        )
+        has_quarantine_condition = True
+
+    failed = tuple(result for result in results if result.failed_count > 0)
+    quarantined_df = df.where(quarantine_condition) if failed and has_quarantine_condition else df.limit(0)
+    quarantined_count = int(quarantined_df.count()) if failed and has_quarantine_condition else 0
+    valid_df = df.where(~quarantine_condition) if quarantined_count > 0 else df
+    return quality_status(tuple(results)), tuple(results), valid_df, quarantined_df, quarantined_count
+
+
+def _required_columns(df: Any, intent: QualityIntent) -> QualityRuleResult:
+    missing = [column for column in intent.columns if column not in (getattr(df, "columns", ()) or ())]
+    return QualityRuleResult(
+        intent.name,
+        "FAILED" if missing else "PASSED",
+        len(missing),
+        "abort",
+        "Required columns are missing." if missing else None,
+        {"missing": missing},
+    )
+
+
+def _not_null(df: Any, intent: QualityIntent, functions: Any) -> QualityRuleResult:
+    column = intent.columns[0]
+    count = _agg_int(df, functions.sum(functions.col(column).isNull().cast("long")).alias("failed_rows"), "failed_rows")
+    return QualityRuleResult(intent.name, "FAILED" if count else "PASSED", count, _severity(intent), intent.message, {"column": column})
+
+
+def _accepted_values(df: Any, intent: QualityIntent, functions: Any) -> QualityRuleResult:
+    column_name = intent.columns[0]
+    column = functions.col(column_name)
+    values = _values(intent.value)
+    if len(values) > MAX_INLINE_ACCEPTED_VALUES:
+        raise ValueError(
+            f"quality.accepted_values.{column_name} has {len(values)} values. "
+            "Use a reference table or custom quality evaluator for large value sets."
+        )
+    invalid = (~column.isin(values)) & column.isNotNull()
+    count = _agg_int(df, functions.sum(invalid.cast("long")).alias("failed_rows"), "failed_rows")
+    return QualityRuleResult(intent.name, "FAILED" if count else "PASSED", count, _severity(intent), intent.message, {"column": column_name, "values": values})
+
+
+def _max_null_ratio(df: Any, intent: QualityIntent, functions: Any, row_count: int) -> QualityRuleResult:
+    column = intent.columns[0]
+    null_count = _agg_int(df, functions.sum(functions.col(column).isNull().cast("long")).alias("failed_rows"), "failed_rows")
+    ratio = 0.0 if row_count == 0 else null_count / row_count
+    failed = ratio > float(intent.value)
+    return QualityRuleResult(intent.name, "FAILED" if failed else "PASSED", null_count if failed else 0, _severity(intent), intent.message, {"column": column, "ratio": ratio, "max_ratio": intent.value})
+
+
+def _unique_key(df: Any, intent: QualityIntent, functions: Any) -> QualityRuleResult:
+    duplicates = df.groupBy(*intent.columns).count().where(functions.col("count") > 1).count()
+    count = int(duplicates or 0)
+    return QualityRuleResult(intent.name, "FAILED" if count else "PASSED", count, "abort", intent.message, {"columns": list(intent.columns)})
+
+
+def _row_count_minimum(intent: QualityIntent, row_count: int) -> QualityRuleResult:
+    minimum = int(intent.value)
+    failed = max(0, minimum - row_count)
+    return QualityRuleResult(intent.name, "FAILED" if failed else "PASSED", failed, "abort", intent.message, {"min_rows": minimum, "actual": row_count})
+
+
+def _expression(df: Any, intent: QualityIntent, functions: Any) -> tuple[QualityRuleResult, Any]:
+    expression = functions.expr(str(intent.value))
+    invalid = expression.isNull() | (expression == functions.lit(False))
+    count = _agg_int(df, functions.sum(invalid.cast("long")).alias("failed_rows"), "failed_rows")
+    severity = _severity(intent)
+    status = "WARNED" if count and severity == "warn" else "FAILED" if count else "PASSED"
+    return QualityRuleResult(intent.name, status, count, severity, intent.message, {"expression": intent.value}), invalid
+
+
+def _agg_int(df: Any, expression: Any, field: str) -> int:
+    row = df.agg(expression).collect()[0]
+    return int((row[field] if row is not None else 0) or 0)
+
+
+def _row_count(df: Any) -> int:
+    return int(df.count() or 0)
+
+
+def _validate_columns(df: Any, columns: tuple[str, ...], context: str) -> None:
+    missing = [column for column in columns if column not in (getattr(df, "columns", ()) or ())]
+    if missing:
+        raise ValueError(f"{context} not found: {missing}")
+
+
+def _values(value: object) -> list[Any]:
+    if isinstance(value, (list, tuple, set)):
+        return list(value)
+    return [value]
+
+
+def _severity(intent: QualityIntent) -> str:
+    return str(intent.severity or "quarantine")  # type: ignore[return-value]
+
+
+def _functions() -> Any:
+    return import_module("pyspark.sql").functions
+
+
+def _custom_quality_rules(contract_or_quality: SemanticContract | tuple[QualityIntent, ...]) -> dict[str, dict[str, Any]]:
+    if not isinstance(contract_or_quality, SemanticContract):
+        return {}
+    extensions = contract_or_quality.extensions or {}
+    quality = extensions.get("quality") if isinstance(extensions, dict) else None
+    custom = quality.get("custom") if isinstance(quality, dict) else None
+    return dict(custom) if isinstance(custom, dict) else {}

contractforge_databricks/quality/persistence.py

@@ -0,0 +1,81 @@
+"""Databricks SQL rendering for quality and quarantine persistence."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+
+from contractforge_core.quality import QualityRuleResult
+from contractforge_databricks.evidence import QuarantineEvidenceRecord
+from contractforge_databricks.evidence.sql import render_quarantine_insert_sql
+from contractforge_databricks.evidence.tables import evidence_table_names
+from contractforge_databricks.sql import quote_table_name, sql_int, sql_string
+
+
+def render_quality_result_insert_sql(
+    *,
+    run_id: str,
+    target_table: str,
+    result: QualityRuleResult,
+    checked_at_utc: datetime,
+    catalog: str = "main",
+    schema: str = "ops",
+) -> str:
+    table = evidence_table_names(catalog, schema)["quality"]
+    checked_at = checked_at_utc.strftime("%Y-%m-%d %H:%M:%S")
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, rule_name, status, severity, failed_count, observed_value, "
+        "checked_at_utc, message, details_json) VALUES "
+        f"({sql_string(run_id)}, {sql_string(target_table)}, {sql_string(result.rule_name)}, "
+        f"{sql_string(result.status)}, {sql_string(result.severity)}, {sql_int(result.failed_count)}, "
+        f"{_json(result.as_dict())}, TIMESTAMP {sql_string(checked_at)}, "
+        f"{sql_string(result.message)}, {_json(result.details or {})})"
+    )
+
+
+def render_quality_results_insert_sql(
+    *,
+    run_id: str,
+    target_table: str,
+    results: tuple[QualityRuleResult, ...],
+    checked_at_utc: datetime,
+    catalog: str = "main",
+    schema: str = "ops",
+) -> str:
+    statements = [
+        render_quality_result_insert_sql(
+            run_id=run_id,
+            target_table=target_table,
+            result=result,
+            checked_at_utc=checked_at_utc,
+            catalog=catalog,
+            schema=schema,
+        )
+        for result in results
+    ]
+    return ";\n".join(statements) + (";\n" if statements else "-- No quality results to persist.\n")
+
+
+def render_quarantine_reference_insert_sql(
+    *,
+    run_id: str,
+    target_table: str,
+    record_ref: str,
+    reason: str,
+    quarantined_at_utc: datetime,
+    catalog: str = "main",
+    schema: str = "ops",
+) -> str:
+    record = QuarantineEvidenceRecord(
+        run_id=run_id,
+        target_table=target_table,
+        record_ref=record_ref,
+        reason=reason,
+        quarantined_at_utc=quarantined_at_utc,
+    )
+    return render_quarantine_insert_sql(record, catalog=catalog, schema=schema)
+
+
+def _json(value: object) -> str:
+    return sql_string(json.dumps(value, sort_keys=True, separators=(",", ":")))

contractforge_databricks/quality/registry.py

@@ -0,0 +1,134 @@
+"""Databricks runtime registry for custom quality evaluators."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib import import_module
+from typing import Any
+
+from contractforge_core.config import VALID_QUALITY_RULE_SEVERITIES
+from contractforge_core.quality import QualityRuleResult, is_abort_only_failure as is_abort_only_failure
+
+QualityRuleEvaluator = Callable[[Any, str, dict[str, Any]], dict[str, Any]]
+QUALITY_RULE_REGISTRY: dict[str, QualityRuleEvaluator] = {}
+
+
+def register_quality_rule(rule_type: str, evaluator: QualityRuleEvaluator, *, overwrite: bool = False) -> None:
+    normalized = _normalize_rule_type(rule_type)
+    if not callable(evaluator):
+        raise ValueError("quality rule evaluator must be callable")
+    if normalized in QUALITY_RULE_REGISTRY and not overwrite:
+        raise ValueError(f"quality rule already registered: {normalized}")
+    QUALITY_RULE_REGISTRY[normalized] = evaluator
+
+
+def unregister_quality_rule(rule_type: str) -> None:
+    QUALITY_RULE_REGISTRY.pop(_normalize_rule_type(rule_type), None)
+
+
+def get_quality_rule(rule_type: str) -> QualityRuleEvaluator | None:
+    return QUALITY_RULE_REGISTRY.get(_normalize_rule_type(rule_type))
+
+
+def list_quality_rules() -> tuple[str, ...]:
+    return tuple(sorted(QUALITY_RULE_REGISTRY))
+
+
+def clear_quality_rule_registry() -> None:
+    QUALITY_RULE_REGISTRY.clear()
+
+
+def evaluate_custom_quality_rules(df: Any, custom_rules: dict[str, dict[str, Any]] | None) -> tuple[QualityRuleResult, ...]:
+    if not custom_rules:
+        return ()
+    results: list[QualityRuleResult] = []
+    for rule_name, config in custom_rules.items():
+        rule_type = str(config.get("type") or "").strip()
+        evaluator = QUALITY_RULE_REGISTRY.get(rule_type)
+        if evaluator is None:
+            raise ValueError(f"quality_rules.custom.{rule_name} uses unregistered type: {rule_type}")
+        payload = evaluator(df, str(rule_name), dict(config))
+        failed_count = int(payload.get("failed_count", 0) or 0)
+        severity = str(payload.get("severity") or config.get("severity") or "abort").strip()
+        if severity not in VALID_QUALITY_RULE_SEVERITIES:
+            raise ValueError(
+                f"quality_rules.custom.{rule_name}.severity={severity!r} is not supported. "
+                f"Valid values: {sorted(VALID_QUALITY_RULE_SEVERITIES)}"
+            )
+        status = _status(failed_count, severity)
+        results.append(
+            QualityRuleResult(
+                rule_name=f"custom:{rule_name}",
+                status=status,
+                failed_count=failed_count,
+                severity=severity,  # type: ignore[arg-type]
+                message=payload.get("message") or config.get("message"),
+                details={"name": rule_name, "type": rule_type, **dict(payload.get("details") or {})},
+            )
+        )
+    return tuple(results)
+
+
+def evaluate_custom_quality_runtime(
+    df: Any,
+    custom_rules: dict[str, dict[str, Any]] | None,
+) -> tuple[tuple[QualityRuleResult, ...], Any | None]:
+    if not custom_rules:
+        return (), None
+    functions = import_module("pyspark.sql").functions
+    quarantine_condition = functions.lit(False)
+    has_quarantine_condition = False
+    results: list[QualityRuleResult] = []
+    for rule_name, config in custom_rules.items():
+        rule_type = str(config.get("type") or "").strip()
+        evaluator = QUALITY_RULE_REGISTRY.get(rule_type)
+        if evaluator is None:
+            raise ValueError(f"quality_rules.custom.{rule_name} uses unregistered type: {rule_type}")
+        payload = evaluator(df, str(rule_name), dict(config))
+        result = _custom_result(str(rule_name), rule_type, config, payload)
+        results.append(result)
+        if result.failed_count and result.severity == "quarantine":
+            condition = payload.get("condition")
+            if condition is None:
+                raise ValueError(f"quality_rules.custom.{rule_name} with severity=quarantine must return condition")
+            quarantine_condition = quarantine_condition | condition
+            has_quarantine_condition = True
+    return tuple(results), quarantine_condition if has_quarantine_condition else None
+
+
+def _custom_result(
+    rule_name: str,
+    rule_type: str,
+    config: dict[str, Any],
+    payload: dict[str, Any],
+) -> QualityRuleResult:
+    failed_count = int(payload.get("failed_count", 0) or 0)
+    severity = str(payload.get("severity") or config.get("severity") or "abort").strip()
+    if severity not in VALID_QUALITY_RULE_SEVERITIES:
+        raise ValueError(
+            f"quality_rules.custom.{rule_name}.severity={severity!r} is not supported. "
+            f"Valid values: {sorted(VALID_QUALITY_RULE_SEVERITIES)}"
+        )
+    return QualityRuleResult(
+        rule_name=f"custom:{rule_name}",
+        status=_status(failed_count, severity),
+        failed_count=failed_count,
+        severity=severity,  # type: ignore[arg-type]
+        message=payload.get("message") or config.get("message"),
+        details={"name": rule_name, "type": rule_type, **dict(payload.get("details") or {})},
+    )
+
+
+def _status(failed_count: int, severity: str) -> str:
+    if failed_count <= 0:
+        return "PASSED"
+    if severity == "warn":
+        return "WARNED"
+    return "FAILED"
+
+
+def _normalize_rule_type(rule_type: str) -> str:
+    normalized = str(rule_type or "").strip()
+    if not normalized:
+        raise ValueError("quality rule type cannot be empty")
+    return normalized