contractforge-databricks 0.1.0__py3-none-any.whl

contractforge_databricks/execution/sql_merge.py

@@ -0,0 +1,85 @@
+"""Databricks SQL MERGE execution helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from contractforge_core.semantic import SemanticContract
+from contractforge_core.execution import ExecutionOutcome
+from contractforge_databricks.rendering.names import target_full_name
+from contractforge_databricks.sql import quote_identifier, quote_table_name
+
+
+class SqlRunner(Protocol):
+    def sql(self, statement: str) -> Any:
+        ...
+
+
+def render_scd1_merge_sql(
+    *,
+    target_table: str,
+    source_view: str,
+    merge_keys: tuple[str, ...],
+    source_columns: tuple[str, ...],
+    target_partition_predicate: str | None = None,
+) -> str:
+    """Render deterministic SCD1 current-state MERGE SQL."""
+    if not merge_keys:
+        raise ValueError("scd1_upsert requires merge_keys")
+    if not source_columns:
+        raise ValueError("scd1_upsert requires source_columns")
+
+    missing_keys = [key for key in merge_keys if key not in source_columns]
+    if missing_keys:
+        raise ValueError(f"merge_keys missing from source_columns: {missing_keys}")
+
+    update_columns = tuple(column for column in source_columns if column not in merge_keys)
+    key_condition = " AND ".join(
+        f"t.{quote_identifier(key)} <=> s.{quote_identifier(key)}" for key in merge_keys
+    )
+    if target_partition_predicate:
+        key_condition = f"{key_condition} AND {target_partition_predicate}"
+    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)
+
+    lines = [
+        f"MERGE INTO {quote_table_name(target_table)} t",
+        f"USING {quote_table_name(source_view)} s",
+        f"ON {key_condition}",
+    ]
+    if update_set:
+        lines.append(f"WHEN MATCHED THEN UPDATE SET {update_set}")
+    lines.append(f"WHEN NOT MATCHED THEN INSERT ({insert_columns}) VALUES ({insert_values})")
+    return "\n".join(lines)
+
+
+def execute_scd1_merge(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    source_view: str,
+    source_columns: tuple[str, ...],
+    target_partition_predicate: str | None = None,
+) -> ExecutionOutcome:
+    if contract.write.mode != "scd1_upsert":
+        raise ValueError(f"execute_scd1_merge only supports scd1_upsert, got {contract.write.mode}")
+
+    target = target_full_name(contract)
+    statement = render_scd1_merge_sql(
+        target_table=target,
+        source_view=source_view,
+        merge_keys=contract.write.merge_keys,
+        source_columns=source_columns,
+        target_partition_predicate=target_partition_predicate,
+    )
+    runner.sql(statement)
+    return ExecutionOutcome(
+        status="SUCCESS",
+        operation="scd1_sql_merge",
+        target=target,
+        metrics={"source_columns": len(source_columns), "merge_keys": len(contract.write.merge_keys)},
+        sql=statement,
+    )

contractforge_databricks/execution/tables.py

@@ -0,0 +1,98 @@
+"""Databricks Delta table setup SQL helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contractforge_core.semantic import SemanticContract
+from contractforge_databricks.contract_extensions import databricks_extensions
+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, sql_literal
+
+
+def render_create_delta_table_sql(
+    *,
+    target_table: str,
+    columns: dict[str, str],
+    partition_column: str | None = None,
+    partition_columns: tuple[str, ...] = (),
+) -> str:
+    if not columns:
+        raise ValueError("Delta table creation requires at least one column")
+    partitions = tuple(partition_columns or ((partition_column,) if partition_column else ()))
+    missing_partition_columns = [column for column in partitions if column not in columns]
+    if missing_partition_columns:
+        raise ValueError(f"partition_columns missing from source columns: {missing_partition_columns}")
+    cols_sql = ", ".join(f"{quote_identifier(name)} {data_type}" for name, data_type in columns.items())
+    partition_sql = f" PARTITIONED BY ({', '.join(quote_identifier(column) for column in partitions)})" if partitions else ""
+    return f"CREATE TABLE IF NOT EXISTS {quote_table_name(target_table)} ({cols_sql}) USING DELTA{partition_sql}"
+
+
+def render_create_schema_sql(*, namespace: str | None) -> str | None:
+    if not namespace:
+        return None
+    return f"CREATE SCHEMA IF NOT EXISTS {quote_table_name(namespace)}"
+
+
+def render_cluster_by_sql(*, target_table: str, cluster_columns: tuple[str, ...]) -> str | None:
+    if not cluster_columns:
+        return None
+    columns_sql = ", ".join(quote_identifier(column) for column in cluster_columns)
+    return f"ALTER TABLE {quote_table_name(target_table)} CLUSTER BY ({columns_sql})"
+
+
+def render_delta_properties_sql(*, target_table: str, properties: dict[str, Any] | None) -> str | None:
+    if not properties:
+        return None
+    props_sql = ", ".join(f"{sql_literal(key)} = {sql_literal(value)}" for key, value in sorted(properties.items()))
+    return f"ALTER TABLE {quote_table_name(target_table)} SET TBLPROPERTIES ({props_sql})"
+
+
+def render_table_setup_sql(
+    contract: SemanticContract,
+    *,
+    columns: dict[str, str],
+) -> tuple[str, ...]:
+    extensions = databricks_extensions(contract)
+    target = target_full_name(contract)
+    cluster_columns = tuple(str(column) for column in extensions.get("cluster_columns") or ())
+    partition_columns = _partition_columns(extensions)
+    missing_cluster_columns = [column for column in cluster_columns if column not in columns]
+    if missing_cluster_columns:
+        raise ValueError(f"cluster_columns missing from source columns: {missing_cluster_columns}")
+    if cluster_columns and partition_columns:
+        partition_columns = ()
+    statements = [
+        render_create_schema_sql(namespace=contract.target.namespace),
+        render_create_delta_table_sql(
+            target_table=target,
+            columns=columns,
+            partition_columns=partition_columns,
+        )
+    ]
+    cluster_sql = render_cluster_by_sql(target_table=target, cluster_columns=cluster_columns)
+    properties_sql = render_delta_properties_sql(target_table=target, properties=extensions.get("delta_properties"))
+    return tuple(statement for statement in (*statements, cluster_sql, properties_sql) if statement)
+
+
+def execute_table_setup(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    columns: dict[str, str],
+) -> tuple[str, ...]:
+    statements = render_table_setup_sql(contract, columns=columns)
+    for statement in statements:
+        runner.sql(statement)
+    return statements
+
+
+def _partition_columns(extensions: dict[str, Any]) -> tuple[str, ...]:
+    value = extensions.get("partition_columns")
+    if value:
+        if isinstance(value, str):
+            return (value,)
+        return tuple(str(column) for column in value)
+    single = str(extensions.get("partition_column") or "")
+    return (single,) if single else ()

