contractforge-snowflake 0.1.0__py3-none-any.whl

contractforge_snowflake/__init__.py

@@ -0,0 +1,68 @@
+"""Public API for the ContractForge Snowflake adapter."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from contractforge_snowflake.adapter import SnowflakeAdapter
+from contractforge_snowflake.api import (
+    build_snowflake_publish_bundle,
+    plan_snowflake_contract,
+    render_snowflake_contract,
+)
+from contractforge_snowflake.capabilities import (
+    SNOWFLAKE_SUBTARGET_SNOWPIPE,
+    SNOWFLAKE_SUBTARGET_SQL_WAREHOUSE,
+    SNOWFLAKE_SUBTARGET_STREAMS_TASKS,
+    SNOWFLAKE_SUBTARGET_TASK_GRAPH,
+    snowflake_sql_warehouse_capabilities,
+)
+from contractforge_snowflake.dashboards import render_control_dashboard_artifacts, render_control_dashboard_sql
+from contractforge_snowflake.environment import SnowflakeEnvironment
+from contractforge_snowflake.maintenance import build_control_retention_plan, execute_control_retention_plan
+from contractforge_snowflake.runtime import (
+    SnowflakeAccessHistoryLineageResult,
+    build_snowflake_project_cleanup_plan,
+    deploy_snowflake_project,
+    publish_snowflake_contract,
+    reconcile_snowflake_access_history_lineage,
+    reconcile_snowflake_cost_evidence,
+    run_snowflake_contract,
+    run_snowflake_project,
+    wait_snowflake_project_tasks,
+)
+from contractforge_snowflake.subtargets import list_snowflake_subtargets
+
+try:
+    __version__ = _version("contractforge-snowflake")
+except PackageNotFoundError:  # pragma: no cover - editable/source tree without installed metadata
+    __version__ = "0.1.0"
+
+__all__ = [
+    "SNOWFLAKE_SUBTARGET_SNOWPIPE",
+    "SNOWFLAKE_SUBTARGET_SQL_WAREHOUSE",
+    "SNOWFLAKE_SUBTARGET_STREAMS_TASKS",
+    "SNOWFLAKE_SUBTARGET_TASK_GRAPH",
+    "SnowflakeAdapter",
+    "SnowflakeAccessHistoryLineageResult",
+    "SnowflakeEnvironment",
+    "__version__",
+    "build_snowflake_publish_bundle",
+    "build_control_retention_plan",
+    "build_snowflake_project_cleanup_plan",
+    "deploy_snowflake_project",
+    "execute_control_retention_plan",
+    "list_snowflake_subtargets",
+    "plan_snowflake_contract",
+    "publish_snowflake_contract",
+    "reconcile_snowflake_access_history_lineage",
+    "reconcile_snowflake_cost_evidence",
+    "render_control_dashboard_artifacts",
+    "render_control_dashboard_sql",
+    "render_snowflake_contract",
+    "run_snowflake_contract",
+    "run_snowflake_project",
+    "snowflake_sql_warehouse_capabilities",
+    "wait_snowflake_project_tasks",
+]

contractforge_snowflake/access/__init__.py

@@ -0,0 +1,5 @@
+"""Snowflake access planning and runtime application."""
+
+from contractforge_snowflake.access.runtime import SnowflakeAccessResult, access_steps, apply_snowflake_access
+
+__all__ = ["SnowflakeAccessResult", "access_steps", "apply_snowflake_access"]

contractforge_snowflake/access/runtime.py

@@ -0,0 +1,264 @@
+"""Apply ContractForge access grants to Snowflake objects."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from contractforge_core.security.redaction import redact_text
+from contractforge_core.semantic import SemanticContract
+from contractforge_snowflake.environment import SnowflakeEnvironment
+from contractforge_snowflake.evidence import record_access_evidence
+from contractforge_snowflake.naming import quote_identifier, quote_multipart_identifier, snowflake_target_name
+from contractforge_snowflake.session_ops import execute
+from contractforge_snowflake.values import dict_mapping as _mapping
+from contractforge_snowflake.values import string_list as _as_list
+
+
+@dataclass(frozen=True)
+class SnowflakeAccessStep:
+    action: str
+    access_type: str
+    principal: str | None
+    privilege: str | None
+    column_name: str | None
+    function_name: str | None
+    object_name: str
+    mode: str
+    sql: str | None
+    drift_policy: str = "warn"
+    revoke_unmanaged: bool = False
+    previous_value: str | None = None
+    new_value: str | None = None
+
+
+@dataclass(frozen=True)
+class SnowflakeAccessResult:
+    status: str
+    applied: int
+    skipped: int
+    failed: int
+    commands: tuple[str, ...]
+
+
+def apply_snowflake_access(
+    *,
+    session: Any,
+    environment: SnowflakeEnvironment,
+    contract: SemanticContract,
+    run_id: str,
+) -> SnowflakeAccessResult:
+    steps = access_steps(contract)
+    if not steps:
+        return SnowflakeAccessResult(status="NOOP", applied=0, skipped=0, failed=0, commands=())
+    commands: list[str] = []
+    applied = skipped = failed = 0
+    for step in steps:
+        if step.mode != "apply":
+            skipped += 1
+            evidence = record_access_evidence(
+                session,
+                environment=environment,
+                contract=contract,
+                run_id=run_id,
+                step=step.__dict__,
+                status=_skipped_status(step.mode),
+                error_message=None,
+            )
+            commands.extend(evidence.commands)
+            continue
+        try:
+            if step.sql:
+                execute(session, step.sql)
+        except Exception as exc:
+            failed += 1
+            evidence = record_access_evidence(
+                session,
+                environment=environment,
+                contract=contract,
+                run_id=run_id,
+                step=step.__dict__,
+                status="FAILED",
+                error_message=redact_text(str(exc)),
+            )
+            commands.extend(_with_sql(step.sql, evidence.commands))
+            raise
+        else:
+            applied += 1
+            evidence = record_access_evidence(
+                session,
+                environment=environment,
+                contract=contract,
+                run_id=run_id,
+                step=step.__dict__,
+                status="APPLIED",
+                error_message=None,
+            )
+            commands.extend(_with_sql(step.sql, evidence.commands))
+    return SnowflakeAccessResult(status="SUCCESS" if failed == 0 else "FAILED", applied=applied, skipped=skipped, failed=failed, commands=tuple(commands))
+
+
+def access_steps(contract: SemanticContract) -> tuple[SnowflakeAccessStep, ...]:
+    access = contract.governance.access if contract.governance else None
+    if not isinstance(access, dict):
+        return ()
+    target = snowflake_target_name(contract)
+    grants = _grant_steps(target, access)
+    policies = _policy_steps(target, access)
+    return (*grants, *policies)
+
+
+def _grant_steps(target: str, access: dict[str, Any]) -> tuple[SnowflakeAccessStep, ...]:
+    return tuple(
+        _grant_step(target, principal=str(grant["principal"]), privilege=str(privilege), access=access)
+        for grant in access.get("grants", ())
+        if isinstance(grant, dict)
+        for privilege in _as_list(grant.get("privileges"))
+    )
+
+
+def _grant_step(target: str, *, principal: str, privilege: str, access: dict[str, Any]) -> SnowflakeAccessStep:
+    privilege_name = _privilege_name(privilege)
+    return SnowflakeAccessStep(
+        action="grant",
+        access_type="grant",
+        principal=principal,
+        privilege=privilege_name,
+        column_name=None,
+        function_name=None,
+        object_name=target,
+        mode=_access_mode(access),
+        sql=f"GRANT {privilege_name} ON TABLE {target} TO ROLE {quote_identifier(principal)}",
+        drift_policy=_access_drift_policy(access),
+        revoke_unmanaged=_revoke_unmanaged(access),
+        new_value="GRANTED",
+    )
+
+
+def _policy_steps(target: str, access: dict[str, Any]) -> tuple[SnowflakeAccessStep, ...]:
+    row_filters = tuple(
+        _row_access_policy_step(target, item, access)
+        for item in _iter_list_items(access.get("row_filters"))
+    )
+    masks = tuple(
+        _masking_policy_step(target, item, access)
+        for item in _iter_column_masks(access.get("column_masks"))
+    )
+    return (*row_filters, *masks)
+
+
+def _row_access_policy_step(target: str, row_filter: dict[str, Any], access: dict[str, Any]) -> SnowflakeAccessStep:
+    columns = tuple(_as_list(row_filter.get("columns")))
+    policy = str(row_filter.get("function") or "").strip()
+    if not columns:
+        raise ValueError("Snowflake row access policy requires access.row_filters.columns")
+    if not policy:
+        raise ValueError("Snowflake row access policy requires access.row_filters.function")
+    return SnowflakeAccessStep(
+        action="apply_row_access_policy",
+        access_type="row_filter",
+        principal="|".join(_as_list(_mapping(row_filter.get("applies_to")).get("principals"))),
+        privilege="ROW_ACCESS_POLICY",
+        column_name="|".join(columns),
+        function_name=policy,
+        object_name=target,
+        mode=_access_mode(access),
+        sql=(
+            f"ALTER TABLE {target} ADD ROW ACCESS POLICY {quote_multipart_identifier(policy)} "
+            f"ON ({', '.join(quote_identifier(column) for column in columns)})"
+        ),
+        drift_policy=_access_drift_policy(access),
+        revoke_unmanaged=_revoke_unmanaged(access),
+        new_value=policy,
+    )
+
+
+def _masking_policy_step(target: str, column_mask: dict[str, Any], access: dict[str, Any]) -> SnowflakeAccessStep:
+    column = str(column_mask.get("column") or "").strip()
+    policy = str(column_mask.get("function") or "").strip()
+    using_columns = tuple(_as_list(column_mask.get("using_columns")))
+    if not column:
+        raise ValueError("Snowflake masking policy requires access.column_masks.column")
+    if not policy:
+        raise ValueError("Snowflake masking policy requires access.column_masks.function")
+    using_sql = ""
+    if using_columns:
+        using = (column, *tuple(item for item in using_columns if item != column))
+        using_sql = " USING (" + ", ".join(quote_identifier(item) for item in using) + ")"
+    return SnowflakeAccessStep(
+        action="apply_masking_policy",
+        access_type="column_mask",
+        principal="|".join(_as_list(_mapping(column_mask.get("applies_to")).get("principals"))),
+        privilege="MASKING_POLICY",
+        column_name=column,
+        function_name=policy,
+        object_name=target,
+        mode=_access_mode(access),
+        sql=(
+            f"ALTER TABLE {target} MODIFY COLUMN {quote_identifier(column)} "
+            f"SET MASKING POLICY {quote_multipart_identifier(policy)}{using_sql}"
+        ),
+        drift_policy=_access_drift_policy(access),
+        revoke_unmanaged=_revoke_unmanaged(access),
+        new_value=policy,
+    )
+
+
+def _access_mode(access: dict[str, Any]) -> str:
+    policy = _mapping(access.get("access_policy"))
+    return str(policy.get("mode") or access.get("mode") or "apply")
+
+
+def _access_drift_policy(access: dict[str, Any]) -> str:
+    policy = _mapping(access.get("access_policy"))
+    return str(policy.get("on_drift") or access.get("on_drift") or "warn")
+
+
+def _revoke_unmanaged(access: dict[str, Any]) -> bool:
+    policy = _mapping(access.get("access_policy"))
+    return bool(policy.get("revoke_unmanaged", access.get("revoke_unmanaged", False)))
+
+
+def _privilege_name(value: str) -> str:
+    privilege = str(value).strip().replace("_", " ").upper()
+    allowed = {
+        "ALL PRIVILEGES",
+        "APPLYBUDGET",
+        "DELETE",
+        "EVOLVE SCHEMA",
+        "INSERT",
+        "REFERENCES",
+        "SELECT",
+        "TRUNCATE",
+        "UPDATE",
+    }
+    if privilege not in allowed:
+        raise ValueError(f"Unsupported Snowflake table privilege: {value!r}")
+    return privilege
+
+
+def _skipped_status(mode: str) -> str:
+    return "IGNORED" if mode == "ignore" else "VALIDATED"
+
+
+def _iter_list_items(value: object) -> tuple[dict[str, Any], ...]:
+    if value is None:
+        return ()
+    if isinstance(value, dict):
+        return tuple(dict(item) for item in value.values() if isinstance(item, dict))
+    return tuple(dict(item) for item in value if isinstance(item, dict))  # type: ignore[union-attr]
+
+
+def _iter_column_masks(value: object) -> tuple[dict[str, Any], ...]:
+    if value is None:
+        return ()
+    if isinstance(value, dict):
+        return tuple({**dict(config), "column": column} for column, config in value.items() if isinstance(config, dict))
+    return tuple(dict(item) for item in value if isinstance(item, dict))  # type: ignore[union-attr]
+
+
+def _with_sql(sql: str | None, commands: tuple[str, ...]) -> tuple[str, ...]:
+    return ((sql,) if sql else ()) + commands
+
+
+__all__ = ["SnowflakeAccessResult", "access_steps", "apply_snowflake_access"]

