contractforge-databricks 0.1.0__py3-none-any.whl

contractforge_databricks/evidence/run_log.py

@@ -0,0 +1,74 @@
+"""Full ContractForge run ledger SQL rendering."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from contractforge_databricks.evidence.helpers import cast_sql
+from contractforge_databricks.evidence.schemas import EVIDENCE_TABLE_COLUMNS
+from contractforge_databricks.evidence.tables import evidence_table_names
+from contractforge_databricks.security import redact_text, redact_value
+from contractforge_databricks.sql import quote_table_name, sql_int, sql_string
+
+RUN_COLUMNS = tuple(column.split(" ", 1)[0] for column in EVIDENCE_TABLE_COLUMNS["runs"])
+RUN_INT_COLUMNS = {
+    "rows_read",
+    "rows_written",
+    "rows_inserted",
+    "rows_updated",
+    "rows_deleted",
+    "rows_expired",
+    "rows_quarantined",
+    "ctrl_schema_version",
+}
+RUN_FLOAT_COLUMNS = {"duration_seconds"}
+RUN_BOOL_COLUMNS = {"write_committed"}
+RUN_DATE_COLUMNS = {"run_date"}
+RUN_TIMESTAMP_COLUMNS = {
+    "run_ts_utc",
+    "started_at_utc",
+    "finished_at_utc",
+    "write_started_at_utc",
+    "write_finished_at_utc",
+}
+
+
+def render_run_log_insert_sql(
+    payload: dict[str, Any],
+    *,
+    catalog: str = "main",
+    schema: str = "ops",
+) -> str:
+    table = evidence_table_names(catalog, schema)["runs"]
+    values = [_render_run_value(column, payload.get(column)) for column in RUN_COLUMNS]
+    return (
+        f"INSERT INTO {quote_table_name(table)} ({', '.join(RUN_COLUMNS)}) VALUES "
+        f"({', '.join(values)})"
+    )
+
+
+def _render_run_value(column: str, value: Any) -> str:
+    if column in RUN_INT_COLUMNS:
+        return sql_int(value)
+    if column in RUN_FLOAT_COLUMNS:
+        return "NULL" if value is None else str(float(value))
+    if column in RUN_BOOL_COLUMNS:
+        return "NULL" if value is None else str(bool(value)).lower()
+    if column in RUN_DATE_COLUMNS:
+        return cast_sql(value, "DATE")
+    if column in RUN_TIMESTAMP_COLUMNS or column.endswith("_utc"):
+        return cast_sql(value, "TIMESTAMP")
+    if column.endswith("_json"):
+        return sql_string(_json_text(value))
+    if column == "error_message":
+        return sql_string(redact_text(str(value))[:4000] if value is not None else None)
+    return sql_string(redact_value(value))
+
+
+def _json_text(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return redact_text(value)
+    return json.dumps(redact_value(value), sort_keys=True, separators=(",", ":"))

contractforge_databricks/evidence/schemas.py

@@ -0,0 +1,7 @@
+"""Databricks facade over core-owned control table schemas."""
+
+from __future__ import annotations
+
+from contractforge_core.evidence import EVIDENCE_TABLE_COLUMNS, EVIDENCE_TABLE_SCHEMAS
+
+__all__ = ["EVIDENCE_TABLE_COLUMNS", "EVIDENCE_TABLE_SCHEMAS"]

contractforge_databricks/evidence/sql.py

@@ -0,0 +1,144 @@
+"""Render INSERT statements for Databricks evidence tables."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+
+from contractforge_core.evidence import (
+    AccessEvidenceRecord,
+    CostEvidenceRecord,
+    ErrorEvidenceRecord,
+    LineageEvidenceRecord,
+    QualityEvidenceRecord,
+    QuarantineEvidenceRecord,
+    RunEvidenceRecord,
+    SchemaChangeEvidenceRecord,
+    SourceMetadataEvidenceRecord,
+    StreamBatchEvidenceRecord,
+)
+from contractforge_databricks.evidence.tables import evidence_table_names
+from contractforge_databricks.sql import quote_table_name
+
+
+def render_run_insert_sql(record: RunEvidenceRecord, *, catalog: str = "main", schema: str = "ops") -> str:
+    table = evidence_table_names(catalog, schema)["runs"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, mode, status, started_at_utc, finished_at_utc, metrics_json) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.mode)}, {_s(record.status)}, "
+        f"{_ts(record.started_at_utc)}, {_ts(record.finished_at_utc)}, {_json(record.metrics or {})})"
+    )
+
+
+def render_error_insert_sql(record: ErrorEvidenceRecord, *, catalog: str = "main", schema: str = "ops") -> str:
+    table = evidence_table_names(catalog, schema)["errors"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, error_class, error_message, occurred_at_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.error_class)}, {_s(record.error_message)}, "
+        f"{_ts(record.occurred_at_utc)})"
+    )
+
+
+def render_lineage_insert_sql(record: LineageEvidenceRecord, *, catalog: str = "main", schema: str = "ops") -> str:
+    table = evidence_table_names(catalog, schema)["lineage"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, source_name, event_json, event_time_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.source_name)}, {_json(record.event)}, "
+        f"{_ts(record.event_time_utc)})"
+    )
+
+
+def render_quality_insert_sql(record: QualityEvidenceRecord, *, catalog: str = "main", schema: str = "ops") -> str:
+    table = evidence_table_names(catalog, schema)["quality"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, rule_name, status, observed_value, checked_at_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.rule_name)}, {_s(record.status)}, "
+        f"{_s(record.observed_value)}, {_ts(record.checked_at_utc)})"
+    )
+
+
+def render_schema_change_insert_sql(
+    record: SchemaChangeEvidenceRecord, *, catalog: str = "main", schema: str = "ops"
+) -> str:
+    table = evidence_table_names(catalog, schema)["schema_changes"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, change_type, payload_json, changed_at_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.change_type)}, {_json(record.payload)}, "
+        f"{_ts(record.changed_at_utc)})"
+    )
+
+
+def render_cost_insert_sql(record: CostEvidenceRecord, *, catalog: str = "main", schema: str = "ops") -> str:
+    table = evidence_table_names(catalog, schema)["cost"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, signal_name, signal_value, payload_json, captured_at_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.signal_name)}, {record.signal_value}, "
+        f"{_json(record.payload)}, {_ts(record.captured_at_utc)})"
+    )
+
+
+def render_quarantine_insert_sql(
+    record: QuarantineEvidenceRecord, *, catalog: str = "main", schema: str = "ops"
+) -> str:
+    table = evidence_table_names(catalog, schema)["quarantine"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, record_ref, reason, quarantined_at_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.record_ref)}, {_s(record.reason)}, "
+        f"{_ts(record.quarantined_at_utc)})"
+    )
+
+
+def render_source_metadata_insert_sql(
+    record: SourceMetadataEvidenceRecord, *, catalog: str = "main", schema: str = "ops"
+) -> str:
+    table = evidence_table_names(catalog, schema)["metadata"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, source_metadata_json, captured_at_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_json(record.source_metadata)}, "
+        f"{_ts(record.captured_at_utc)})"
+    )
+
+
+def render_stream_batch_insert_sql(
+    record: StreamBatchEvidenceRecord, *, catalog: str = "main", schema: str = "ops"
+) -> str:
+    table = evidence_table_names(catalog, schema)["streams"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, batch_id, batch_metrics_json, captured_at_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.batch_id)}, {_json(record.batch_metrics)}, "
+        f"{_ts(record.captured_at_utc)})"
+    )
+
+
+def render_access_insert_sql(record: AccessEvidenceRecord, *, catalog: str = "main", schema: str = "ops") -> str:
+    table = evidence_table_names(catalog, schema)["access"]
+    return (
+        f"INSERT INTO {quote_table_name(table)} "
+        "(run_id, target_table, action, status, payload_json, applied_at_utc) VALUES "
+        f"({_s(record.run_id)}, {_s(record.target_table)}, {_s(record.action)}, {_s(record.status)}, "
+        f"{_json(record.payload)}, {_ts(record.applied_at_utc)})"
+    )
+
+
+def _json(value: dict[str, Any]) -> str:
+    return _s(json.dumps(value, sort_keys=True, separators=(",", ":")))
+
+
+def _s(value: object) -> str:
+    return "'" + str(value).replace("'", "''") + "'"
+
+
+def _ts(value: datetime | None) -> str:
+    if value is None:
+        return "NULL"
+    return f"TIMESTAMP {_s(value.strftime('%Y-%m-%d %H:%M:%S'))}"