contractforge_databricks/execution/windows.py

@@ -0,0 +1,58 @@
+"""Databricks execution window SQL helpers."""
+
+from __future__ import annotations
+
+import re
+
+from contractforge_core.execution import (
+    ChildWindowPlan,
+    ExecutionWindow,
+    build_time_windows,
+    combine_filter,
+    summarize_window_results,
+)
+from contractforge_core.execution import build_child_window_plan as build_core_child_window_plan
+from contractforge_databricks.sql import quote_identifier, sql_string
+
+_SIMPLE_COLUMN_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def render_window_filter_sql(column: str, window: ExecutionWindow) -> str:
+    if not _SIMPLE_COLUMN_RE.match(column):
+        raise ValueError("execution window column must be a simple column name")
+    quoted = quote_identifier(column)
+    return (
+        f"(CAST({quoted} AS TIMESTAMP) >= CAST({sql_string(window.start)} AS TIMESTAMP) "
+        f"AND CAST({quoted} AS TIMESTAMP) < CAST({sql_string(window.end)} AS TIMESTAMP))"
+    )
+
+
+def build_child_window_plan(
+    *,
+    parent_run_id: str,
+    column: str,
+    window: ExecutionWindow,
+    index: int,
+    existing_filter: str | None = None,
+    base_idempotency_key: str | None = None,
+) -> ChildWindowPlan:
+    return build_core_child_window_plan(
+        parent_run_id=parent_run_id,
+        column=column,
+        window=window,
+        index=index,
+        window_filter=render_window_filter_sql(column, window),
+        existing_filter=existing_filter,
+        base_idempotency_key=base_idempotency_key,
+    )
+
+
+__all__ = [
+    "ChildWindowPlan",
+    "ExecutionWindow",
+    "build_child_window_plan",
+    "build_time_windows",
+    "combine_filter",
+    "render_window_filter_sql",
+    "summarize_window_results",
+]