contractforge_snowflake/adapter.py

@@ -0,0 +1,78 @@
+"""ContractForge adapter implementation for Snowflake targets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from contractforge_core.adapters import RenderedArtifacts
+from contractforge_core.capabilities import PlatformCapabilities
+from contractforge_core.planner import ExecutionPlan, PlanningResult, plan_contract
+from contractforge_core.semantic import SemanticContract
+from contractforge_snowflake.capabilities import (
+    SNOWFLAKE_SUBTARGET_SQL_WAREHOUSE,
+    snowflake_sql_warehouse_capabilities,
+)
+from contractforge_snowflake.diagnostics import (
+    snowflake_planning_warnings,
+    snowflake_review_required_warnings,
+    unsupported_source_blockers,
+)
+from contractforge_snowflake.environment import SnowflakeEnvironment
+from contractforge_snowflake.rendering import render_snowflake_review_artifacts
+
+
+@dataclass(frozen=True)
+class SnowflakeAdapter:
+    """Snowflake adapter for planning and publish-bundle preparation."""
+
+    declared_capabilities: PlatformCapabilities
+    environment: SnowflakeEnvironment = SnowflakeEnvironment()
+    name: str = SNOWFLAKE_SUBTARGET_SQL_WAREHOUSE
+
+    @classmethod
+    def sql_warehouse(cls, environment: dict[str, Any] | None = None) -> "SnowflakeAdapter":
+        return cls(
+            snowflake_sql_warehouse_capabilities(),
+            environment=SnowflakeEnvironment.from_contract(environment),
+        )
+
+    def capabilities(self) -> PlatformCapabilities:
+        return self.declared_capabilities
+
+    def plan(self, contract: SemanticContract) -> PlanningResult:
+        source_blockers = unsupported_source_blockers(contract)
+        if source_blockers:
+            return PlanningResult(status="UNSUPPORTED", plan=None, blockers=source_blockers)
+
+        result = plan_contract(contract, self.capabilities())
+        warnings = result.warnings + snowflake_planning_warnings(contract)
+        review_warnings = snowflake_review_required_warnings(contract)
+        if review_warnings and result.status in {"SUPPORTED", "SUPPORTED_WITH_WARNINGS"}:
+            return PlanningResult(
+                status="REVIEW_REQUIRED",
+                plan=result.plan,
+                blockers=result.blockers,
+                warnings=warnings + review_warnings,
+            )
+        if warnings and result.status == "SUPPORTED":
+            return PlanningResult(status="SUPPORTED_WITH_WARNINGS", plan=result.plan, warnings=warnings)
+        return PlanningResult(
+            status=result.status,
+            plan=result.plan,
+            blockers=result.blockers,
+            warnings=warnings + review_warnings,
+        )
+
+    def render(self, plan: ExecutionPlan) -> RenderedArtifacts:
+        return render_snowflake_review_artifacts(plan=plan, planning=None, environment=self.environment)
+
+    def render_contract(self, contract: SemanticContract, *, raw_contract: dict[str, Any] | None = None) -> RenderedArtifacts:
+        planning = self.plan(contract)
+        return render_snowflake_review_artifacts(
+            plan=planning.plan,
+            planning=planning,
+            contract=contract,
+            raw_contract=raw_contract,
+            environment=self.environment,
+        )

contractforge_snowflake/annotations/__init__.py

@@ -0,0 +1,9 @@
+"""Snowflake annotation planning and runtime application."""
+
+from contractforge_snowflake.annotations.runtime import (
+    SnowflakeAnnotationResult,
+    annotation_steps,
+    apply_snowflake_annotations,
+)
+
+__all__ = ["SnowflakeAnnotationResult", "annotation_steps", "apply_snowflake_annotations"]

contractforge_snowflake/annotations/runtime.py

@@ -0,0 +1,258 @@
+"""Apply ContractForge annotations to Snowflake objects."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from contractforge_core.security.redaction import redact_text
+from contractforge_core.semantic import SemanticContract
+from contractforge_snowflake.contract_extensions import snowflake_extensions
+from contractforge_snowflake.environment import SnowflakeEnvironment
+from contractforge_snowflake.evidence import record_annotation_evidence
+from contractforge_snowflake.naming import quote_identifier, quote_multipart_identifier, snowflake_target_name
+from contractforge_snowflake.session_ops import execute
+from contractforge_snowflake.sql import sql_string
+from contractforge_snowflake.values import dict_mapping as _mapping
+from contractforge_snowflake.values import pipe_string_list as _as_list
+
+
+@dataclass(frozen=True)
+class SnowflakeAnnotationStep:
+    scope: str
+    annotation_type: str
+    column_name: str | None
+    key: str
+    value: str
+    sql: str
+
+
+@dataclass(frozen=True)
+class SnowflakeAnnotationResult:
+    status: str
+    applied: int
+    failed: int
+    commands: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class _TagExtractor:
+    prefix: str
+    extract: Callable[[dict[str, Any]], dict[str, str]]
+
+
+def apply_snowflake_annotations(
+    *,
+    session: Any,
+    environment: SnowflakeEnvironment,
+    contract: SemanticContract,
+    run_id: str,
+) -> SnowflakeAnnotationResult:
+    """Apply annotations and record canonical annotation evidence."""
+
+    steps = annotation_steps(contract)
+    if not steps:
+        return SnowflakeAnnotationResult(status="NOOP", applied=0, failed=0, commands=())
+    policy = _annotation_policy(contract)
+    if policy == "ignore":
+        return SnowflakeAnnotationResult(status="IGNORED", applied=0, failed=0, commands=())
+    tag_mode = _tag_mode(contract)
+    commands: list[str] = []
+    applied = 0
+    failed = 0
+    for step in steps:
+        if step.annotation_type == "tag" and tag_mode == "validate_only":
+            evidence = record_annotation_evidence(
+                session,
+                environment=environment,
+                contract=contract,
+                run_id=run_id,
+                step=step.__dict__,
+                status="VALIDATED",
+                error_message=None,
+            )
+            applied += 1
+            commands.extend(evidence.commands)
+            continue
+        try:
+            execute(session, step.sql)
+        except Exception as exc:
+            failed += 1
+            evidence = record_annotation_evidence(
+                session,
+                environment=environment,
+                contract=contract,
+                run_id=run_id,
+                step=step.__dict__,
+                status="FAILED",
+                error_message=redact_text(str(exc)),
+            )
+            commands.extend((step.sql, *evidence.commands))
+            if policy == "fail":
+                raise
+        else:
+            applied += 1
+            evidence = record_annotation_evidence(
+                session,
+                environment=environment,
+                contract=contract,
+                run_id=run_id,
+                step=step.__dict__,
+                status="APPLIED",
+                error_message=None,
+            )
+            commands.extend((step.sql, *evidence.commands))
+    status = "SUCCESS" if failed == 0 else "WARNED"
+    return SnowflakeAnnotationResult(status=status, applied=applied, failed=failed, commands=tuple(commands))
+
+
+def annotation_steps(contract: SemanticContract) -> tuple[SnowflakeAnnotationStep, ...]:
+    annotations = contract.governance.annotations if contract.governance else None
+    if not isinstance(annotations, dict):
+        return ()
+    target = snowflake_target_name(contract)
+    steps: list[SnowflakeAnnotationStep] = []
+    table = _mapping(annotations.get("table"))
+    description = table.get("description")
+    if description:
+        steps.append(_step("table", "description", None, "description", str(description), f"COMMENT ON TABLE {target} IS {sql_string(description)}"))
+    steps.extend(_tag_steps(target=target, column=None, tags=_table_tags(table)))
+    for column, config in _mapping(annotations.get("columns")).items():
+        steps.extend(_column_steps(target=target, column=str(column), config=_mapping(config)))
+    return tuple(steps)
+
+
+def _column_steps(*, target: str, column: str, config: dict[str, Any]) -> tuple[SnowflakeAnnotationStep, ...]:
+    steps: list[SnowflakeAnnotationStep] = []
+    description = config.get("description")
+    if description:
+        quoted_column = _qualified_column(target, column)
+        steps.append(
+            _step(
+                "column",
+                "description",
+                column,
+                "description",
+                str(description),
+                f"COMMENT ON COLUMN {quoted_column} IS {sql_string(description)}",
+            )
+        )
+    steps.extend(_tag_steps(target=target, column=column, tags=_column_tags(config)))
+    return tuple(steps)
+
+
+def _tag_steps(*, target: str, column: str | None, tags: dict[str, str]) -> tuple[SnowflakeAnnotationStep, ...]:
+    builder = _column_tag_sql if column else _table_tag_sql
+    scope = "column" if column else "table"
+    return tuple(
+        _step(scope, "tag", column, key, value, builder(target, column, key, value))
+        for key, value in tags.items()
+    )
+
+
+def _table_tag_sql(target: str, _column: str | None, key: str, value: str) -> str:
+    return f"ALTER TABLE {target} SET TAG {_tag_name(key)} = {sql_string(value)}"
+
+
+def _column_tag_sql(target: str, column: str | None, key: str, value: str) -> str:
+    if column is None:
+        raise ValueError("column tag SQL requires a column")
+    return f"ALTER TABLE {target} ALTER COLUMN {quote_identifier(column)} SET TAG {_tag_name(key)} = {sql_string(value)}"
+
+
+def _step(scope: str, annotation_type: str, column: str | None, key: str, value: str, sql: str) -> SnowflakeAnnotationStep:
+    return SnowflakeAnnotationStep(
+        scope=scope,
+        annotation_type=annotation_type,
+        column_name=column,
+        key=key,
+        value=value,
+        sql=sql,
+    )
+
+
+def _qualified_column(target: str, column: str) -> str:
+    return f"{target}.{quote_identifier(column)}"
+
+
+def _annotation_policy(contract: SemanticContract) -> str:
+    annotations = contract.governance.annotations if contract.governance else None
+    value = annotations.get("policy") if isinstance(annotations, dict) else None
+    return str(value or "warn").lower()
+
+
+def _tag_mode(contract: SemanticContract) -> str:
+    annotations = contract.governance.annotations if contract.governance else None
+    snowflake = snowflake_extensions(contract)
+    value = snowflake.get("annotation_tag_mode") or snowflake.get("tag_mode")
+    if value is not None:
+        return str(value).lower()
+    if not isinstance(annotations, dict):
+        return "apply"
+    return str(annotations.get("tags_mode") or "apply").lower()
+
+
+def _tag_name(key: str) -> str:
+    return quote_multipart_identifier(key) if "." in key else quote_identifier(key)
+
+
+def _table_tags(table: dict[str, Any]) -> dict[str, str]:
+    return _tags(table, _TABLE_TAG_EXTRACTORS)
+
+
+def _column_tags(config: dict[str, Any]) -> dict[str, str]:
+    return _tags(config, _COLUMN_TAG_EXTRACTORS)
+
+
+def _tags(data: dict[str, Any], extractors: tuple[_TagExtractor, ...]) -> dict[str, str]:
+    tags: dict[str, str] = {}
+    for extractor in extractors:
+        tags.update({f"{extractor.prefix}{key}": value for key, value in extractor.extract(data).items()})
+    return tags
+
+
+def _str_map(value: object) -> dict[str, str]:
+    return {str(key): _tag_value(item) for key, item in _mapping(value).items()}
+
+
+def _indexed_tags(value: object) -> dict[str, str]:
+    return {str(idx): item for idx, item in enumerate(_as_list(value), start=1)}
+
+
+def _deprecated_tags(value: object) -> dict[str, str]:
+    deprecated = _mapping(value)
+    if not deprecated:
+        return {}
+    payload = {"enabled": "true"}
+    payload.update({key: str(deprecated[key]) for key in ("since", "replacement", "removal_date") if deprecated.get(key)})
+    return payload
+
+
+def _pii_tags(value: object) -> dict[str, str]:
+    pii = _mapping(value)
+    if not pii:
+        return {}
+    return {
+        "enabled": _tag_value(pii.get("enabled", True)),
+        "type": str(pii.get("type", "unknown")),
+        "sensitivity": str(pii.get("sensitivity", "internal")),
+    }
+
+
+def _tag_value(value: object) -> str:
+    return str(value).lower() if isinstance(value, bool) else str(value)
+
+
+_TABLE_TAG_EXTRACTORS: tuple[_TagExtractor, ...] = (
+    _TagExtractor("", lambda data: _str_map(data.get("tags"))),
+    _TagExtractor("alias_", lambda data: _indexed_tags(data.get("aliases"))),
+    _TagExtractor("deprecated_", lambda data: _deprecated_tags(data.get("deprecated"))),
+)
+_COLUMN_TAG_EXTRACTORS: tuple[_TagExtractor, ...] = (
+    *_TABLE_TAG_EXTRACTORS,
+    _TagExtractor("pii_", lambda data: _pii_tags(data.get("pii"))),
+)
+
+
+__all__ = ["SnowflakeAnnotationResult", "annotation_steps", "apply_snowflake_annotations"]