contractforge_databricks/evidence/tables.py

@@ -0,0 +1,20 @@
+"""Databricks implementation notes for the core evidence model."""
+
+from __future__ import annotations
+
+from contractforge_core.evidence import EVIDENCE_TABLES
+
+
+def evidence_table_names(catalog: str, schema: str) -> dict[str, str]:
+    return {name: f"{catalog}.{schema}.{table}" for name, table in EVIDENCE_TABLES.items()}
+
+
+def render_evidence_table_notes(*, catalog: str = "main", schema: str = "ops") -> str:
+    lines = [
+        "-- Databricks evidence table mapping.",
+        "-- These notes are intentionally non-executing review artifacts.",
+        "",
+    ]
+    for name, table in evidence_table_names(catalog, schema).items():
+        lines.append(f"-- {name}: {table}")
+    return "\n".join(lines) + "\n"

contractforge_databricks/evidence/writer.py

@@ -0,0 +1,118 @@
+"""Evidence writer using an injected SQL runner."""
+
+from __future__ import annotations
+
+from contractforge_core.evidence import (
+    AccessEvidenceRecord,
+    CostEvidenceRecord,
+    ErrorEvidenceRecord,
+    LineageEvidenceRecord,
+    QualityEvidenceRecord,
+    QuarantineEvidenceRecord,
+    RunEvidenceRecord,
+    SchemaChangeEvidenceRecord,
+    SourceMetadataEvidenceRecord,
+    StreamBatchEvidenceRecord,
+)
+from contractforge_databricks.evidence.helpers import TimestampClock
+from contractforge_databricks.evidence.ops_log import (
+    render_error_log_insert_sql,
+    render_schema_change_log_insert_sql,
+    render_stream_finish_update_sql,
+    render_stream_log_insert_sql,
+)
+from contractforge_databricks.evidence.governance_log import (
+    render_access_log_insert_sql,
+    render_annotation_log_insert_sql,
+    render_operations_log_insert_sql,
+)
+from contractforge_databricks.evidence.run_log import render_run_log_insert_sql
+from contractforge_databricks.evidence.sql import (
+    render_access_insert_sql,
+    render_cost_insert_sql,
+    render_error_insert_sql,
+    render_lineage_insert_sql,
+    render_quality_insert_sql,
+    render_quarantine_insert_sql,
+    render_run_insert_sql,
+    render_schema_change_insert_sql,
+    render_source_metadata_insert_sql,
+    render_stream_batch_insert_sql,
+)
+from contractforge_databricks.execution.sql_merge import SqlRunner
+
+
+class EvidenceWriter:
+    def __init__(
+        self,
+        runner: SqlRunner,
+        *,
+        catalog: str = "main",
+        schema: str = "ops",
+        clock: TimestampClock | None = None,
+    ) -> None:
+        self.runner = runner
+        self.catalog = catalog
+        self.schema = schema
+        self.clock = clock
+
+    def write_run(self, record: RunEvidenceRecord) -> None:
+        self.runner.sql(render_run_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_run_log(self, payload: dict[str, object]) -> None:
+        self.runner.sql(render_run_log_insert_sql(payload, catalog=self.catalog, schema=self.schema))
+
+    def write_error(self, record: ErrorEvidenceRecord) -> None:
+        self.runner.sql(render_error_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_error_log(self, payload: dict[str, object]) -> None:
+        self.runner.sql(render_error_log_insert_sql(payload, catalog=self.catalog, schema=self.schema))
+
+    def write_lineage(self, record: LineageEvidenceRecord) -> None:
+        self.runner.sql(render_lineage_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_quality(self, record: QualityEvidenceRecord) -> None:
+        self.runner.sql(render_quality_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_schema_change(self, record: SchemaChangeEvidenceRecord) -> None:
+        self.runner.sql(render_schema_change_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_schema_change_log(self, payload: dict[str, object]) -> None:
+        self.runner.sql(render_schema_change_log_insert_sql(payload, catalog=self.catalog, schema=self.schema))
+
+    def write_cost(self, record: CostEvidenceRecord) -> None:
+        self.runner.sql(render_cost_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_quarantine(self, record: QuarantineEvidenceRecord) -> None:
+        self.runner.sql(render_quarantine_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_source_metadata(self, record: SourceMetadataEvidenceRecord) -> None:
+        self.runner.sql(render_source_metadata_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_stream_batch(self, record: StreamBatchEvidenceRecord) -> None:
+        self.runner.sql(render_stream_batch_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_stream_log(self, payload: dict[str, object]) -> None:
+        self.runner.sql(render_stream_log_insert_sql(payload, catalog=self.catalog, schema=self.schema, clock=self.clock))
+
+    def finish_stream_log(self, *, stream_run_id: str, payload: dict[str, object]) -> None:
+        statement = render_stream_finish_update_sql(
+            stream_run_id=stream_run_id,
+            payload=payload,
+            catalog=self.catalog,
+            schema=self.schema,
+        )
+        if statement is not None:
+            self.runner.sql(statement)
+
+    def write_access(self, record: AccessEvidenceRecord) -> None:
+        self.runner.sql(render_access_insert_sql(record, catalog=self.catalog, schema=self.schema))
+
+    def write_annotation_log(self, payload: dict[str, object]) -> None:
+        self.runner.sql(render_annotation_log_insert_sql(payload, catalog=self.catalog, schema=self.schema, clock=self.clock))
+
+    def write_access_log(self, payload: dict[str, object]) -> None:
+        self.runner.sql(render_access_log_insert_sql(payload, catalog=self.catalog, schema=self.schema, clock=self.clock))
+
+    def write_operations_log(self, payload: dict[str, object]) -> None:
+        self.runner.sql(render_operations_log_insert_sql(payload, catalog=self.catalog, schema=self.schema, clock=self.clock))

contractforge_databricks/execution/__init__.py

@@ -0,0 +1,70 @@
+from contractforge_core.execution import ExecutionOutcome
+from contractforge_databricks.execution.delta_basic import (
+    execute_append,
+    execute_overwrite,
+    render_append_sql,
+    render_overwrite_sql,
+)
+from contractforge_databricks.execution.hash_diff import execute_hash_diff_insert, render_hash_diff_insert_sql
+from contractforge_databricks.execution.replace_partitions import (
+    execute_replace_partitions,
+    render_replace_partitions_sql,
+)
+from contractforge_databricks.execution.retry import is_retryable_delta_concurrency_error, with_delta_retry
+from contractforge_databricks.execution.scd2 import execute_scd2_merge, render_scd2_merge_sql, render_scd2_stage_sql
+from contractforge_databricks.execution.scd2_deletes import render_scd2_delete_merge_sql
+from contractforge_databricks.execution.sql_merge import SqlRunner, execute_scd1_merge, render_scd1_merge_sql
+from contractforge_databricks.execution.snapshot import execute_snapshot_soft_delete, render_snapshot_soft_delete_sql
+from contractforge_databricks.execution.tables import (
+    execute_table_setup,
+    render_cluster_by_sql,
+    render_create_delta_table_sql,
+    render_create_schema_sql,
+    render_delta_properties_sql,
+    render_table_setup_sql,
+)
+from contractforge_databricks.execution.windows import (
+    ChildWindowPlan,
+    ExecutionWindow,
+    build_child_window_plan,
+    build_time_windows,
+    combine_filter,
+    render_window_filter_sql,
+    summarize_window_results,
+)
+
+__all__ = [
+    "ChildWindowPlan",
+    "ExecutionOutcome",
+    "ExecutionWindow",
+    "is_retryable_delta_concurrency_error",
+    "with_delta_retry",
+    "SqlRunner",
+    "build_child_window_plan",
+    "build_time_windows",
+    "combine_filter",
+    "execute_append",
+    "execute_hash_diff_insert",
+    "execute_overwrite",
+    "execute_replace_partitions",
+    "execute_scd1_merge",
+    "execute_scd2_merge",
+    "execute_snapshot_soft_delete",
+    "execute_table_setup",
+    "render_append_sql",
+    "render_cluster_by_sql",
+    "render_create_delta_table_sql",
+    "render_create_schema_sql",
+    "render_delta_properties_sql",
+    "render_hash_diff_insert_sql",
+    "render_overwrite_sql",
+    "render_replace_partitions_sql",
+    "render_scd2_merge_sql",
+    "render_scd2_stage_sql",
+    "render_scd2_delete_merge_sql",
+    "render_scd1_merge_sql",
+    "render_snapshot_soft_delete_sql",
+    "render_table_setup_sql",
+    "render_window_filter_sql",
+    "summarize_window_results",
+]

contractforge_databricks/execution/delta_basic.py

@@ -0,0 +1,57 @@
+"""Databricks Delta append and overwrite helpers."""
+
+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_table_name
+
+
+def render_append_sql(*, target_table: str, source_view: str) -> str:
+    return f"INSERT INTO {quote_table_name(target_table)}\nSELECT * FROM {quote_table_name(source_view)}"
+
+
+def render_overwrite_sql(*, target_table: str, source_view: str) -> str:
+    return f"INSERT OVERWRITE TABLE {quote_table_name(target_table)}\nSELECT * FROM {quote_table_name(source_view)}"
+
+
+def execute_append(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    source_view: str,
+) -> ExecutionOutcome:
+    if contract.write.mode != "scd0_append":
+        raise ValueError(f"execute_append only supports scd0_append, got {contract.write.mode}")
+    target = target_full_name(contract)
+    statement = render_append_sql(target_table=target, source_view=source_view)
+    runner.sql(statement)
+    return ExecutionOutcome(
+        status="SUCCESS",
+        operation="delta_append",
+        target=target,
+        metrics={},
+        sql=statement,
+    )
+
+
+def execute_overwrite(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    source_view: str,
+) -> ExecutionOutcome:
+    if contract.write.mode != "scd0_overwrite":
+        raise ValueError(f"execute_overwrite only supports scd0_overwrite, got {contract.write.mode}")
+    target = target_full_name(contract)
+    statement = render_overwrite_sql(target_table=target, source_view=source_view)
+    runner.sql(statement)
+    return ExecutionOutcome(
+        status="SUCCESS",
+        operation="delta_overwrite",
+        target=target,
+        metrics={},
+        sql=statement,
+    )

contractforge_databricks/execution/hash_diff.py

@@ -0,0 +1,126 @@
+"""ContractForge-compatible SCD1 hash-diff append SQL."""
+
+from __future__ import annotations
+
+from contractforge_core.runtime import QueryOne
+from contractforge_core.semantic import SemanticContract
+from contractforge_core.execution import ExecutionOutcome
+from contractforge_databricks.execution.hash_diff_latest import (
+    resolve_hash_diff_latest_selection,
+    validate_hash_diff_target_latest,
+)
+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_hash_diff_insert_sql(
+    *,
+    target_table: str,
+    source_view: str,
+    merge_keys: tuple[str, ...],
+    source_columns: tuple[str, ...],
+    row_hash_column: str = "row_hash",
+    latest_order_by: str | None = None,
+) -> str:
+    if not merge_keys:
+        raise ValueError("scd1_hash_diff requires merge_keys")
+    _require_columns(source_columns, merge_keys, "merge_keys")
+    if row_hash_column not in source_columns:
+        raise ValueError(f"prepared hash-diff source is missing {row_hash_column}")
+
+    join_condition = " AND ".join(
+        f"t.{quote_identifier(key)} <=> s.{quote_identifier(key)}" for key in merge_keys
+    )
+    null_condition = " AND ".join(f"t.{quote_identifier(key)} IS NULL" for key in merge_keys)
+    columns = ", ".join(quote_identifier(column) for column in source_columns)
+    values = ", ".join(f"s.{quote_identifier(column)}" for column in source_columns)
+
+    target_relation = _target_latest_relation(
+        target_table=target_table,
+        merge_keys=merge_keys,
+        row_hash_column=row_hash_column,
+        latest_order_by=latest_order_by,
+    )
+    lines = [
+        f"INSERT INTO {quote_table_name(target_table)} ({columns})",
+        f"SELECT {values}",
+        f"FROM {quote_table_name(source_view)} s",
+        "LEFT JOIN (",
+        *target_relation,
+        ") t",
+        f"ON {join_condition}",
+        f"WHERE ({null_condition}) OR NOT (t.{quote_identifier(row_hash_column)} <=> s.{quote_identifier(row_hash_column)})",
+    ]
+    return "\n".join(lines)
+
+
+def _target_latest_relation(
+    *,
+    target_table: str,
+    merge_keys: tuple[str, ...],
+    row_hash_column: str,
+    latest_order_by: str | None,
+) -> list[str]:
+    selected = f"{', '.join(quote_identifier(key) for key in merge_keys)}, {quote_identifier(row_hash_column)}"
+    if not latest_order_by:
+        return [f"  SELECT {selected}", f"  FROM {quote_table_name(target_table)}"]
+    partition = ", ".join(quote_identifier(key) for key in merge_keys)
+    return [
+        f"  SELECT {selected}",
+        "  FROM (",
+        f"    SELECT {selected},",
+        f"      row_number() OVER (PARTITION BY {partition} ORDER BY {latest_order_by}) AS __cf_latest_rank",
+        f"    FROM {quote_table_name(target_table)}",
+        "  ) latest",
+        "  WHERE __cf_latest_rank = 1",
+    ]
+
+
+def _require_columns(columns: tuple[str, ...], required: tuple[str, ...], context: str) -> None:
+    missing = [column for column in required if column not in columns]
+    if missing:
+        raise ValueError(f"prepared hash-diff source is missing {context}: {missing}")
+
+
+def execute_hash_diff_insert(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    source_view: str,
+    source_columns: tuple[str, ...],
+    target_schema: dict[str, str] | None = None,
+    query_one: QueryOne | None = None,
+) -> ExecutionOutcome:
+    if contract.write.mode != "scd1_hash_diff":
+        raise ValueError(f"execute_hash_diff_insert only supports scd1_hash_diff, got {contract.write.mode}")
+    target = target_full_name(contract)
+    merge_keys = contract.write.merge_keys or contract.write.hash_keys
+    selection = resolve_hash_diff_latest_selection(contract, target_schema)
+    validate_hash_diff_target_latest(
+        query_one=query_one,
+        target_table=target,
+        merge_keys=merge_keys,
+        selection=selection,
+    )
+    statement = render_hash_diff_insert_sql(
+        target_table=target,
+        source_view=source_view,
+        merge_keys=merge_keys,
+        source_columns=source_columns,
+        latest_order_by=selection.order_by,
+    )
+    runner.sql(statement)
+    return ExecutionOutcome(
+        status="SUCCESS",
+        operation="core_managed_hash_diff_delta",
+        target=target,
+        metrics={
+            "source_columns": len(source_columns),
+            "merge_keys": len(merge_keys),
+            "hash_keys": len(contract.write.hash_keys),
+            "target_latest_ordered": bool(selection.order_by),
+            "target_latest_reason": selection.reason,
+        },
+        sql=statement,
+    )