contractforge_databricks/governance/__init__.py

@@ -0,0 +1,30 @@
+from contractforge_core.results import GovernanceApplyResult
+from contractforge_databricks.governance.access import (
+    access_steps,
+    render_access_audit_insert_sql,
+    render_access_sql,
+    revoke_grant_steps,
+)
+from contractforge_databricks.governance.application import apply_access_contract
+from contractforge_databricks.governance.runtime import apply_governance_contract, check_governance_contract
+from contractforge_databricks.governance.sql import render_governance_sql
+from contractforge_databricks.governance.validation import (
+    access_drift_report,
+    governance_referenced_columns,
+    validate_governance_contract,
+)
+
+__all__ = [
+    "GovernanceApplyResult",
+    "access_steps",
+    "apply_access_contract",
+    "apply_governance_contract",
+    "check_governance_contract",
+    "access_drift_report",
+    "governance_referenced_columns",
+    "render_access_audit_insert_sql",
+    "render_access_sql",
+    "revoke_grant_steps",
+    "render_governance_sql",
+    "validate_governance_contract",
+]

contractforge_databricks/governance/access.py

@@ -0,0 +1,185 @@
+"""Render Unity Catalog access steps and audit SQL."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import Any
+
+from contractforge_core.semantic import SemanticContract
+from contractforge_databricks.coercion import string_list
+from contractforge_databricks.evidence.tables import evidence_table_names
+from contractforge_databricks.rendering.names import target_full_name
+from contractforge_databricks.sql import quote_identifier, quote_table_name, sql_string
+
+
+def access_steps(contract: SemanticContract) -> list[dict[str, Any]]:
+    governance = contract.governance
+    access = governance.access if governance else None
+    if not isinstance(access, dict):
+        return []
+    target = target_full_name(contract)
+    quoted_target = quote_table_name(target)
+    steps: list[dict[str, Any]] = []
+    for grant in access.get("grants", []):
+        principal = str(grant["principal"])
+        for privilege in string_list(grant.get("privileges")):
+            steps.append(_grant_step(quoted_target, target, principal, privilege, access))
+    for row_filter in access.get("row_filters", []):
+        steps.append(_row_filter_step(quoted_target, row_filter, access))
+    for column_mask in access.get("column_masks", []):
+        steps.append(_column_mask_step(quoted_target, column_mask, access))
+    return steps
+
+
+def revoke_grant_steps(contract: SemanticContract, unmanaged_grants: list[tuple[str, str]]) -> list[dict[str, Any]]:
+    access = contract.governance.access if contract.governance else None
+    if not isinstance(access, dict):
+        return []
+    target = target_full_name(contract)
+    quoted_target = quote_table_name(target)
+    return [_revoke_step(quoted_target, target, principal, privilege, access) for principal, privilege in unmanaged_grants]
+
+
+def render_access_sql(contract: SemanticContract) -> str:
+    return "\n".join(f"{step['sql']};" for step in access_steps(contract))
+
+
+def render_access_audit_insert_sql(
+    contract: SemanticContract,
+    *,
+    run_id: str = "${run_id}",
+    status: str = "PLANNED",
+    captured_at_utc: datetime | None = None,
+    catalog: str = "main",
+    schema: str = "ops",
+) -> str:
+    steps = access_steps(contract)
+    if not steps:
+        return "-- No access intent declared.\n"
+    table = evidence_table_names(catalog, schema)["access"]
+    captured_at_utc = captured_at_utc or datetime(1970, 1, 1, 0, 0, 0)
+    statements = [
+        _audit_insert(table, run_id, target_full_name(contract), step, status, captured_at_utc)
+        for step in steps
+    ]
+    return ";\n".join(statements) + ";\n"
+
+
+def _grant_step(
+    quoted_target: str,
+    target: str,
+    principal: str,
+    privilege: str,
+    access: dict[str, Any],
+) -> dict[str, Any]:
+    return {
+        "access_type": "grant",
+        "principal": principal,
+        "privilege": privilege,
+        "column_name": None,
+        "function_name": None,
+        "object_name": target,
+        "new_value": "GRANTED",
+        "mode": _access_policy(access, "mode", "apply"),
+        "drift_policy": _access_policy(access, "on_drift", "warn"),
+        "revoke_unmanaged": _access_policy(access, "revoke_unmanaged", False),
+        "sql": f"GRANT {privilege} ON TABLE {quoted_target} TO {_principal(principal)}",
+    }
+
+
+def _row_filter_step(quoted_target: str, row_filter: dict[str, Any], access: dict[str, Any]) -> dict[str, Any]:
+    columns = ", ".join(quote_identifier(column) for column in string_list(row_filter.get("columns")))
+    function = str(row_filter["function"])
+    return {
+        "access_type": "row_filter",
+        "principal": "|".join(string_list(row_filter.get("applies_to", {}).get("principals"))),
+        "privilege": "ROW_FILTER",
+        "column_name": "|".join(string_list(row_filter.get("columns"))),
+        "function_name": function,
+        "object_name": row_filter.get("name"),
+        "new_value": function,
+        "mode": _access_policy(access, "mode", "apply"),
+        "drift_policy": _access_policy(access, "on_drift", "warn"),
+        "revoke_unmanaged": _access_policy(access, "revoke_unmanaged", False),
+        "sql": f"ALTER TABLE {quoted_target} SET ROW FILTER {function} ON ({columns})",
+    }
+
+
+def _column_mask_step(quoted_target: str, column_mask: dict[str, Any], access: dict[str, Any]) -> dict[str, Any]:
+    column = str(column_mask["column"])
+    using_columns = string_list(column_mask.get("using_columns"))
+    using_sql = ""
+    if using_columns:
+        using_sql = " USING COLUMNS (" + ", ".join(quote_identifier(item) for item in using_columns) + ")"
+    function = str(column_mask["function"])
+    return {
+        "access_type": "column_mask",
+        "principal": "|".join(string_list(column_mask.get("applies_to", {}).get("principals"))),
+        "privilege": "COLUMN_MASK",
+        "column_name": column,
+        "function_name": function,
+        "object_name": column,
+        "new_value": function,
+        "mode": _access_policy(access, "mode", "apply"),
+        "drift_policy": _access_policy(access, "on_drift", "warn"),
+        "revoke_unmanaged": _access_policy(access, "revoke_unmanaged", False),
+        "sql": f"ALTER TABLE {quoted_target} ALTER COLUMN {quote_identifier(column)} SET MASK {function}{using_sql}",
+    }
+
+
+def _revoke_step(
+    quoted_target: str,
+    target: str,
+    principal: str,
+    privilege: str,
+    access: dict[str, Any],
+) -> dict[str, Any]:
+    return {
+        "access_type": "revoke",
+        "principal": principal,
+        "privilege": privilege,
+        "column_name": None,
+        "function_name": None,
+        "object_name": target,
+        "previous_value": "GRANTED",
+        "new_value": "REVOKED",
+        "mode": _access_policy(access, "mode", "apply"),
+        "drift_policy": _access_policy(access, "on_drift", "warn"),
+        "revoke_unmanaged": True,
+        "sql": f"REVOKE {privilege} ON TABLE {quoted_target} FROM {_principal(principal)}",
+    }
+
+
+def _audit_insert(table: str, run_id: str, target: str, step: dict[str, Any], status: str, captured_at_utc: datetime) -> str:
+    payload = json.dumps(step, sort_keys=True, separators=(",", ":"))
+    columns = "run_id, target_table, action, status, payload_json, applied_at_utc, access_type, principal, privilege, column_name, function_name, object_name, applied_sql, new_value, mode, drift_policy, revoke_unmanaged"
+    values = [
+        sql_string(run_id),
+        sql_string(target),
+        sql_string(step["access_type"]),
+        sql_string(status),
+        sql_string(payload),
+        f"TIMESTAMP {sql_string(captured_at_utc.strftime('%Y-%m-%d %H:%M:%S'))}",
+        sql_string(step["access_type"]),
+        sql_string(step.get("principal")),
+        sql_string(step.get("privilege")),
+        sql_string(step.get("column_name")),
+        sql_string(step.get("function_name")),
+        sql_string(step.get("object_name")),
+        sql_string(step.get("sql")),
+        sql_string(step.get("new_value")),
+        sql_string(step.get("mode")),
+        sql_string(step.get("drift_policy")),
+        "true" if bool(step.get("revoke_unmanaged")) else "false",
+    ]
+    return f"INSERT INTO {quote_table_name(table)} ({columns}) VALUES ({', '.join(values)})"
+
+
+def _access_policy(access: dict[str, Any], key: str, default: object) -> object:
+    policy = access.get("access_policy", {})
+    return policy.get(key, access.get(key, default)) if isinstance(policy, dict) else access.get(key, default)
+
+
+def _principal(value: str) -> str:
+    return "`" + value.replace("`", "``") + "`"

contractforge_databricks/governance/application.py

@@ -0,0 +1,93 @@
+"""Apply Databricks access governance with an injected SQL runner."""
+
+from __future__ import annotations
+
+from contractforge_core.semantic import SemanticContract
+from contractforge_core.results import GovernanceApplyResult
+from contractforge_databricks.execution.sql_merge import SqlRunner
+from contractforge_databricks.governance.access import access_steps, revoke_grant_steps
+from contractforge_databricks.governance.drift import current_contract_grants
+from contractforge_databricks.governance.validation import access_drift_report
+from contractforge_databricks.security import exception_message
+
+
+def apply_access_contract(
+    *,
+    runner: SqlRunner,
+    contract: SemanticContract,
+    allow_revoke_unmanaged: bool = False,
+) -> GovernanceApplyResult:
+    steps = access_steps(contract)
+    if not steps:
+        return GovernanceApplyResult(status="NOT_CONFIGURED")
+    drift = _drift(runner, contract)
+    if drift and drift["status"] == "DRIFTED" and _access_setting(contract, "on_drift", "warn") == "fail":
+        return GovernanceApplyResult(
+            status="FAILED",
+            failed=len(drift["issues"]) or 1,
+            sql_preview=tuple(str(step["sql"]) for step in steps),
+            errors=tuple(str(issue["message"]) for issue in drift["issues"]),
+        )
+    if _revoke_unmanaged(contract) and drift and drift["unmanaged_grants"]:
+        if not allow_revoke_unmanaged:
+            return GovernanceApplyResult(
+                status="FAILED",
+                failed=len(drift["unmanaged_grants"]),
+                sql_preview=tuple(str(step["sql"]) for step in steps),
+                errors=("access.revoke_unmanaged requires explicit allow_revoke_unmanaged=True",),
+            )
+        steps = [*steps, *revoke_grant_steps(contract, drift["unmanaged_grants"])]
+    sql_preview = tuple(str(step["sql"]) for step in steps)
+    mode = _access_setting(contract, "mode", "apply")
+    if mode == "ignore":
+        return GovernanceApplyResult(status="IGNORED", ignored=len(steps), sql_preview=sql_preview)
+    if mode == "validate_only":
+        return GovernanceApplyResult(status="VALIDATED", validated=len(steps), sql_preview=sql_preview)
+
+    applied = 0
+    errors: list[str] = []
+    fail_fast = _access_setting(contract, "on_drift", "warn") == "fail"
+    for statement in sql_preview:
+        try:
+            runner.sql(statement)
+            applied += 1
+        except Exception as exc:
+            errors.append(exception_message(exc))
+            if fail_fast:
+                return GovernanceApplyResult(
+                    status="FAILED",
+                    applied=applied,
+                    failed=len(errors),
+                    sql_preview=sql_preview,
+                    errors=tuple(errors),
+                )
+    if errors:
+        return GovernanceApplyResult(
+            status="WARNED",
+            applied=applied,
+            failed=len(errors),
+            sql_preview=sql_preview,
+            errors=tuple(errors),
+        )
+    return GovernanceApplyResult(status="SUCCESS", applied=applied, sql_preview=sql_preview)
+
+
+def _access_setting(contract: SemanticContract, key: str, default: str) -> str:
+    access = contract.governance.access if contract.governance else None
+    if not isinstance(access, dict):
+        return default
+    policy = access.get("access_policy", {})
+    if isinstance(policy, dict) and policy.get(key) is not None:
+        return str(policy[key])
+    return str(access.get(key, default))
+
+
+def _revoke_unmanaged(contract: SemanticContract) -> bool:
+    return _access_setting(contract, "revoke_unmanaged", "false").lower() == "true"
+
+
+def _drift(runner: SqlRunner, contract: SemanticContract) -> dict[str, object] | None:
+    current = current_contract_grants(runner, contract)
+    if current is None:
+        return None
+    return access_drift_report(contract, current_grants=current)

contractforge_databricks/governance/drift.py

@@ -0,0 +1,49 @@
+"""Unity Catalog access drift inspection helpers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contractforge_databricks.rendering.names import target_full_name
+from contractforge_databricks.sql import quote_table_name
+
+
+def current_table_grants(runner: Any, target_table: str) -> set[tuple[str, str]] | None:
+    """Return current table grants when the runner exposes a query interface."""
+
+    query = getattr(runner, "query", None)
+    if not callable(query):
+        return None
+    rows = query(f"SHOW GRANTS ON TABLE {quote_table_name(target_table)}")
+    return {_grant_tuple(row) for row in rows if _grant_tuple(row) != (None, None)}  # type: ignore[misc]
+
+
+def current_contract_grants(runner: Any, contract: Any) -> set[tuple[str, str]] | None:
+    return current_table_grants(runner, target_full_name(contract))
+
+
+def _grant_tuple(row: Any) -> tuple[str | None, str | None]:
+    principal = _row_value(row, "Principal", "principal", "grantee")
+    privilege = _row_value(row, "ActionType", "actionType", "Privilege", "privilege")
+    if principal is None or privilege is None:
+        return (None, None)
+    return (str(principal), str(privilege).upper())
+
+
+def _row_value(row: Any, *names: str) -> Any:
+    if isinstance(row, dict):
+        data = row
+    elif hasattr(row, "asDict"):
+        data = row.asDict(recursive=True)
+    else:
+        try:
+            data = dict(row)
+        except Exception:
+            data = {}
+    lower = {str(key).lower(): value for key, value in data.items()}
+    for name in names:
+        if name in data:
+            return data[name]
+        if name.lower() in lower:
+            return lower[name.lower()]
+    return None

contractforge_databricks/governance/runtime.py

@@ -0,0 +1,60 @@
+"""Runtime check/apply facade for Databricks governance contracts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from contractforge_core.results import GovernanceApplyResult
+from contractforge_core.semantic import SemanticContract
+from contractforge_databricks.annotations import annotation_steps, apply_annotations_contract
+from contractforge_databricks.execution.sql_merge import SqlRunner
+from contractforge_databricks.governance.access import access_steps
+from contractforge_databricks.governance.application import apply_access_contract
+
+
+def check_governance_contract(contract: SemanticContract) -> dict[str, Any]:
+    """Return reviewable governance SQL without executing it."""
+
+    annotation_sql = tuple(str(step["sql"]) for step in annotation_steps(contract))
+    access_sql = tuple(str(step["sql"]) for step in access_steps(contract))
+    total = len(annotation_sql) + len(access_sql)
+    return {
+        "status": "VALIDATED" if total else "NOT_CONFIGURED",
+        "annotations": GovernanceApplyResult(status="VALIDATED" if annotation_sql else "NOT_CONFIGURED", validated=len(annotation_sql), sql_preview=annotation_sql),
+        "access": GovernanceApplyResult(status="VALIDATED" if access_sql else "NOT_CONFIGURED", validated=len(access_sql), sql_preview=access_sql),
+        "sql_preview": annotation_sql + access_sql,
+        "validated": total,
+    }
+
+
+def apply_governance_contract(*, runner: SqlRunner, contract: SemanticContract) -> dict[str, Any]:
+    """Apply annotations and access governance using an injected Databricks SQL runner."""
+
+    annotations = apply_annotations_contract(runner=runner, contract=contract)
+    access = apply_access_contract(runner=runner, contract=contract)
+    return {
+        "status": _combined_status(annotations, access),
+        "annotations": annotations,
+        "access": access,
+        "applied": annotations.applied + access.applied,
+        "validated": annotations.validated + access.validated,
+        "ignored": annotations.ignored + access.ignored,
+        "failed": annotations.failed + access.failed,
+        "sql_preview": annotations.sql_preview + access.sql_preview,
+        "errors": annotations.errors + access.errors,
+    }
+
+
+def _combined_status(*results: GovernanceApplyResult) -> str:
+    statuses = {result.status for result in results}
+    if "FAILED" in statuses:
+        return "FAILED"
+    if "WARNED" in statuses:
+        return "WARNED"
+    if "SUCCESS" in statuses:
+        return "SUCCESS"
+    if "VALIDATED" in statuses:
+        return "VALIDATED"
+    if "IGNORED" in statuses:
+        return "IGNORED"
+    return "NOT_CONFIGURED"