kiri-cli 1.0.0b3__py3-none-any.whl

kiri_adapters/backends/databricks.py

@@ -0,0 +1,2980 @@
+"""Databricks adapter.
+
+Talks to Databricks via the Workspace SDK + Statement Execution API.
+
+Two ingestion modes, matching the table's metadata:
+
+- **fixture_file** — legacy demo path. A single CSV per table is uploaded to a
+  Unity Catalog volume and appended via ``COPY INTO``.
+- **landing_zone** — the production path (ADR 0008 + 0009 + 0046). Files
+  reach the landing storage primitive (ADLS in production, LocalLandingStorage
+  in dev/tests). Per file we ``move_to_raw`` (atomic on HNS-enabled ADLS)
+  and run a native SQL ``MERGE`` with ``_kiri_*`` columns injected by a
+  SELECT wrapper. The warehouse reads bytes directly from the storage URL
+  (``read_files('abfss://...')``) — no pod-mediated upload step.
+
+Required environment / profile (landing_zone):
+- ``DATABRICKS_HOST`` (profile ``host`` overrides)
+- ``DATABRICKS_TOKEN``
+- ``DATABRICKS_WAREHOUSE_ID`` or profile ``warehouse_id``
+- profile ``catalog`` (default: ``main``)
+- profile ``ingest_volume`` (default: ``main.ops.ingest`` — used by
+  fixture mode only)
+- profile ``landing_storage`` block (ADR 0046 phase 2) — points at ADLS in
+  production. When omitted, the adapter falls back to
+  :class:`LocalLandingStorage` for development; warehouse-side read of
+  ``file://`` URLs requires a colocated runtime, so production deploys
+  must configure the block.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import time
+import uuid
+from contextlib import suppress
+from dataclasses import dataclass
+from datetime import UTC, date, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from kiri_core.ai_query_gate.audit import _redact_preview
+from kiri_core.schema import IngestionMode, Source
+from kiri_core.trace import current_trace
+from kiri_core.types import HealthStatus, RunStatus
+
+from kiri_adapters.base import (
+    ApplyLogEntry,
+    AssetWatermark,
+    ColumnDescription,
+    Credential,
+    IngestionPlan,
+    LiveColumnAnnotation,
+    LiveTableAnnotations,
+    NamingLockError,
+    PlatformAdapter,
+    ProjectManifest,
+    ProjectTargetCollisionError,
+    QueryResult,
+    ReleaseManifestEntry,
+    RetentionAction,
+    RetentionReport,
+    RunResult,
+    StorageResolution,
+    TableDescription,
+    TableRef,
+    WatermarkStoreError,
+)
+from kiri_adapters.sql_dialect import DeltaDialect, SqlDialect
+
+if TYPE_CHECKING:  # pragma: no cover — type-only to avoid import cost at runtime
+    from kiri_odcs.kiri_ext import StorageBinding
+
+_logger = logging.getLogger(__name__)
+
+DEFAULT_CATALOG = "main"
+DEFAULT_INGEST_VOLUME = "main.ops.ingest"
+
+# ADR 0014 / 0017: reserved schema + tables for governance metadata.
+# Live under the project's Unity Catalog, keeping all kiri.* state
+# under one ACL boundary.
+_META_SCHEMA = "_kiri_meta"
+_MANIFEST_TABLE = "_kiri_project_manifest"
+_APPLY_LOG_TABLE = "_kiri_apply_log"
+# ADR 0041: release-manifest mirror — three tables alongside the apply log.
+_RELEASE_STATE_TABLE = "_kiri_release_state"
+_ACTIVE_CONTRACT_VERSIONS_TABLE = "_kiri_active_contract_versions"
+_PROMOTION_HISTORY_TABLE = "_kiri_promotion_history"
+# ADR 0080: asset-level watermark store — one row per (asset_urn, target_env).
+_ASSET_WATERMARKS_TABLE = "_kiri_asset_watermarks"
+
+_TRUTHY_AUDIT = {"1", "on", "true"}
+_FALSY_AUDIT = {"0", "off", "false"}
+_TRACE_COMMENT_PREFIX = "/* kiri_trace_id="
+_SQL_TOKEN_RE = re.compile(
+    r"`(?:``|[^`])+`|\"(?:\"\"|[^\"])+\"|'(?:''|[^'])+'|[A-Za-z_][\w$]*|[.,();]"
+)
+_WITH_TOP_LEVEL_VERBS = {"SELECT", "INSERT", "UPDATE", "DELETE", "MERGE", "CREATE"}
+_AUDIT_DISABLED_DESTINATIONS: set[tuple[str, str]] = set()
+_McpAuditStatus = Literal["OK", "FAILED", "DENIED", "success", "failed"]
+
+
+@dataclass(frozen=True)
+class _AuditPaths:
+    jsonl: Path
+    line: Path
+
+
+@dataclass(frozen=True)
+class _AuditRecord:
+    ts: str
+    trace_id: str
+    apply_id: str | None
+    caller: str
+    via: str
+    user: str
+    event: str
+    target: str
+    duration_ms: int
+    attempts: int
+    status: str
+    warehouse_id: object
+    statement_preview: str
+    error_class: str | None = None
+    reason: str | None = None
+
+
+# ---- pure SQL builders (tested in isolation) ------------------------------
+
+
+def _quote_ident(name: str) -> str:
+    """Databricks backtick-quoting."""
+    return "`" + name.replace("`", "``") + "`"
+
+
+def _fq(catalog: str, schema: str, table: str) -> str:
+    return f"{_quote_ident(catalog)}.{_quote_ident(schema)}.{_quote_ident(table)}"
+
+
+def _is_table_or_schema_not_found(exc: BaseException) -> bool:
+    """True when ``exc`` reports a missing table/view/schema (not a real fault).
+
+    Databricks/Spark surface absence through the SQL error message rather than a
+    distinct exception type, so we match the stable error-class tokens
+    (``TABLE_OR_VIEW_NOT_FOUND`` / ``SCHEMA_NOT_FOUND`` and the
+    ``... does not exist`` / ``cannot be found`` phrasings). Used by
+    :meth:`read_watermark` to map only genuine absence to ``None`` while every
+    other failure raises :class:`WatermarkStoreError` (ADR 0080 §2 — a real read
+    error must never look like an empty cursor).
+
+    Delegates to the cross-dialect :func:`kiri_adapters.base.is_relation_absent_error`
+    so the not-found token logic lives in ONE place (shared with the DV freeze
+    fail-closed path, ADR 0080 §4); the Databricks-specific narrowing is the
+    same set of stable Spark error-class tokens.
+    """
+    from kiri_adapters.base import is_relation_absent_error
+
+    return is_relation_absent_error(exc)
+
+
+def _sql_str_lit(value: str) -> str:
+    """Single-quote a SQL string literal, escaping embedded quotes."""
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _render_describe_external_location(name: str) -> str:
+    """ADR 0132 §3 read primitive: ``DESCRIBE EXTERNAL LOCATION `<name>` ``.
+
+    Resolves the location NAME → its ``url`` + ``credential_name`` (and owner).
+    """
+    return f"DESCRIBE EXTERNAL LOCATION {_quote_ident(name)}"
+
+
+def _render_create_external_location(name: str, url: str, credential: str) -> str:
+    """ADR 0132 §3 provision DDL: idempotent ``CREATE EXTERNAL LOCATION``.
+
+    UC requires ``WITH (STORAGE CREDENTIAL <name>)``; the credential name is
+    backtick-quoted, the url single-quote-escaped.
+    """
+    return (
+        f"CREATE EXTERNAL LOCATION IF NOT EXISTS {_quote_ident(name)} "
+        f"URL {_sql_str_lit(url)} "
+        f"WITH (STORAGE CREDENTIAL {_quote_ident(credential)})"
+    )
+
+
+def _render_create_schema_managed_location(catalog: str, schema: str, location: str) -> str:
+    """ADR 0132 §3 provision DDL: idempotent per-schema ``MANAGED LOCATION``."""
+    return (
+        f"CREATE SCHEMA IF NOT EXISTS "
+        f"{_quote_ident(catalog)}.{_quote_ident(schema)} "
+        f"MANAGED LOCATION {_sql_str_lit(location)}"
+    )
+
+
+# Issue #366 — ADR 0124 renamed meta columns ``_dca_*`` → ``_kiri_*``.
+# A target table created by a pre-rename build still carries the old
+# names; the rewritten ``build_merge_sql`` emits ``_kiri_*`` and
+# ``WHEN MATCHED THEN UPDATE SET *`` expands against the target's
+# columns, so the MERGE fails with ``DELTA_MERGE_UNRESOLVED_EXPRESSION``
+# and the per-file loop swallows it as "0 rows" → silver/gold cascade
+# empty. We detect this state before MERGE and refuse to proceed.
+_STALE_META_PREFIX = "_dca_"
+
+
+class StaleSchemaError(RuntimeError):
+    """Target table predates the ADR 0124 meta-column rename.
+
+    Auto-migration via ``ALTER TABLE ... RENAME COLUMN`` was rejected:
+    Delta rewrites the file footprint on rename and the operation is
+    not rollback-safe. Pre-1.0 the breaking-change rename had no
+    upgrade script by design (see ADR 0124); this error surfaces the
+    one-time mismatch with an actionable hint instead of letting it
+    cascade through silver and gold as empty rows.
+    """
+
+    def __init__(self, target_fq: str, stale_columns: list[str]) -> None:
+        self.target_fq = target_fq
+        self.stale_columns = list(stale_columns)
+        rename_hints = "; ".join(
+            f"ALTER TABLE {target_fq} RENAME COLUMN {col} TO "
+            f"{col.replace(_STALE_META_PREFIX, '_kiri_', 1)}"
+            for col in stale_columns
+        )
+        super().__init__(
+            f"Target {target_fq} has pre-ADR-0124 meta columns "
+            f"({', '.join(stale_columns)}). ADR 0124 renamed _dca_* → "
+            f"_kiri_*; the MERGE cannot reconcile. Drop and recreate "
+            f"the table (DROP TABLE {target_fq}) before re-running "
+            f"apply, or rename the columns explicitly: "
+            f"{rename_hints}."
+        )
+
+
+def _stale_meta_columns_from_describe(
+    describe_rows: list[tuple[Any, ...]] | None,
+) -> list[str]:
+    """Return pre-rename ``_dca_*`` column names from ``DESCRIBE TABLE`` output.
+
+    Databricks' ``DESCRIBE TABLE`` returns ``(col_name, data_type,
+    comment)`` rows for each column, then a delimiter (empty
+    ``col_name``) and a ``# Detailed Table Information`` section.
+    Stop at the delimiter — only column rows precede.
+    """
+    if not describe_rows:
+        return []
+    stale: list[str] = []
+    for row in describe_rows:
+        if not row:
+            continue
+        col_name = str(row[0])
+        # Delimiter row (blank) or section header ("# Detailed Table
+        # Information", "# Partition Information", …) marks end of
+        # the column list.
+        if not col_name.strip() or col_name.startswith("#"):
+            break
+        if col_name.startswith(_STALE_META_PREFIX):
+            stale.append(col_name)
+    return stale
+
+
+def _strip_leading_trace_comment(sql: str) -> str:
+    body = sql.strip()
+    if body.startswith(_TRACE_COMMENT_PREFIX):
+        end = body.find("*/")
+        if end != -1:
+            return body[end + 2 :].strip()
+    return body
+
+
+def _normalise_identifier(token: str) -> str:
+    token = token.rstrip(",;")
+    if len(token) >= 2 and token[0] == "`" and token[-1] == "`":
+        return token[1:-1].replace("``", "`")
+    if len(token) >= 2 and token[0] == '"' and token[-1] == '"':
+        return token[1:-1].replace('""', '"')
+    return token
+
+
+def _sql_tokens(sql: str) -> list[str]:
+    return [m.group(0) for m in _SQL_TOKEN_RE.finditer(_strip_leading_trace_comment(sql))]
+
+
+def _keyword(token: str) -> str:
+    if token.startswith(("`", '"', "'")):
+        return ""
+    return token.upper()
+
+
+def _read_identifier(tokens: list[str], start: int) -> str:
+    parts: list[str] = []
+    i = start
+    while i < len(tokens):
+        tok = tokens[i]
+        if tok == ".":
+            i += 1
+            continue
+        if tok in {"(", ")", ",", ";"}:
+            break
+        if _keyword(tok) in {
+            "AS",
+            "USING",
+            "WHERE",
+            "SET",
+            "VALUES",
+            "SELECT",
+            "COMMENT",
+            "LOCATION",
+            "PARTITIONED",
+            "TBLPROPERTIES",
+            "WITH",
+            "FROM",
+            "TO",
+            "ON",
+        }:
+            break
+        if tok.startswith("'"):
+            break
+        parts.append(_normalise_identifier(tok))
+        if i + 1 >= len(tokens) or tokens[i + 1] != ".":
+            break
+        i += 2
+    return ".".join(p for p in parts if p) or "?"
+
+
+def _skip_if_not_exists(words: list[str], start: int) -> int:
+    if words[start : start + 3] == ["IF", "NOT", "EXISTS"]:
+        return start + 3
+    return start
+
+
+def _skip_optional_table(words: list[str], start: int) -> int:
+    if start < len(words) and words[start] == "TABLE":
+        return start + 1
+    return start
+
+
+def _cte_key(name: str) -> str:
+    return _normalise_identifier(name).lower()
+
+
+def _with_ctes_and_top_level_verb(tokens: list[str]) -> tuple[dict[str, list[str]], int | None]:
+    ctes: dict[str, list[str]] = {}
+    i = 1
+    if i < len(tokens) and _keyword(tokens[i]) == "RECURSIVE":
+        i += 1
+    while i < len(tokens):
+        name = tokens[i]
+        if name in {"(", ")", ",", ";"} or _keyword(name) in _WITH_TOP_LEVEL_VERBS | {"AS"}:
+            break
+        cte_name = _cte_key(name)
+        i += 1
+
+        if i < len(tokens) and tokens[i] == "(":
+            depth = 1
+            i += 1
+            while i < len(tokens) and depth > 0:
+                if tokens[i] == "(":
+                    depth += 1
+                elif tokens[i] == ")":
+                    depth -= 1
+                i += 1
+
+        if i >= len(tokens) or _keyword(tokens[i]) != "AS":
+            break
+        i += 1
+        if i >= len(tokens) or tokens[i] != "(":
+            break
+        body_start = i + 1
+        depth = 1
+        i += 1
+        while i < len(tokens) and depth > 0:
+            if tokens[i] == "(":
+                depth += 1
+            elif tokens[i] == ")":
+                depth -= 1
+            i += 1
+        if depth != 0:
+            return ctes, None
+        ctes[cte_name] = tokens[body_start : i - 1]
+
+        if i < len(tokens) and tokens[i] == ",":
+            i += 1
+            continue
+        break
+
+    for j in range(i, len(tokens)):
+        if _keyword(tokens[j]) in _WITH_TOP_LEVEL_VERBS:
+            return ctes, j
+    return ctes, None
+
+
+def _audit_event_from_tokens(tokens: list[str], start: int) -> str:
+    words = [_keyword(t) for t in tokens]
+    if start >= len(words) or not words[start]:
+        return "OTHER"
+    first = words[start]
+    if first == "CREATE":
+        i = start + 1
+        while i < len(words) and words[i] in {
+            "OR",
+            "REPLACE",
+            "TEMP",
+            "TEMPORARY",
+            "EXTERNAL",
+            "LIVE",
+            "STREAMING",
+        }:
+            i += 1
+        if i < len(words) and words[i] in {"CATALOG", "SCHEMA", "DATABASE", "TABLE", "VIEW"}:
+            kind = "SCHEMA" if words[i] == "DATABASE" else words[i]
+            return f"CREATE_{kind}"
+        return "CREATE"
+    if first in {"DROP", "ALTER"} and start + 1 < len(words):
+        kind = "SCHEMA" if words[start + 1] == "DATABASE" else words[start + 1]
+        if kind in {"CATALOG", "SCHEMA", "TABLE", "VIEW"}:
+            return f"{first}_{kind}"
+    if first == "DESCRIBE":
+        return "DESCRIBE"
+    if first in {
+        "INSERT",
+        "MERGE",
+        "UPDATE",
+        "DELETE",
+        "SELECT",
+        "SHOW",
+        "GRANT",
+        "REVOKE",
+        "OPTIMIZE",
+        "VACUUM",
+        "TRUNCATE",
+        "REFRESH",
+    }:
+        return first
+    return "OTHER"
+
+
+def databricks_audit_event(sql: str) -> str:
+    """Derive ADR 0092 event name from a Databricks SQL statement."""
+    tokens = _sql_tokens(sql)
+    if not tokens:
+        return "OTHER"
+    if _keyword(tokens[0]) == "WITH":
+        _, start = _with_ctes_and_top_level_verb(tokens)
+        return "OTHER" if start is None else _audit_event_from_tokens(tokens, start)
+    return _audit_event_from_tokens(tokens, 0)
+
+
+def _audit_target_from_tokens(tokens: list[str], start: int) -> str:
+    words = [_keyword(t) for t in tokens]
+    if start >= len(words):
+        return "?"
+    first = words[start]
+    if first == "CREATE":
+        i = start + 1
+        while i < len(words) and words[i] in {
+            "OR",
+            "REPLACE",
+            "TEMP",
+            "TEMPORARY",
+            "EXTERNAL",
+            "LIVE",
+            "STREAMING",
+        }:
+            i += 1
+        if i < len(words) and words[i] in {"CATALOG", "SCHEMA", "DATABASE", "TABLE", "VIEW"}:
+            return _read_identifier(tokens, _skip_if_not_exists(words, i + 1))
+    if first in {"DROP", "ALTER"} and start + 2 < len(tokens):
+        return _read_identifier(tokens, start + 2)
+    if first == "INSERT":
+        for i in range(start + 1, len(words)):
+            word = words[i]
+            if word in {"INTO", "OVERWRITE"}:
+                return _read_identifier(tokens, _skip_optional_table(words, i + 1))
+    if first == "MERGE" and start + 1 < len(words) and words[start + 1] == "INTO":
+        return _read_identifier(tokens, start + 2)
+    if first == "UPDATE":
+        return _read_identifier(tokens, start + 1)
+    if first == "DELETE":
+        target_start = (
+            start + 2 if start + 1 < len(words) and words[start + 1] == "FROM" else start + 1
+        )
+        return _read_identifier(tokens, target_start)
+    if first in {"DESCRIBE", "TRUNCATE", "REFRESH"}:
+        target_start = (
+            start + 2
+            if start + 1 < len(words)
+            and words[start + 1] in {"TABLE", "VIEW", "EXTENDED", "FORMATTED"}
+            else start + 1
+        )
+        return _read_identifier(tokens, target_start)
+    if first == "SELECT":
+        depth = 0
+        for i in range(start + 1, len(words)):
+            tok = tokens[i]
+            if tok == "(":
+                depth += 1
+                continue
+            if tok == ")":
+                depth = max(0, depth - 1)
+                continue
+            word = words[i]
+            if word == "FROM":
+                if depth > 0:
+                    continue
+                return _read_identifier(tokens, i + 1)
+    if first == "GRANT":
+        for i in range(start + 1, len(words)):
+            word = words[i]
+            if word == "ON":
+                start = i + 2 if i + 2 < len(tokens) else i + 1
+                return _read_identifier(tokens, start)
+    if first == "SHOW":
+        if "IN" in words[start + 1 :]:
+            return _read_identifier(tokens, words.index("IN", start + 1) + 1)
+        if "FROM" in words[start + 1 :]:
+            return _read_identifier(tokens, words.index("FROM", start + 1) + 1)
+    return "?"
+
+
+def _resolve_cte_audit_target(
+    target: str,
+    ctes: dict[str, list[str]],
+    *,
+    via_cte: bool = False,
+    seen: set[str] | None = None,
+) -> str:
+    if target == "?":
+        return "?"
+    seen = set() if seen is None else seen
+    current = target
+    for _ in range(len(ctes)):
+        key = _cte_key(current)
+        if key in seen:
+            return "?"
+        body = ctes.get(key)
+        if body is None:
+            return current if not via_cte or "." in current else "?"
+        seen.add(key)
+        if body and _keyword(body[0]) == "WITH":
+            nested_ctes, start = _with_ctes_and_top_level_verb(body)
+            if start is None:
+                return "?"
+            nested_target = _audit_target_from_tokens(body, start)
+            resolved_nested = _resolve_cte_audit_target(
+                nested_target,
+                nested_ctes,
+                via_cte=True,
+            )
+            current = resolved_nested
+        else:
+            current = _audit_target_from_tokens(body, 0)
+        if current == "?":
+            return "?"
+    return current if "." in current else "?"
+
+
+def databricks_audit_target(sql: str) -> str:
+    """Best-effort target object extraction for the ADR 0092 one-liner."""
+
+    tokens = _sql_tokens(sql)
+    if not tokens:
+        return "?"
+    if _keyword(tokens[0]) == "WITH":
+        ctes, start = _with_ctes_and_top_level_verb(tokens)
+        if start is None:
+            return "?"
+        return _resolve_cte_audit_target(_audit_target_from_tokens(tokens, start), ctes)
+    return _audit_target_from_tokens(tokens, 0)
+
+
+def databricks_audit_enabled(profile: dict[str, Any]) -> tuple[bool, str | None]:
+    """Resolve ADR 0092 Databricks audit enablement.
+
+    ``KIRIMANA_DATABRICKS_AUDIT`` is the runtime override. The profile value is
+    loader-threaded from ``audit.databricks`` and defaults to enabled.
+    """
+
+    raw_env = os.environ.get("KIRIMANA_DATABRICKS_AUDIT")
+    if raw_env is not None:
+        value = raw_env.strip().lower()
+        if value in _TRUTHY_AUDIT:
+            return True, None
+        if value in _FALSY_AUDIT:
+            return False, "env:KIRIMANA_DATABRICKS_AUDIT"
+    raw_profile = profile.get("databricks_audit_enabled", True)
+    if isinstance(raw_profile, str):
+        value = raw_profile.strip().lower()
+        if value in _FALSY_AUDIT:
+            return False, "config:audit.databricks=false"
+        if value in _TRUTHY_AUDIT:
+            return True, None
+    if raw_profile is False:
+        return False, "config:audit.databricks=false"
+    return True, None
+
+
+def _line_status(status: str, error_class: str | None) -> str:
+    if status == "denied":
+        return "DENIED"
+    if error_class and error_class.lower() in {"permissiondenied", "permission_denied", "denied"}:
+        return "DENIED"
+    return "OK" if status == "success" else "FAILED"
+
+
+def _kv(value: object) -> str:
+    text = "?" if value is None else str(value)
+    return text.replace("\n", " ").replace("\r", " ").replace(" ", "_") or "?"
+
+
+def _render_audit_line(record: _AuditRecord) -> str:
+    parts = [
+        record.ts,
+        f"user={_kv(record.user)}",
+        f"event={_kv(record.event)}",
+        f"target={_kv(record.target)}",
+        f"status={_line_status(record.status, record.error_class)}",
+        f"dur={record.duration_ms / 1000:.1f}s",
+        f"trace={_kv(record.trace_id)}",
+        f"warehouse={_kv(record.warehouse_id)}",
+        f"via={_kv(record.via)}",
+    ]
+    if record.reason is not None:
+        parts.append(f"reason={_kv(record.reason)}")
+    return " ".join(parts)
+
+
+def _resolve_databricks_audit_paths(profile: dict[str, Any]) -> _AuditPaths:
+    explicit = profile.get("databricks_audit_log_path")
+    if explicit:
+        jsonl = Path(str(explicit))
+        return _AuditPaths(jsonl=jsonl, line=jsonl.with_name("databricks-audit.log"))
+    default_dir = Path.cwd() / "logs" / "databricks-audit"
+    base = Path(str(profile.get("databricks_audit_log_dir") or default_dir))
+    return _AuditPaths(
+        jsonl=base / "databricks-audit.jsonl",
+        line=base / "databricks-audit.log",
+    )
+
+
+def _audit_destination_key(paths: _AuditPaths) -> tuple[str, str]:
+    return (str(paths.jsonl.resolve()), str(paths.line.resolve()))
+
+
+def _claim_audit_disabled_emit(paths: _AuditPaths) -> bool:
+    key = _audit_destination_key(paths)
+    if key in _AUDIT_DISABLED_DESTINATIONS:
+        return False
+    _AUDIT_DISABLED_DESTINATIONS.add(key)
+    return True
+
+
+def _build_audit_record(
+    *,
+    event: str,
+    target: str,
+    status: str,
+    duration_ms: int,
+    attempts: int,
+    warehouse_id: str | None,
+    via: str,
+    user: str | None,
+    error_class: str | None,
+    reason: str | None,
+    statement_preview: str,
+) -> _AuditRecord:
+    ctx = current_trace()
+    return _AuditRecord(
+        ts=datetime.now(UTC).isoformat(timespec="seconds"),
+        trace_id=ctx.kiri_trace_id,
+        apply_id=ctx.apply_id,
+        caller=ctx.caller,
+        via=via,
+        user=user or "unknown",
+        event=event,
+        target=target,
+        duration_ms=duration_ms,
+        attempts=attempts,
+        status=status,
+        warehouse_id=warehouse_id,
+        statement_preview=statement_preview,
+        error_class=error_class,
+        reason=reason,
+    )
+
+
+def _write_audit_line(paths: _AuditPaths, record: _AuditRecord) -> None:
+    path = paths.line
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as f:
+        f.write(_render_audit_line(record) + "\n")
+
+
+def _write_audit_jsonl(paths: _AuditPaths, record: _AuditRecord) -> None:
+    path = paths.jsonl
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Keep existing JSONL keys and status vocabulary for audit_join
+    # back-compat. ADR 0092's OK/FAILED/DENIED vocabulary is only
+    # the one-line projection.
+    row: dict[str, Any] = {
+        "ts": record.ts,
+        "trace_id": record.trace_id,
+        "apply_id": record.apply_id,
+        "caller": record.caller,
+        "duration_ms": record.duration_ms,
+        "attempts": record.attempts,
+        "status": "failed" if record.status == "denied" else record.status,
+        "warehouse_id": record.warehouse_id,
+        "statement_preview": record.statement_preview,
+        "user": record.user,
+        "event": record.event,
+        "via": record.via,
+    }
+    if record.error_class is not None:
+        row["error_class"] = record.error_class
+    if record.reason is not None:
+        row["reason"] = record.reason
+    with path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(row, default=str) + "\n")
+
+
+def _write_audit_record(paths: _AuditPaths, record: _AuditRecord) -> None:
+    with suppress(Exception):
+        _write_audit_line(paths, record)
+    try:
+        _write_audit_jsonl(paths, record)
+    except Exception:
+        # Never break Databricks work because the client-side audit-log
+        # filesystem hiccupped. The Databricks-side audit log (ADR 0049) is
+        # the authoritative trail; this client-side emission is a complement.
+        return
+
+
+def _emit_databricks_audit_record(
+    *,
+    profile: dict[str, Any],
+    paths: _AuditPaths,
+    event: str,
+    target: str,
+    status: str,
+    duration_ms: int,
+    attempts: int,
+    warehouse_id: str | None,
+    via: str,
+    user: str | None,
+    error_class: str | None,
+    statement_preview: str,
+    disabled_reason: str | None = None,
+) -> None:
+    enabled, resolved_disabled_reason = databricks_audit_enabled(profile)
+    if not enabled:
+        if _claim_audit_disabled_emit(paths):
+            record = _build_audit_record(
+                event="AUDIT_DISABLED",
+                target="?",
+                status="failed",
+                duration_ms=0,
+                attempts=0,
+                warehouse_id=warehouse_id,
+                via=via,
+                user=user,
+                error_class=None,
+                reason=disabled_reason
+                or resolved_disabled_reason
+                or "config:audit.databricks=false",
+                statement_preview=statement_preview,
+            )
+            _write_audit_record(paths, record)
+        return
+    record = _build_audit_record(
+        event=event,
+        target=target,
+        status=status,
+        duration_ms=duration_ms,
+        attempts=attempts,
+        warehouse_id=warehouse_id,
+        via=via,
+        user=user,
+        error_class=error_class,
+        reason=None,
+        statement_preview=statement_preview,
+    )
+    _write_audit_record(paths, record)
+
+
+def _normalize_mcp_audit_status(status: str) -> str:
+    value = status.strip().lower()
+    if value in {"ok", "success"}:
+        return "success"
+    if value == "denied":
+        return "denied"
+    return "failed"
+
+
+def emit_databricks_mcp_audit(
+    *,
+    event: str,
+    target: str,
+    status: _McpAuditStatus,
+    duration_ms: int,
+    warehouse_id: str | None,
+    user: str | None = None,
+    error_class: str | None = None,
+    profile: dict[str, Any] | None = None,
+    statement_preview: str | None = None,
+) -> None:
+    """Emit the ADR 0092 audit record at the Kiri→Databricks-MCP boundary."""
+
+    normalized_status = _normalize_mcp_audit_status(status)
+    resolved_profile = profile or {}
+    paths = _resolve_databricks_audit_paths(resolved_profile)
+    _emit_databricks_audit_record(
+        profile=resolved_profile,
+        paths=paths,
+        event=event,
+        target=target,
+        status=normalized_status,
+        duration_ms=duration_ms,
+        attempts=1,
+        warehouse_id=warehouse_id,
+        via="mcp",
+        user=user,
+        error_class=error_class,
+        statement_preview=_redact_preview(statement_preview or f"{event} {target}"),
+    )
+
+
+def _extract_current_user(response: Any) -> str | None:
+    data = getattr(getattr(response, "result", None), "data_array", None)
+    if not data:
+        return None
+    first_row = data[0]
+    if not first_row:
+        return None
+    return str(first_row[0])
+
+
+def build_staging_select_sql(
+    *,
+    volume_path: str,
+    fmt: str,
+    source_file: str,
+    trace_id: str,
+    deleted_flag: str | None,
+    today: date,
+    json_shape: str = "array",
+) -> str:
+    """SELECT wrapper that reads a file from a volume and adds `_kiri_*` columns.
+
+    Path, trace_id, source_file are the only user-ish inputs; we embed them as
+    string literals (Databricks parameters don't survive inside ``read_files``
+    options cleanly). All three come from our own metadata / runtime and
+    never from end-user SQL.
+
+    ``json_shape`` mirrors ``IngestionConfig.json_shape``:
+
+    - ``array`` / ``single`` → ``multiLine => 'true'`` (Spark reads the whole
+      file as one JSON document — array elements become rows, single object
+      becomes a one-row table).
+    - ``ndjson`` → ``multiLine => 'false'`` (newline-delimited; one row per
+      line). This is the shape most integration platforms push.
+
+    Ignored when ``fmt != "json"``.
+    """
+    if fmt not in {"json", "csv"}:
+        raise ValueError(f"Unsupported fmt: {fmt}")
+    if fmt == "json" and json_shape not in {"array", "ndjson", "single"}:
+        raise ValueError(
+            f"Unsupported json_shape: {json_shape!r}; expected one of 'array', 'ndjson', 'single'."
+        )
+    # ``recursiveFileLookup => 'true'`` disables Hive-style partition
+    # discovery in Databricks' ``read_files``: the raw landing path is
+    # ``…/_raw/_kiri_ingested_date=YYYY-MM-DD/<file>``; with discovery
+    # on, Spark synthesises an ``_kiri_ingested_date`` partition column
+    # that collides with the literal one projected below
+    # (AMBIGUOUS_COLUMN_OR_FIELD).
+    if fmt == "json":
+        multi_line = "false" if json_shape == "ndjson" else "true"
+        fmt_opts = f"format => 'json', multiLine => '{multi_line}', recursiveFileLookup => 'true'"
+    else:
+        fmt_opts = "format => 'csv', header => 'true', recursiveFileLookup => 'true'"
+    # Literal escaping — single-quote-in-SQL = double the quote.
+    v = volume_path.replace("'", "''")
+    sf = source_file.replace("'", "''")
+    tid = trace_id.replace("'", "''")
+    d_iso = today.isoformat()
+
+    if deleted_flag:
+        tombstone = (
+            f"CAST(CASE WHEN CAST({_quote_ident(deleted_flag)} AS BOOLEAN) "
+            f"THEN CURRENT_TIMESTAMP() ELSE NULL END AS TIMESTAMP)"
+        )
+    else:
+        tombstone = "CAST(NULL AS TIMESTAMP)"
+
+    return (
+        f"SELECT "
+        f"src.*, "
+        f"CURRENT_TIMESTAMP() AS _kiri_ingested_at, "
+        f"'{sf}' AS _kiri_source_file, "
+        f"'{tid}' AS _kiri_trace_id, "
+        f"{tombstone} AS _kiri_deleted_at, "
+        f"DATE '{d_iso}' AS _kiri_ingested_date "
+        f"FROM read_files('{v}', {fmt_opts}) AS src"
+    )
+
+
+def build_merge_sql(
+    *,
+    target_fq: str,
+    source_select: str,
+    dedupe_key: list[str],
+) -> str:
+    """SQL MERGE: last-write-wins on _kiri_ingested_at per dedupe_key.
+
+    The source is de-duplicated on ``dedupe_key`` first (QUALIFY ROW_NUMBER,
+    keeping the latest ``_kiri_ingested_at``). Without it, a source batch that
+    repeats a key — e.g. the same business key landed twice in one fetch —
+    makes Delta reject the MERGE with
+    ``DELTA_MULTIPLE_SOURCE_ROW_MATCHING_TARGET_ROW_IN_MERGE`` (#268). This
+    mirrors the local runner's arrow-side dedup so both backends agree.
+    """
+    if not dedupe_key:
+        raise ValueError("dedupe_key is required for MERGE")
+    predicate = " AND ".join(
+        f"target.{_quote_ident(k)} = source.{_quote_ident(k)}" for k in dedupe_key
+    )
+    partition = ", ".join(_quote_ident(k) for k in dedupe_key)
+    deduped_source = (
+        f"SELECT * FROM ({source_select}) "
+        f"QUALIFY ROW_NUMBER() OVER ("
+        f"PARTITION BY {partition} ORDER BY _kiri_ingested_at DESC) = 1"
+    )
+    return (
+        f"MERGE INTO {target_fq} AS target "
+        f"USING ({deduped_source}) AS source "
+        f"ON {predicate} "
+        f"WHEN MATCHED AND source._kiri_ingested_at > target._kiri_ingested_at "
+        f"  THEN UPDATE SET * "
+        f"WHEN NOT MATCHED THEN INSERT *"
+    )
+
+
+def build_append_sql(*, target_fq: str, source_select: str) -> str:
+    """SQL INSERT when there is no dedupe_key."""
+    return f"INSERT INTO {target_fq} {source_select}"
+
+
+def build_create_table_sql(*, target_fq: str, source_select: str) -> str:
+    """First-time CREATE TABLE AS SELECT (CTAS) — Delta by default on UC."""
+    return (
+        f"CREATE TABLE IF NOT EXISTS {target_fq} "
+        f"PARTITIONED BY (_kiri_ingested_date) "
+        f"AS {source_select} WHERE 1 = 0"
+    )
+
+
+# ---- adapter --------------------------------------------------------------
+
+
+class DatabricksAdapter(PlatformAdapter):
+    """Talks to Databricks via the Workspace SDK + Statement Execution API."""
+
+    name = "databricks"
+
+    def __init__(self, profile: dict[str, Any]) -> None:
+        super().__init__(profile)
+        self._client: Any | None = None
+        # Per-run cache for the landing-storage handle. Built lazily on
+        # first ``landing_storage()`` call so the adapter stays usable
+        # in profiles that don't declare an ADLS block (legacy tests).
+        self._landing_storage_cache: Any | None = None
+        # S8: simple per-adapter token-bucket gating Statement Execution
+        # API calls. Off by default; operators set ``statement_rps_limit``
+        # in profile to throttle concurrent applies that share a
+        # warehouse.  Single-process — multi-replica deployments need
+        # per-warehouse coordination (out of scope for v1).
+        self._rps_limit: float | None = None
+        rps = profile.get("statement_rps_limit")
+        if rps is not None:
+            try:
+                rps_val = float(rps)
+            except (TypeError, ValueError) as e:
+                raise ValueError(f"statement_rps_limit must be a number; got {rps!r}") from e
+            if rps_val <= 0:
+                raise ValueError(f"statement_rps_limit must be > 0; got {rps_val}")
+            self._rps_limit = rps_val
+        self._last_call_at: float = 0.0
+
+        # N1: retry tunables. Operators with very fast warehouses tighten
+        # the backoff; ones on a noisy network ease it up. Defaults match
+        # the legacy hardcoded values so existing deploys see no change.
+        self._retry_attempts = int(profile.get("retry_attempts", 3))
+        if self._retry_attempts < 1:
+            raise ValueError(f"retry_attempts must be ≥ 1; got {self._retry_attempts}")
+        self._retry_backoff_base = float(profile.get("retry_backoff_base_seconds", 0.5))
+        if self._retry_backoff_base < 0:
+            raise ValueError(
+                f"retry_backoff_base_seconds must be ≥ 0; got {self._retry_backoff_base}"
+            )
+
+        # ADR 0092: per-_execute audit is on by default. A legacy explicit
+        # JSONL path is still honoured exactly; otherwise both projections
+        # live under the project-threaded default audit dir.
+        self._audit_paths = self._resolve_audit_paths(profile)
+        self._audit_disabled_emitted = False
+        self._audit_user: str | None = None
+
+    # ---- public API ------------------------------------------------------
+
+    def required_credentials(self) -> list[Credential]:
+        return [
+            Credential(
+                env_var="DATABRICKS_HOST",
+                description="Workspace URL, e.g. https://adb-123.azuredatabricks.net",
+            ),
+            Credential(
+                env_var="DATABRICKS_TOKEN",
+                description="PAT or OAuth token with SQL + Files API access",
+            ),
+            Credential(
+                env_var="DATABRICKS_WAREHOUSE_ID",
+                description="SQL warehouse ID used for statements and dbt",
+                required=False,
+            ),
+        ]
+
+    def health_check(self) -> HealthStatus:
+        try:
+            result = self._execute("SELECT 1 AS ok")
+        except Exception:
+            return HealthStatus.UNHEALTHY
+        return HealthStatus.HEALTHY if result is not None else HealthStatus.UNHEALTHY
+
+    def dialect(self) -> SqlDialect:
+        """Return ``DeltaDialect`` for Unity Catalog Delta tables (#149).
+
+        ``DatabricksDwDialect`` (Photon ANSI SQL Warehouse) is still future
+        work — when it lands the adapter will switch on a profile flag.
+        """
+        return DeltaDialect()
+
+    def landing_storage(self, vault: Any | None = None) -> Any:
+        """Return the ADLS-backed landing storage (ADR 0046 phase 2).
+
+        Built once per adapter instance (= per ``kiri apply`` run), so
+        the SDK client + credential lookup happen exactly once even
+        when many tables share the same target. When the profile
+        carries a ``${vault:...}`` reference for the credential, the
+        caller MUST pass a ``vault`` :class:`kiri_vault.VaultClient` to
+        resolve it; literal credential strings (test fixtures, dev)
+        flow through unchanged.
+
+        Profile shape::
+
+            targets:
+              prod:
+                adapter: databricks
+                landing_storage:
+                  scheme: adls
+                  account: kirimanalanding
+                  container: landing
+                  credential: ${vault:azure:landing-sas}
+
+        When ``landing_storage`` is absent from the profile, the
+        adapter falls back to :class:`LocalLandingStorage` rooted at
+        ``bronze_raw_root`` so non-Databricks development still works
+        and existing tests stay green.
+        """
+        if self._landing_storage_cache is not None:
+            return self._landing_storage_cache
+
+        block = self.profile.get("landing_storage")
+        if not block:
+            ingest_volume = self.profile.get("ingest_volume")
+            if ingest_volume:
+                # Preferred: write landing bytes straight into a UC
+                # Volume the warehouse can ``read_files()`` from. The
+                # source contract drives the fetch; the storage is the
+                # adapter's choice (this branch is the Databricks one).
+                from kiri_ingestion.storage import DatabricksVolumeLandingStorage
+
+                self._landing_storage_cache = DatabricksVolumeLandingStorage(
+                    workspace_client=self._workspace(),
+                    volume=str(ingest_volume),
+                )
+                return self._landing_storage_cache
+
+            # Back-compat: pre-ADR-0046 profiles drove ingest off the
+            # control-plane FS. Kept for tests and adapters whose
+            # warehouse can in fact read local paths (e.g. an in-pod
+            # dev SQL endpoint); a real Databricks SQL warehouse
+            # cannot read ``file://``, so set ``ingest_volume`` (or a
+            # cloud ``landing_storage`` block) for production runs.
+            from kiri_ingestion.storage import LocalLandingStorage
+
+            # Canonical key is ``bronze_root`` — the kiri.yml target, the
+            # fetch stage and _resolve_profile_paths all use it. Keep
+            # ``bronze_raw_root`` as a back-compat fallback.
+            root_value = (
+                self.profile.get("bronze_root")
+                or self.profile.get("bronze_raw_root")
+                or "./data/bronze"
+            )
+            root = Path(str(root_value)).resolve()
+            self._landing_storage_cache = LocalLandingStorage(root)
+            return self._landing_storage_cache
+
+        scheme = block.get("scheme", "adls")
+        if scheme != "adls":
+            raise ValueError(
+                f"DatabricksAdapter.landing_storage: unsupported scheme {scheme!r}; "
+                "only 'adls' is supported in phase 2."
+            )
+        account = block.get("account")
+        container = block.get("container")
+        credential = block.get("credential")
+        if not (account and container and credential):
+            raise ValueError(
+                "DatabricksAdapter.landing_storage requires account, "
+                "container, and credential in profile.landing_storage."
+            )
+
+        resolved = self._resolve_credential(str(credential), vault)
+
+        from kiri_ingestion.storage import AdlsLandingStorage
+
+        self._landing_storage_cache = AdlsLandingStorage.from_credential(
+            account=str(account),
+            container=str(container),
+            credential=resolved,
+        )
+        return self._landing_storage_cache
+
+    @staticmethod
+    def _resolve_credential(value: str, vault: Any | None) -> str:
+        """Resolve a profile credential string.
+
+        - ``${vault:<id>:<key>}`` requires a vault client; raises if
+          one isn't passed.
+        - Anything else is returned verbatim (literal SAS, env-var
+          token, etc).
+        """
+        from kiri_vault.ref import VaultRef
+
+        parsed = VaultRef.parse(value)
+        if parsed is None:
+            return value
+        if vault is None:
+            raise RuntimeError(
+                "DatabricksAdapter.landing_storage: credential is a "
+                f"vault reference ({value!r}) but no vault client was "
+                "provided. Pass project.vault_client() to landing_storage()."
+            )
+        return str(vault.get(parsed.secret_id, parsed.key))
+
+    def claim_target(self, manifest: ProjectManifest) -> None:
+        """Idempotently claim the Unity Catalog for ``(project, env)``.
+
+        Mirrors the LocalDuckDB implementation of ADRs 0014 + 0017. Not
+        currently exercised by CI (requires a live workspace); the code
+        below codifies the SQL shape so the invariant cannot drift.
+
+        - Row-per-(project, env). Same project + different envs coexist;
+          different projects in the same env collide.
+        - Legacy 5-column manifest migrated in-place with ALTER TABLE
+          (Delta supports ``ADD COLUMNS``).
+        - Re-apply refreshes release_sha/tag/ts when the caller brought
+          them (kiri release apply path); plain apply preserves existing.
+        """
+
+        def esc(s: str | None) -> str:
+            if s is None:
+                return "NULL"
+            return "'" + s.replace("'", "''") + "'"
+
+        catalog = self._catalog()
+        fq_meta = f"{_quote_ident(catalog)}.{_quote_ident(_META_SCHEMA)}"
+        fq_table = f"{fq_meta}.{_quote_ident(_MANIFEST_TABLE)}"
+        self._execute(f"CREATE SCHEMA IF NOT EXISTS {fq_meta}")
+        self._execute(
+            f"CREATE TABLE IF NOT EXISTS {fq_table} ("
+            "  project_name STRING NOT NULL,"
+            "  project_version STRING NOT NULL,"
+            "  silver_technique STRING NOT NULL,"
+            "  first_write STRING NOT NULL,"
+            "  kirimana_version STRING NOT NULL,"
+            "  environment STRING NOT NULL,"
+            "  release_sha STRING,"
+            "  release_tag STRING,"
+            "  release_ts STRING"
+            ") USING DELTA"
+        )
+
+        # ADR 0017 migration: legacy 0014-shape tables get the missing
+        # columns bolted on, existing rows backfilled env='dev'. Databricks
+        # SQL has no ``ADD COLUMNS IF NOT EXISTS`` (parse error on a
+        # second apply / on the full-schema table the CREATE above just
+        # made), so introspect the live columns and add only the genuine
+        # gaps — no-op when the table already carries them.
+        existing_rows = self._execute(
+            "SELECT column_name FROM system.information_schema.columns "
+            "WHERE table_catalog = ? AND table_schema = ? AND table_name = ?",
+            parameters=[catalog, _META_SCHEMA, _MANIFEST_TABLE],
+        )
+        existing = {str(r[0]).lower() for r in (existing_rows or [])}
+        # ADR 0020 naming-lock columns join the 0017 migration set. The live
+        # _kiri_project_manifest predates them, so they must be bolted on
+        # before the INSERT/SELECT below references them. Databricks SQL has
+        # no reliable ``ADD COLUMNS IF NOT EXISTS`` (parse error on the
+        # full-schema table the CREATE above just made), so the same
+        # information_schema introspection that guards the 0017 columns guards
+        # these too — emitting only the genuine gaps, a no-op once present.
+        migration_columns = [
+            ("environment", "STRING"),
+            ("release_sha", "STRING"),
+            ("release_tag", "STRING"),
+            ("release_ts", "STRING"),
+            ("naming_locked_at", "STRING"),
+            ("naming_snapshot", "STRING"),
+        ]
+        missing = [(c, t) for c, t in migration_columns if c.lower() not in existing]
+        if missing:
+            cols_sql = ", ".join(f"{c} {t}" for c, t in missing)
+            self._execute(f"ALTER TABLE {fq_table} ADD COLUMNS ({cols_sql})")
+        self._execute(f"UPDATE {fq_table} SET environment = 'dev' WHERE environment IS NULL")
+
+        # Slot lookup. Reads the locked naming_snapshot too (ADR 0020) so the
+        # enforce/backfill decision below reuses this round-trip — no second
+        # SELECT.
+        slot_result = self._execute(
+            f"SELECT project_name, project_version, silver_technique, "
+            f"first_write, naming_snapshot FROM {fq_table} "
+            f"WHERE project_name = {esc(manifest.project_name)} "
+            f"AND environment = {esc(manifest.environment)}"
+        )
+        slot_rows = list(slot_result) if slot_result is not None else []
+
+        # Cross-project collision in the same env.
+        other_result = self._execute(
+            f"SELECT project_name, project_version, silver_technique, "
+            f"first_write FROM {fq_table} "
+            f"WHERE environment = {esc(manifest.environment)} "
+            f"AND project_name <> {esc(manifest.project_name)}"
+        )
+        other_rows = list(other_result) if other_result is not None else []
+        if other_rows:
+            other_name, other_ver, other_tech, other_first = other_rows[0]
+            raise ProjectTargetCollisionError(
+                f"Environment {manifest.environment!r} in catalog "
+                f"{catalog!r} is owned by project {other_name!r} "
+                f"(version {other_ver}, silver technique {other_tech!r}, "
+                f"first write {other_first}). Cannot apply from project "
+                f"{manifest.project_name!r}. Either pick a different "
+                "target/environment in kiri.yml or coordinate with the "
+                "owning project."
+            )
+
+        if not slot_rows:
+            self._execute(
+                f"INSERT INTO {fq_table} "
+                f"(project_name, project_version, silver_technique, "
+                f"first_write, kirimana_version, environment, "
+                f"release_sha, release_tag, release_ts, "
+                f"naming_locked_at, naming_snapshot) "
+                f"VALUES ("
+                f"{esc(manifest.project_name)}, "
+                f"{esc(manifest.project_version)}, "
+                f"{esc(manifest.silver_technique)}, "
+                f"{esc(manifest.first_write)}, "
+                f"{esc(manifest.kirimana_version)}, "
+                f"{esc(manifest.environment)}, "
+                f"{esc(manifest.release_sha)}, "
+                f"{esc(manifest.release_tag)}, "
+                f"{esc(manifest.release_ts)}, "
+                f"{esc(manifest.naming_locked_at)}, "
+                f"{esc(manifest.naming_snapshot)})"
+            )
+            return
+
+        if len(slot_rows) > 1:
+            raise ProjectTargetCollisionError(
+                f"{fq_table} contains {len(slot_rows)} rows for "
+                f"(project={manifest.project_name!r}, "
+                f"env={manifest.environment!r}) — catalog metadata is "
+                "corrupted. Inspect and resolve."
+            )
+
+        # ADR 0020 naming-lock enforcement (same-slot re-apply). The locked
+        # snapshot was read in the slot SELECT above (column 5).
+        stored_snapshot = slot_rows[0][4]
+        incoming_snapshot = manifest.naming_snapshot
+        if ProjectManifest.naming_snapshot_diverges(stored_snapshot, incoming_snapshot):
+            raise NamingLockError(
+                f"naming block for project {manifest.project_name!r} "
+                f"(environment {manifest.environment!r}) diverges from the "
+                "locked naming snapshot recorded on first write.\n"
+                f"  locked:   {stored_snapshot}\n"
+                f"  incoming: {incoming_snapshot}\n"
+                "Naming conventions are locked after the first apply "
+                "(ADR 0020). Restore the locked naming in kiri.yml, or run "
+                "`kiri naming migrate` (future) to rewrite the warehouse "
+                "objects and re-lock. Refusing to apply against live data "
+                "with a changed naming scheme."
+            )
+        if stored_snapshot is None and incoming_snapshot is not None:
+            # Pre-upgrade manifest row written before this feature: no snapshot
+            # was ever recorded. Backfill it (graceful upgrade, never a
+            # failure) so the lock takes effect from now on. The
+            # `naming_snapshot IS NULL` predicate makes this a compare-and-set:
+            # if a concurrent apply locked a snapshot between the slot SELECT
+            # and here, this UPDATE is a no-op rather than clobbering the lock.
+            self._execute(
+                f"UPDATE {fq_table} SET "
+                f"naming_locked_at = {esc(manifest.naming_locked_at)}, "
+                f"naming_snapshot = {esc(incoming_snapshot)} "
+                f"WHERE project_name = {esc(manifest.project_name)} "
+                f"AND environment = {esc(manifest.environment)} "
+                f"AND naming_snapshot IS NULL"
+            )
+
+        # Same slot — idempotent reclaim. Refresh release fields if the
+        # caller supplied them (kiri release apply post-success).
+        if (
+            manifest.release_sha is not None
+            or manifest.release_tag is not None
+            or manifest.release_ts is not None
+        ):
+            self._execute(
+                f"UPDATE {fq_table} SET "
+                f"release_sha = {esc(manifest.release_sha)}, "
+                f"release_tag = {esc(manifest.release_tag)}, "
+                f"release_ts = {esc(manifest.release_ts)}, "
+                f"project_version = {esc(manifest.project_version)}, "
+                f"kirimana_version = {esc(manifest.kirimana_version)} "
+                f"WHERE project_name = {esc(manifest.project_name)} "
+                f"AND environment = {esc(manifest.environment)}"
+            )
+
+    def read_manifest(self, project_name: str, environment: str) -> ProjectManifest | None:
+        """Return the manifest row for (project, env), or None if absent.
+
+        Delta mirror of the LocalDuckDB path. Not CI-tested (requires a
+        live workspace); catches every exception and maps to None so
+        `kiri release status` on a workspace without the schema/table
+        reports "not applied yet" rather than blowing up.
+        """
+
+        def esc(s: str) -> str:
+            return "'" + s.replace("'", "''") + "'"
+
+        catalog = self._catalog()
+        fq_table = (
+            f"{_quote_ident(catalog)}.{_quote_ident(_META_SCHEMA)}.{_quote_ident(_MANIFEST_TABLE)}"
+        )
+        try:
+            result = self._execute(
+                f"SELECT project_name, project_version, silver_technique, "
+                f"first_write, kirimana_version, environment, "
+                f"release_sha, release_tag, release_ts, "
+                f"naming_locked_at, naming_snapshot "
+                f"FROM {fq_table} "
+                f"WHERE project_name = {esc(project_name)} "
+                f"AND environment = {esc(environment)}"
+            )
+        except Exception:
+            return None
+        rows = list(result) if result is not None else []
+        if not rows:
+            return None
+        row = rows[0]
+        return ProjectManifest(
+            project_name=row[0],
+            project_version=row[1],
+            silver_technique=row[2],
+            first_write=row[3],
+            kirimana_version=row[4],
+            environment=row[5],
+            release_sha=row[6],
+            release_tag=row[7],
+            release_ts=row[8],
+            naming_locked_at=row[9],
+            naming_snapshot=row[10],
+        )
+
+    def log_apply(self, entry: ApplyLogEntry) -> None:
+        """Upsert one row of ``_kiri_meta._kiri_apply_log`` (ADR 0017).
+
+        Delta Lake shape mirrors the LocalDuckDB implementation. Not
+        CI-tested (requires a live workspace); SQL form codifies the
+        invariant so it cannot drift.
+        """
+
+        def esc(s: str | None) -> str:
+            if s is None:
+                return "NULL"
+            return "'" + s.replace("'", "''") + "'"
+
+        catalog = self._catalog()
+        fq_meta = f"{_quote_ident(catalog)}.{_quote_ident(_META_SCHEMA)}"
+        fq_log = f"{fq_meta}.{_quote_ident(_APPLY_LOG_TABLE)}"
+        self._execute(f"CREATE SCHEMA IF NOT EXISTS {fq_meta}")
+        self._execute(
+            f"CREATE TABLE IF NOT EXISTS {fq_log} ("
+            "  apply_id STRING NOT NULL,"
+            "  project_name STRING NOT NULL,"
+            "  environment STRING NOT NULL,"
+            "  release_sha STRING,"
+            "  release_tag STRING,"
+            "  release_ts STRING,"
+            "  kirimana_version STRING NOT NULL,"
+            "  started_at STRING NOT NULL,"
+            "  ended_at STRING,"
+            "  status STRING NOT NULL,"
+            "  error_message STRING"
+            ") USING DELTA"
+        )
+        existing_result = self._execute(
+            f"SELECT apply_id FROM {fq_log} WHERE apply_id = {esc(entry.apply_id)}"
+        )
+        existing_rows = list(existing_result) if existing_result is not None else []
+        if not existing_rows:
+            self._execute(
+                f"INSERT INTO {fq_log} "
+                f"(apply_id, project_name, environment, release_sha, "
+                f" release_tag, release_ts, kirimana_version, started_at, "
+                f" ended_at, status, error_message) VALUES ("
+                f"{esc(entry.apply_id)}, {esc(entry.project_name)}, "
+                f"{esc(entry.environment)}, {esc(entry.release_sha)}, "
+                f"{esc(entry.release_tag)}, {esc(entry.release_ts)}, "
+                f"{esc(entry.kirimana_version)}, {esc(entry.started_at)}, "
+                f"{esc(entry.ended_at)}, {esc(entry.status)}, "
+                f"{esc(entry.error_message)})"
+            )
+        else:
+            self._execute(
+                f"UPDATE {fq_log} SET "
+                f"release_sha = {esc(entry.release_sha)}, "
+                f"release_tag = {esc(entry.release_tag)}, "
+                f"release_ts = {esc(entry.release_ts)}, "
+                f"ended_at = {esc(entry.ended_at)}, "
+                f"status = {esc(entry.status)}, "
+                f"error_message = {esc(entry.error_message)} "
+                f"WHERE apply_id = {esc(entry.apply_id)}"
+            )
+
+    def read_watermark(self, asset_urn: str, environment: str) -> AssetWatermark | None:
+        """Return the watermark row for (asset_urn, env), or None if absent.
+
+        Delta mirror of the LocalDuckDB path (ADR 0080 §2). Not CI-tested
+        (requires a live workspace). Only the "table or schema does not exist"
+        failure maps to None ("no cursor yet" → first run); EVERY other failure
+        (permission / transport / malformed row) is wrapped in
+        :class:`WatermarkStoreError` and raised. Flattening a real read error to
+        None would silently reprocess the full history (P0 data-correctness
+        hazard). The rendered SQL is pinned by a golden-SQL unit test.
+        """
+
+        def esc(s: str) -> str:
+            return "'" + s.replace("'", "''") + "'"
+
+        catalog = self._catalog()
+        fq_table = (
+            f"{_quote_ident(catalog)}.{_quote_ident(_META_SCHEMA)}."
+            f"{_quote_ident(_ASSET_WATERMARKS_TABLE)}"
+        )
+        try:
+            result = self._execute(
+                f"SELECT asset_urn, target_env, grain, last_processed_value, "
+                f"last_run_id, updated_at "
+                f"FROM {fq_table} "
+                f"WHERE asset_urn = {esc(asset_urn)} "
+                f"AND target_env = {esc(environment)}"
+            )
+        except Exception as exc:
+            if _is_table_or_schema_not_found(exc):
+                # Legitimate "no watermark store yet" → first run / no cursor.
+                return None
+            # Any other failure is NOT absence — fail closed so a transient read
+            # error is never mistaken for an empty cursor (full reprocess).
+            raise WatermarkStoreError(
+                f"read_watermark failed for asset_urn={asset_urn!r} env={environment!r}: {exc}"
+            ) from exc
+        rows = list(result) if result is not None else []
+        if not rows:
+            return None
+        row = rows[0]
+        return AssetWatermark(
+            asset_urn=row[0],
+            target_env=row[1],
+            grain=row[2],
+            last_processed_value=row[3],
+            last_run_id=row[4],
+            updated_at=row[5],
+        )
+
+    def advance_watermark(
+        self,
+        asset_urn: str,
+        environment: str,
+        *,
+        grain: str,
+        last_processed_value: str,
+        last_run_id: str | None,
+    ) -> None:
+        """Upsert one row of ``_kiri_meta._kiri_asset_watermarks`` (ADR 0080 §2).
+
+        Delta Lake shape mirroring the LocalDuckDB implementation and the
+        ``_kiri_release_state`` sink: CREATE SCHEMA / TABLE IF NOT EXISTS, then
+        the established atomic upsert — an idempotent ``UPDATE ... WHERE <key>``
+        (0 rows when absent) followed by a guarded
+        ``INSERT ... SELECT <literals> WHERE NOT EXISTS (SELECT 1 ...)`` (no-op
+        when present). Never MERGE, never a Python-side read-then-write branch.
+        Idempotent on ``(asset_urn, target_env)`` — one row per slot.
+
+        Delta has no enforced PRIMARY KEY, so the guarded-insert idiom is itself
+        the backstop against a duplicate row — exactly as the other ``_kiri_meta``
+        Delta tables (``_kiri_release_state`` / ``_kiri_active_contract_versions``)
+        do. Not CI-tested against a live cluster; the rendered SQL form is pinned
+        by a golden-SQL unit test so it cannot drift.
+        """
+
+        def esc(s: str | None) -> str:
+            if s is None:
+                return "NULL"
+            return "'" + s.replace("'", "''") + "'"
+
+        from datetime import datetime
+
+        updated_at = datetime.now(UTC).isoformat()
+        catalog = self._catalog()
+        fq_meta = f"{_quote_ident(catalog)}.{_quote_ident(_META_SCHEMA)}"
+        fq_table = f"{fq_meta}.{_quote_ident(_ASSET_WATERMARKS_TABLE)}"
+        self._execute(f"CREATE SCHEMA IF NOT EXISTS {fq_meta}")
+        self._execute(
+            f"CREATE TABLE IF NOT EXISTS {fq_table} ("
+            "  asset_urn STRING NOT NULL,"
+            "  target_env STRING NOT NULL,"
+            "  grain STRING NOT NULL,"
+            "  last_processed_value STRING,"
+            "  last_run_id STRING,"
+            "  updated_at STRING NOT NULL"
+            ") USING DELTA"
+        )
+        wm_key = f"asset_urn = {esc(asset_urn)} AND target_env = {esc(environment)}"
+        # Atomic: idempotent UPDATE (0 rows when absent) then a guarded INSERT
+        # (no-op when present) — the duplicate-row backstop on Delta (no PK).
+        self._execute(
+            f"UPDATE {fq_table} SET "
+            f"grain = {esc(grain)}, "
+            f"last_processed_value = {esc(last_processed_value)}, "
+            f"last_run_id = {esc(last_run_id)}, "
+            f"updated_at = {esc(updated_at)} "
+            f"WHERE {wm_key}"
+        )
+        self._execute(
+            f"INSERT INTO {fq_table} "
+            f"(asset_urn, target_env, grain, last_processed_value, "
+            f" last_run_id, updated_at) "
+            f"SELECT {esc(asset_urn)}, {esc(environment)}, {esc(grain)}, "
+            f"{esc(last_processed_value)}, {esc(last_run_id)}, {esc(updated_at)} "
+            f"WHERE NOT EXISTS (SELECT 1 FROM {fq_table} WHERE {wm_key})"
+        )
+
+    def mirror_release_manifest(self, entry: ReleaseManifestEntry) -> None:
+        """Mirror one apply's release manifest into ``_kiri_meta`` (ADR 0041).
+
+        Delta Lake shape, validated live against ``kirimana_mvp``. CREATE
+        SCHEMA/TABLE IF NOT EXISTS, then an atomic conditional-insert upsert
+        (never MERGE, never a Python-side read-then-write branch): a guarded
+        ``UPDATE ... WHERE <key>`` followed by an
+        ``INSERT ... SELECT <literals> WHERE NOT EXISTS (SELECT 1 ...)``. The
+        FROM-less ``SELECT`` + ``WHERE NOT EXISTS`` was validated live on Delta
+        and is byte-for-byte the same logical pattern the DuckDB backend uses,
+        so the two backends converge. Not CI-tested against a live cluster; the
+        rendered SQL form is pinned by a golden-SQL unit test so it cannot
+        drift.
+
+        - ``_kiri_release_state``: keyed on ``environment`` (UPDATE-then-guarded
+          INSERT).
+        - ``_kiri_active_contract_versions``: keyed on ``(environment, urn)``
+          (UPDATE-then-guarded INSERT per changed contract).
+        - ``_kiri_promotion_history``: append-only, single guarded INSERT on
+          ``audit_id`` so re-applying the same apply does not duplicate a row.
+
+        Self-fail-soft: the whole body is wrapped in ``try/except`` and logs a
+        best-effort warning on any error — this governance sink must never raise
+        out of the adapter and block a successful apply. The SQL itself is
+        idempotent so a repeated call against the same audit_id is a no-op for
+        history and an UPDATE for state/versions.
+        """
+        try:
+            self._mirror_release_manifest_unguarded(entry)
+        except Exception as exc:  # governance sink must never raise
+            _logger.warning(
+                "mirror_release_manifest failed for audit_id=%s (governance sink, best-effort): %s",
+                entry.audit_id,
+                exc,
+            )
+
+    def _mirror_release_manifest_unguarded(self, entry: ReleaseManifestEntry) -> None:
+        def esc(s: str | None) -> str:
+            if s is None:
+                return "NULL"
+            return "'" + s.replace("'", "''") + "'"
+
+        def boollit(b: bool) -> str:
+            return "TRUE" if b else "FALSE"
+
+        catalog = self._catalog()
+        fq_meta = f"{_quote_ident(catalog)}.{_quote_ident(_META_SCHEMA)}"
+        fq_state = f"{fq_meta}.{_quote_ident(_RELEASE_STATE_TABLE)}"
+        fq_versions = f"{fq_meta}.{_quote_ident(_ACTIVE_CONTRACT_VERSIONS_TABLE)}"
+        fq_history = f"{fq_meta}.{_quote_ident(_PROMOTION_HISTORY_TABLE)}"
+
+        self._execute(f"CREATE SCHEMA IF NOT EXISTS {fq_meta}")
+        self._execute(
+            f"CREATE TABLE IF NOT EXISTS {fq_state} ("
+            "  environment STRING NOT NULL,"
+            "  release_sha STRING NOT NULL,"
+            "  ordinal INT,"
+            "  last_applied_at STRING NOT NULL,"
+            "  last_applied_by STRING NOT NULL,"
+            "  last_audit_id STRING NOT NULL,"
+            "  last_apply_status STRING NOT NULL,"
+            "  updated_at STRING"
+            ") USING DELTA"
+        )
+        self._execute(
+            f"CREATE TABLE IF NOT EXISTS {fq_versions} ("
+            "  environment STRING NOT NULL,"
+            "  contract_urn STRING NOT NULL,"
+            "  contract_version STRING NOT NULL,"
+            "  applied_at STRING NOT NULL,"
+            "  applied_by STRING NOT NULL,"
+            "  audit_id STRING NOT NULL,"
+            "  is_breaking BOOLEAN,"
+            "  is_hotfix BOOLEAN,"
+            "  previous_version STRING"
+            ") USING DELTA"
+        )
+        self._execute(
+            f"CREATE TABLE IF NOT EXISTS {fq_history} ("
+            "  audit_id STRING NOT NULL,"
+            "  environment STRING NOT NULL,"
+            "  release_sha STRING NOT NULL,"
+            "  initiated_at STRING NOT NULL,"
+            "  completed_at STRING,"
+            "  initiated_by STRING NOT NULL,"
+            "  status STRING NOT NULL,"
+            "  changed_contracts STRING,"
+            "  breaking_ack BOOLEAN,"
+            "  hotfix BOOLEAN"
+            ") USING DELTA"
+        )
+
+        ordinal_lit = "NULL" if entry.ordinal is None else str(entry.ordinal)
+
+        # release_state — one row per environment. Atomic: idempotent UPDATE
+        # (0 rows when absent) then a guarded INSERT (no-op when present).
+        state_key = f"environment = {esc(entry.environment)}"
+        self._execute(
+            f"UPDATE {fq_state} SET "
+            f"release_sha = {esc(entry.release_sha)}, "
+            f"ordinal = {ordinal_lit}, "
+            f"last_applied_at = {esc(entry.applied_at)}, "
+            f"last_applied_by = {esc(entry.applied_by)}, "
+            f"last_audit_id = {esc(entry.audit_id)}, "
+            f"last_apply_status = {esc(entry.status)}, "
+            f"updated_at = {esc(entry.applied_at)} "
+            f"WHERE {state_key}"
+        )
+        self._execute(
+            f"INSERT INTO {fq_state} "
+            f"(environment, release_sha, ordinal, last_applied_at, "
+            f" last_applied_by, last_audit_id, last_apply_status, updated_at) "
+            f"SELECT {esc(entry.environment)}, {esc(entry.release_sha)}, "
+            f"{ordinal_lit}, {esc(entry.applied_at)}, {esc(entry.applied_by)}, "
+            f"{esc(entry.audit_id)}, {esc(entry.status)}, {esc(entry.applied_at)} "
+            f"WHERE NOT EXISTS (SELECT 1 FROM {fq_state} WHERE {state_key})"
+        )
+
+        # active_contract_versions — one row per (environment, contract_urn).
+        # Same atomic UPDATE-then-guarded-INSERT pattern.
+        for change in entry.changed_contracts:
+            ver_key = f"environment = {esc(entry.environment)} AND contract_urn = {esc(change.urn)}"
+            self._execute(
+                f"UPDATE {fq_versions} SET "
+                f"contract_version = {esc(change.to_version)}, "
+                f"applied_at = {esc(entry.applied_at)}, "
+                f"applied_by = {esc(entry.applied_by)}, "
+                f"audit_id = {esc(entry.audit_id)}, "
+                f"is_breaking = {boollit(change.breaking)}, "
+                f"is_hotfix = {boollit(change.hotfix)}, "
+                f"previous_version = {esc(change.from_version)} "
+                f"WHERE {ver_key}"
+            )
+            self._execute(
+                f"INSERT INTO {fq_versions} "
+                f"(environment, contract_urn, contract_version, applied_at, "
+                f" applied_by, audit_id, is_breaking, is_hotfix, previous_version) "
+                f"SELECT {esc(entry.environment)}, {esc(change.urn)}, "
+                f"{esc(change.to_version)}, {esc(entry.applied_at)}, "
+                f"{esc(entry.applied_by)}, {esc(entry.audit_id)}, "
+                f"{boollit(change.breaking)}, {boollit(change.hotfix)}, "
+                f"{esc(change.from_version)} "
+                f"WHERE NOT EXISTS (SELECT 1 FROM {fq_versions} WHERE {ver_key})"
+            )
+
+        # promotion_history — append-only, single guarded INSERT on audit_id.
+        changed_json = json.dumps(
+            [
+                {
+                    "urn": c.urn,
+                    "from_version": c.from_version,
+                    "to_version": c.to_version,
+                    "breaking": c.breaking,
+                    "hotfix": c.hotfix,
+                }
+                for c in entry.changed_contracts
+            ]
+        )
+        breaking_ack = any(c.breaking for c in entry.changed_contracts)
+        hotfix = any(c.hotfix for c in entry.changed_contracts)
+        self._execute(
+            f"INSERT INTO {fq_history} "
+            f"(audit_id, environment, release_sha, initiated_at, "
+            f" completed_at, initiated_by, status, changed_contracts, "
+            f" breaking_ack, hotfix) "
+            f"SELECT {esc(entry.audit_id)}, {esc(entry.environment)}, "
+            f"{esc(entry.release_sha)}, {esc(entry.applied_at)}, "
+            f"{esc(entry.applied_at)}, {esc(entry.applied_by)}, "
+            f"{esc(entry.status)}, {esc(changed_json)}, "
+            f"{boollit(breaking_ack)}, {boollit(hotfix)} "
+            f"WHERE NOT EXISTS (SELECT 1 FROM {fq_history} "
+            f"WHERE audit_id = {esc(entry.audit_id)})"
+        )
+
+    def resolve_storage(
+        self,
+        binding: StorageBinding,
+        *,
+        live: bool = False,
+        provision: bool = False,
+    ) -> StorageResolution:
+        """Map a per-layer storage binding to live Unity Catalog (ADR 0132 §3).
+
+        Read+validate (when ``live``) then optional operator-gated provision.
+        Provisioning DDL runs **only** when ``provision is True`` AND this adapter
+        ``supports("unity-catalog")`` — a bare ``live=True`` read+validates but
+        never mutates. Fully fail-soft — every UC interaction is wrapped so auth /
+        permission / not-found errors land in ``issues`` and the method never
+        raises out (the apply stage treats the result as advisory; the hard gate
+        is the author-time ``validate_project``).
+        """
+        do_provision = provision and self.supports("unity-catalog")
+        try:
+            return self._resolve_storage_unguarded(binding, live=live, provision=do_provision)
+        except Exception as exc:  # storage resolve must never raise out
+            _logger.warning(
+                "resolve_storage failed for external_location=%s (advisory, best-effort): %s",
+                binding.external_location,
+                exc,
+            )
+            return StorageResolution(
+                supported=True,
+                dry_run=not do_provision,
+                issues=[
+                    f"resolve_storage failed for external location "
+                    f"{binding.external_location!r} (error category: "
+                    f"{type(exc).__name__})"
+                ],
+            )
+
+    def _resolve_storage_unguarded(
+        self,
+        binding: StorageBinding,
+        *,
+        live: bool,
+        provision: bool,
+    ) -> StorageResolution:
+        from kiri_core.storage_paths import (
+            is_strict_subpath,
+            is_vault_ref,
+            parse_location,
+        )
+
+        issues: list[str] = []
+        provisioned: list[str] = []
+
+        # ---- Read: DESCRIBE EXTERNAL LOCATION `<name>` -----------------------
+        # Vault-ref external locations are opaque (resolved elsewhere); we cannot
+        # DESCRIBE a secret, so skip the live read and record nothing — author-
+        # time §4.4 covers resolvability.
+        url: str | None = None
+        credential_name: str | None = None
+        location_exists = False
+        if live and not is_vault_ref(binding.external_location):
+            rows = self._execute(_render_describe_external_location(binding.external_location))
+            # DESCRIBE EXTERNAL LOCATION returns columns
+            # (name, url, credential_name, owner, ...). Read positionally: the
+            # first three columns are stable across runtimes we target.
+            if rows:
+                location_exists = True
+                first = rows[0]
+                url = str(first[1]) if len(first) > 1 and first[1] is not None else None
+                credential_name = str(first[2]) if len(first) > 2 and first[2] is not None else None
+            else:
+                # ADR-006 footgun: the external location named by the binding is
+                # absent live. Record it (do not raise) — this is exactly the
+                # missing-location case caught at apply time.
+                issues.append(
+                    f"external location {binding.external_location!r} does not "
+                    f"exist (DESCRIBE EXTERNAL LOCATION returned no rows)"
+                )
+
+        # ---- Validate: managed/schema roots are sub-paths of url -------------
+        if url is not None:
+            ext = parse_location(url)
+            if ext is None:
+                issues.append(
+                    f"external location url {url!r} is not a parseable scheme://authority/path URL"
+                )
+            else:
+                candidates: list[tuple[str, str]] = [("managed_location", binding.managed_location)]
+                candidates.extend(
+                    (f"schema_locations.{schema}", value)
+                    for schema, value in binding.schema_locations.items()
+                )
+                for field_path, value in candidates:
+                    if is_vault_ref(value):
+                        continue
+                    loc = parse_location(value)
+                    if loc is None:
+                        issues.append(
+                            f"{field_path} {value!r} is not a parseable scheme://authority/path URL"
+                        )
+                    elif not is_strict_subpath(loc, ext):
+                        issues.append(
+                            f"{field_path} {value!r} is not a strict sub-path of "
+                            f"the external location url {url!r}"
+                        )
+            if not credential_name:
+                issues.append(
+                    f"external location {binding.external_location!r} has no storage credential"
+                )
+
+        # ---- Provision (opt-in): caller-gated provision flag -----------------
+        # The caller (CLI) has already computed the full four-part operator gate
+        # (binding.provision AND KIRIMANA_STORAGE_PROVISION_LIVE AND
+        # supports(unity-catalog)); resolve_storage re-checks supports() for
+        # defense-in-depth before passing ``provision`` here.
+        do_provision = provision
+        if do_provision:
+            catalog = self._catalog()
+            # External location: only create when it is genuinely absent and we
+            # have an explicit root URL plus a credential to back it. The common
+            # case is a pre-existing location (creation is the rare opt-in). The
+            # external_location field is a NAME, never a URL — we render the
+            # CREATE from the distinct ``external_location_url``. When the URL is
+            # missing we record an issue and skip the CREATE rather than guess.
+            if not location_exists and not is_vault_ref(binding.external_location):
+                if binding.external_location_url and binding.storage_credential:
+                    ddl = _render_create_external_location(
+                        binding.external_location,
+                        binding.external_location_url,
+                        binding.storage_credential,
+                    )
+                    self._execute(ddl)
+                    provisioned.append(ddl)
+                elif not binding.external_location_url:
+                    issues.append(
+                        f"external location {binding.external_location!r} absent "
+                        "and no external_location_url to create it"
+                    )
+                else:
+                    issues.append(
+                        f"external location {binding.external_location!r} absent "
+                        "and no storage_credential to create it"
+                    )
+            # Per-schema MANAGED LOCATION — idempotent CREATE SCHEMA.
+            for schema, location in binding.schema_locations.items():
+                if is_vault_ref(location):
+                    continue
+                ddl = _render_create_schema_managed_location(catalog, schema, location)
+                self._execute(ddl)
+                provisioned.append(ddl)
+
+        return StorageResolution(
+            supported=True,
+            external_location_url=url,
+            credential_name=credential_name,
+            validated=(live and not is_vault_ref(binding.external_location)) and not issues,
+            issues=issues,
+            provisioned=provisioned,
+            dry_run=not do_provision,
+        )
+
+    def create_schema(self, schema_name: str) -> RunResult:
+        start = time.monotonic()
+        catalog = self._catalog()
+        try:
+            self._execute(
+                f"CREATE SCHEMA IF NOT EXISTS {_quote_ident(catalog)}.{_quote_ident(schema_name)}"
+            )
+        except Exception as e:
+            return RunResult(
+                status=RunStatus.FAILED,
+                message=f"create_schema failed: {e}",
+            )
+        return RunResult(
+            status=RunStatus.SUCCESS,
+            message=f"schema {catalog}.{schema_name} ready",
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    def ingest_bronze(self, source: Source, plan: IngestionPlan) -> RunResult:
+        """Dispatch on the table's ingestion.mode, mirroring LocalDuckDB."""
+        ingestion = plan.effective_ingestion()
+        mode = ingestion.mode if ingestion else IngestionMode.FIXTURE_FILE
+        # REST_API / DATABASE / SOAP fetchers drop files into _landing/
+        # just like an external system would for LANDING_ZONE — from here
+        # all four are ingested identically (mirrors LocalDuckDB).
+        if mode in {
+            IngestionMode.LANDING_ZONE,
+            IngestionMode.REST_API,
+            IngestionMode.DATABASE,
+            IngestionMode.SOAP,
+        }:
+            return self._ingest_landing_zone(source, plan)
+        return self._ingest_fixture(source, plan)
+
+    # ---- fixture mode (legacy demo path) ---------------------------------
+
+    def _ingest_fixture(self, source: Source, plan: IngestionPlan) -> RunResult:
+        fixture = self._resolve_fixture(source, plan)
+        if fixture is None:
+            return RunResult(
+                status=RunStatus.FAILED,
+                message="no fixture source configured for this Databricks adapter instance",
+            )
+        if not fixture.exists():
+            return RunResult(
+                status=RunStatus.FAILED,
+                message=f"fixture not found: {fixture}",
+            )
+
+        start = time.monotonic()
+        catalog = self._catalog()
+        schema = plan.target.schema_name
+        table = plan.target.table_name
+        target_fq = _fq(catalog, schema, table)
+        volume = self.profile.get("ingest_volume", DEFAULT_INGEST_VOLUME)
+
+        try:
+            self.create_schema(schema)
+            remote_path = self._upload_to_volume(fixture, volume, source.name, fixture.name)
+            self._execute(
+                f"CREATE TABLE IF NOT EXISTS {target_fq} "
+                f"AS SELECT * FROM read_files(?, format => 'csv', header => true) LIMIT 0",
+                parameters=[remote_path],
+            )
+            self._execute(
+                f"COPY INTO {target_fq} "
+                f"FROM (SELECT * FROM read_files(?, format => 'csv', header => true)) "
+                f"FILEFORMAT = CSV "
+                f"COPY_OPTIONS ('mergeSchema' = 'true')",
+                parameters=[remote_path],
+            )
+            rows = self._scalar(f"SELECT COUNT(*) FROM {target_fq}")
+        except Exception as e:
+            return RunResult(
+                status=RunStatus.FAILED,
+                message=f"ingest failed: {e}",
+            )
+
+        return RunResult(
+            status=RunStatus.SUCCESS,
+            message=f"ingested {rows} rows into {catalog}.{schema}.{table}",
+            rows_affected=int(rows) if rows is not None else None,
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    # ---- landing_zone mode (real production path) -----------------------
+
+    def _ingest_landing_zone(self, source: Source, plan: IngestionPlan) -> RunResult:
+        """Drive bronze ingest off :class:`LandingStorage` (ADR 0046 phase 3).
+
+        The warehouse reads the landing bytes directly via ``read_files()``
+        against the URL the storage layer hands back — no pod-mediated
+        upload to Unity Catalog Volumes. ``move_to_raw`` rotates the file
+        atomically (rename on HNS-ADLS); the URL the warehouse consumes
+        is the post-rotation one, so the read targets a stable path.
+        """
+        ingestion = plan.effective_ingestion()
+        assert ingestion is not None
+
+        storage = self.landing_storage()
+        refs = list(storage.list(source.name, plan.table.physical_name))
+        if not refs:
+            return RunResult(
+                status=RunStatus.SKIPPED,
+                message=(f"no landing files for {source.name}/{plan.table.physical_name}"),
+            )
+
+        start = time.monotonic()
+        catalog = self._catalog()
+        schema = plan.target.schema_name
+        table = plan.target.table_name
+        target_fq = _fq(catalog, schema, table)
+        today = datetime.now(UTC).date()
+
+        self.create_schema(schema)
+
+        # Issue #366 — refuse to MERGE into a pre-ADR-0124 target.
+        # ``WHEN MATCHED THEN UPDATE SET *`` expands against the
+        # target's columns; a target carrying ``_dca_*`` meta cols
+        # would fail every file's MERGE and let bronze report 0 rows
+        # silently. The per-file ``except Exception`` loop in
+        # ``runner.py`` would catch and continue, masking the cause.
+        stale_meta = self._detect_stale_meta_columns(target_fq)
+        if stale_meta:
+            return RunResult(
+                status=RunStatus.FAILED,
+                message=str(StaleSchemaError(target_fq, stale_meta)),
+            )
+
+        files_ingested = 0
+        total_rows = 0
+        errors: list[str] = []
+
+        for ref in sorted(refs, key=lambda r: r.name):
+            try:
+                rows = self._merge_one_file(
+                    storage=storage,
+                    ref=ref,
+                    target_fq=target_fq,
+                    fmt=ingestion.format.value,
+                    dedupe_key=list(ingestion.dedupe_key),
+                    deleted_flag=ingestion.deleted_flag,
+                    today=today,
+                    json_shape=ingestion.json_shape,
+                )
+            except Exception as e:
+                errors.append(f"{ref.name}: {e}")
+                continue
+            files_ingested += 1
+            total_rows += rows
+
+        status = RunStatus.SUCCESS if not errors else RunStatus.FAILED
+        return RunResult(
+            status=status,
+            message=(
+                f"ingested {files_ingested} files ({total_rows} rows) "
+                f"into {catalog}.{schema}.{table}"
+                + (f" — errors: {len(errors)}; first: {errors[0]}" if errors else "")
+            ),
+            rows_affected=total_rows,
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    def _merge_one_file(
+        self,
+        *,
+        storage: Any,
+        ref: Any,
+        target_fq: str,
+        fmt: str,
+        dedupe_key: list[str],
+        deleted_flag: str | None,
+        today: date,
+        json_shape: str = "array",
+    ) -> int:
+        """Move landing → _raw, MERGE (or INSERT) the warehouse-native URL.
+
+        Phase 3: the warehouse reads from
+        ``storage.url_for_native_read(post_move_ref)`` directly. No
+        upload-to-volume — the bytes never traverse the control-plane
+        pod for ADLS-backed storage. The original landing basename is
+        preserved as ``source_file`` for audit attribution.
+
+        ``json_shape`` selects between ``multiLine=true`` (array /
+        single-object files) and ``multiLine=false`` (NDJSON, the
+        default integration-platform output). See
+        :func:`build_staging_select_sql` for the full mapping.
+        """
+        landing_name = ref.name
+        trace_id = uuid.uuid4().hex
+        raw_ref = storage.move_to_raw(ref, day=today)
+        remote = storage.url_for_native_read(raw_ref)
+
+        source_select = build_staging_select_sql(
+            volume_path=remote,
+            fmt=fmt,
+            source_file=landing_name,
+            trace_id=trace_id,
+            deleted_flag=deleted_flag,
+            today=today,
+            json_shape=json_shape,
+        )
+
+        # First run creates an empty table with the right schema.
+        self._execute(
+            build_create_table_sql(
+                target_fq=target_fq,
+                source_select=source_select,
+            )
+        )
+
+        if dedupe_key:
+            sql = build_merge_sql(
+                target_fq=target_fq,
+                source_select=source_select,
+                dedupe_key=dedupe_key,
+            )
+        else:
+            sql = build_append_sql(
+                target_fq=target_fq,
+                source_select=source_select,
+            )
+        self._execute(sql)
+
+        rows = self._scalar(f"SELECT COUNT(*) FROM ({source_select}) s")
+        return int(rows) if rows is not None else 0
+
+    def query(self, sql: str, parameters: list[Any] | None = None) -> QueryResult:
+        """Run a read-only query via the Statement Execution API.
+
+        Column names aren't returned by the SDK's simple data_array path;
+        we fall back to `col_1, col_2, …` if column metadata isn't exposed.
+        """
+        from databricks.sdk.service.sql import StatementState
+
+        ws = self._workspace()
+        response = ws.statement_execution.execute_statement(
+            statement=sql,
+            warehouse_id=self._warehouse_id(),
+            parameters=[{"value": p, "type": "STRING"} for p in (parameters or [])] or None,
+            wait_timeout="30s",
+        )
+        state = response.status.state if response.status else None
+        if state != StatementState.SUCCEEDED:
+            raise RuntimeError(
+                f"Query did not succeed: state={state}, "
+                f"error={getattr(response.status, 'error', None)}"
+            )
+
+        # Try to pull column names from the manifest; fall back gracefully.
+        col_names: list[str]
+        manifest = getattr(response, "manifest", None)
+        if manifest and manifest.schema and manifest.schema.columns:
+            col_names = [c.name for c in manifest.schema.columns]
+        else:
+            width = (
+                len(response.result.data_array[0])
+                if response.result and response.result.data_array
+                else 0
+            )
+            col_names = [f"col_{i}" for i in range(width)]
+
+        data = [tuple(r) for r in (response.result.data_array or [])] if response.result else []
+        return QueryResult(columns=col_names, rows=data)
+
+    def execute(self, sql: str, parameters: list[Any] | None = None) -> RunResult:
+        """Run a write statement via the Statement Execution API."""
+        start = time.monotonic()
+        try:
+            self._execute(sql, parameters=parameters)
+        except Exception as e:
+            return RunResult(
+                status=RunStatus.FAILED,
+                message=f"execute failed: {e}",
+                duration_ms=int((time.monotonic() - start) * 1000),
+            )
+        return RunResult(
+            status=RunStatus.SUCCESS,
+            message="ok",
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    def describe_table(self, ref: TableRef) -> TableDescription:
+        catalog = self._catalog()
+        cols_rows = self._execute(
+            "SELECT column_name, full_data_type, is_nullable "
+            "FROM system.information_schema.columns "
+            "WHERE table_catalog = ? AND table_schema = ? AND table_name = ? "
+            "ORDER BY ordinal_position",
+            parameters=[catalog, ref.schema_name, ref.table_name],
+        )
+        columns = [
+            ColumnDescription(name=n, data_type=t, nullable=(nullable == "YES"))
+            for (n, t, nullable) in (cols_rows or [])
+        ]
+        fq_table = _fq(catalog, ref.schema_name, ref.table_name)
+        row_count = self._row_count_describe_detail(fq_table)
+        if row_count is None:
+            row_count = self._row_count_count_star(fq_table)
+        return TableDescription(ref=ref, row_count=row_count, columns=columns)
+
+    def describe_annotations(self, ref: TableRef) -> LiveTableAnnotations:
+        """Read live comments + tags from Unity Catalog (ADR 0131 verify).
+
+        All four reads go through ``system.information_schema`` (the same
+        metastore view ``describe_table`` uses), so no new auth surface and
+        no Spark-cluster dependency — a SQL warehouse is enough:
+
+        * ``tables.comment`` / ``columns.comment`` → comments
+        * ``table_tags`` / ``column_tags`` → governance tags
+
+        Tags are returned verbatim; the verify engine scopes the comparison
+        to the contract-managed ``kiri_*`` keys so unrelated operator tags are
+        never mistaken for drift. ``tags_supported`` is always ``True`` here.
+        """
+        catalog = self._catalog()
+
+        table_comment: str | None = None
+        tbl_rows = self._execute(
+            "SELECT comment FROM system.information_schema.tables "
+            "WHERE table_catalog = ? AND table_schema = ? AND table_name = ?",
+            parameters=[catalog, ref.schema_name, ref.table_name],
+        )
+        if tbl_rows and tbl_rows[0]:
+            table_comment = tbl_rows[0][0]
+
+        col_rows = self._execute(
+            "SELECT column_name, comment FROM system.information_schema.columns "
+            "WHERE table_catalog = ? AND table_schema = ? AND table_name = ?",
+            parameters=[catalog, ref.schema_name, ref.table_name],
+        )
+        columns: dict[str, LiveColumnAnnotation] = {}
+        for name, comment in col_rows or []:
+            columns[name] = LiveColumnAnnotation(comment=comment, tags={})
+
+        tbl_tag_rows = self._execute(
+            "SELECT tag_name, tag_value FROM system.information_schema.table_tags "
+            "WHERE catalog_name = ? AND schema_name = ? AND table_name = ?",
+            parameters=[catalog, ref.schema_name, ref.table_name],
+        )
+        table_tags = {k: ("" if v is None else str(v)) for (k, v) in (tbl_tag_rows or [])}
+
+        col_tag_rows = self._execute(
+            "SELECT column_name, tag_name, tag_value "
+            "FROM system.information_schema.column_tags "
+            "WHERE catalog_name = ? AND schema_name = ? AND table_name = ?",
+            parameters=[catalog, ref.schema_name, ref.table_name],
+        )
+        for col_name, tag_name, tag_value in col_tag_rows or []:
+            existing = columns.get(col_name)
+            tag_val = "" if tag_value is None else str(tag_value)
+            if existing is None:
+                # A column with a tag but no row in the columns read is
+                # unexpected, but record it rather than drop the tag silently.
+                columns[col_name] = LiveColumnAnnotation(comment=None, tags={tag_name: tag_val})
+            else:
+                columns[col_name] = existing.model_copy(
+                    update={"tags": {**existing.tags, tag_name: tag_val}}
+                )
+
+        return LiveTableAnnotations(
+            ref=ref,
+            table_comment=table_comment,
+            table_tags=table_tags,
+            columns=columns,
+            tags_supported=True,
+        )
+
+    def _row_count_describe_detail(self, fq_table: str) -> int | None:
+        """N3: prefer ``DESCRIBE DETAIL`` when ``numRecords`` is present.
+
+        Recent Databricks runtimes (and Delta tables with stats
+        collection enabled) include ``numRecords`` in
+        ``DESCRIBE DETAIL``'s output. That's a metadata read — bounded
+        cost regardless of table size, vs ``COUNT(*)`` which can scan
+        billions of files on stats-disabled tables. Falls back to
+        ``COUNT(*)`` when the field is absent.
+
+        Returns ``None`` when DESCRIBE DETAIL doesn't yield a row,
+        the column is missing, or the value is ``NULL`` — caller
+        falls through to ``_row_count_count_star``.
+        """
+        try:
+            rows = self._execute(f"DESCRIBE DETAIL {fq_table}")
+        except Exception:
+            return None
+        if not rows or not rows[0]:
+            return None
+        # The result columns vary by Databricks Runtime version.
+        # We can't introspect column names from the SDK's data_array
+        # response without manifest metadata; instead we look for an
+        # int-typed value with magnitude consistent with a row count.
+        # The shape we expect is: (format, id, name, description,
+        # location, ..., numFiles, sizeInBytes, ..., numRecords?).
+        # Newer DBR returns ``numRecords`` as a typed long.
+        # Heuristic: scan the row for a non-negative integer that's
+        # reasonably-bounded (< 2^60); pick the *last* such value
+        # because numRecords (when present) is appended after older
+        # columns. False positives are caught by the fallback path —
+        # COUNT(*) is the source of truth, this is just an
+        # optimisation when we can avoid it cheaply.
+        candidate: int | None = None
+        for value in rows[0]:
+            if isinstance(value, int) and not isinstance(value, bool) and value >= 0:
+                candidate = value
+        return candidate
+
+    def _row_count_count_star(self, fq_table: str) -> int | None:
+        """Slow-path row count — Delta optimises ``SELECT COUNT(*)``
+        to a metadata aggregation in most cases, but very large
+        non-stats-collected tables still pay file-scan cost. Wrapped
+        so a permission denial doesn't block ``describe_table``.
+        """
+        try:
+            value = self._scalar(f"SELECT COUNT(*) FROM {fq_table}")
+            return int(value) if value is not None else None
+        except Exception:
+            return None
+
+    def supports(self, capability: str) -> bool:
+        return capability in {
+            "unity-catalog",
+            "delta-lake",
+            "managed-volumes",
+            "sql-merge",
+            "time-travel",
+        }
+
+    # ---- maintenance -----------------------------------------------------
+
+    def optimize(self, source_name: str, table_physical_name: str) -> RunResult:
+        catalog = self._catalog()
+        target = _fq(catalog, f"bronze_{source_name}", table_physical_name)
+        start = time.monotonic()
+        try:
+            self._execute(f"OPTIMIZE {target}")
+        except Exception as e:
+            return RunResult(status=RunStatus.FAILED, message=f"OPTIMIZE failed: {e}")
+        return RunResult(
+            status=RunStatus.SUCCESS,
+            message=f"optimized {target}",
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    def vacuum(
+        self,
+        source_name: str,
+        table_physical_name: str,
+        *,
+        retention_hours: int = 168,
+        dry_run: bool = False,
+        enforce_retention: bool = True,
+    ) -> RunResult:
+        catalog = self._catalog()
+        target = _fq(catalog, f"bronze_{source_name}", table_physical_name)
+        clause = f"RETAIN {retention_hours} HOURS"
+        suffix = " DRY RUN" if dry_run else ""
+        start = time.monotonic()
+        # N4: ``SET spark.databricks.delta.retentionDurationCheck.enabled
+        # = false`` is a session-scoped flag — without an explicit
+        # restore, the next statement that re-uses the warehouse
+        # session inherits the relaxed check. Always restore the
+        # default ``true`` after a vacuum that flipped it, even when
+        # the VACUUM itself raises.
+        flag_was_flipped = False
+        try:
+            if not enforce_retention:
+                self._execute("SET spark.databricks.delta.retentionDurationCheck.enabled = false")
+                flag_was_flipped = True
+            self._execute(f"VACUUM {target} {clause}{suffix}")
+        except Exception as e:
+            return RunResult(status=RunStatus.FAILED, message=f"VACUUM failed: {e}")
+        finally:
+            if flag_was_flipped:
+                # Best-effort restore — a failure here is logged via
+                # ``_execute``'s normal path but does not turn a
+                # successful vacuum into a failed RunResult.
+                import contextlib
+
+                with contextlib.suppress(Exception):
+                    self._execute(
+                        "SET spark.databricks.delta.retentionDurationCheck.enabled = true"
+                    )
+        verb = "would vacuum" if dry_run else "vacuumed"
+        return RunResult(
+            status=RunStatus.SUCCESS,
+            message=f"{verb} {target} (retention={retention_hours}h)",
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    def apply_retention(
+        self,
+        table_fqn: str,
+        days: int,
+        *,
+        dry_run: bool = False,
+    ) -> RetentionReport:
+        """Dispatch Delta VACUUM + ``delta.logRetentionDuration`` (ADR 0114 §4).
+
+        ``table_fqn`` is the canonical ``<schema>.<table>``; Databricks
+        runs in the configured catalog (``profile['catalog']``) so the
+        adapter prefixes it on the way to SQL. Retention is recorded
+        twice — as a TBLPROPERTIES setting so Delta's own expiry math
+        respects the contract value, and as a VACUUM that physically
+        removes the now-out-of-window files. Both are idempotent.
+        """
+        if days <= 0:
+            raise ValueError(f"retention days must be positive, got {days!r}")
+        catalog = self._catalog()
+        # Accept either ``schema.table`` or a pre-qualified
+        # ``catalog.schema.table`` — the latter is what operators
+        # might paste from describe output.
+        parts = table_fqn.split(".")
+        if len(parts) == 2:
+            qualified = f"`{catalog}`.`{parts[0]}`.`{parts[1]}`"
+        elif len(parts) == 3:
+            qualified = ".".join(f"`{p}`" for p in parts)
+        else:
+            raise ValueError(
+                f"table_fqn must be 'schema.table' or 'catalog.schema.table', got {table_fqn!r}"
+            )
+        retention_hours = days * 24
+        set_tblprops = (
+            f"ALTER TABLE {qualified} SET TBLPROPERTIES "
+            f"('delta.logRetentionDuration' = 'interval {days} days')"
+        )
+        vacuum_stmt = f"VACUUM {qualified} RETAIN {retention_hours} HOURS"
+        if dry_run:
+            vacuum_stmt += " DRY RUN"
+        commands = [set_tblprops, vacuum_stmt]
+        if dry_run:
+            return RetentionReport(
+                action=RetentionAction.PREVIEWED,
+                mechanism="VACUUM",
+                table_fqn=table_fqn,
+                days=days,
+                commands=commands,
+                message=f"would apply retention={days}d ({retention_hours}h) on {table_fqn}",
+            )
+        start = time.monotonic()
+        try:
+            self._execute(set_tblprops)
+            self._execute(vacuum_stmt)
+        except Exception as e:
+            return RetentionReport(
+                action=RetentionAction.FAILED,
+                mechanism="VACUUM",
+                table_fqn=table_fqn,
+                days=days,
+                commands=commands,
+                message=f"retention dispatch failed: {e}",
+                duration_ms=int((time.monotonic() - start) * 1000),
+            )
+        return RetentionReport(
+            action=RetentionAction.APPLIED,
+            mechanism="VACUUM",
+            table_fqn=table_fqn,
+            days=days,
+            commands=commands,
+            message=f"applied retention={days}d ({retention_hours}h) on {table_fqn}",
+            duration_ms=int((time.monotonic() - start) * 1000),
+        )
+
+    def history(
+        self, source_name: str, table_physical_name: str, limit: int = 10
+    ) -> list[dict[str, Any]]:
+        """Return DESCRIBE HISTORY rows as dicts."""
+        catalog = self._catalog()
+        target = _fq(catalog, f"bronze_{source_name}", table_physical_name)
+        try:
+            rows = self._execute(f"DESCRIBE HISTORY {target} LIMIT {int(limit)}")
+        except Exception:
+            return []
+        if not rows:
+            return []
+        # DESCRIBE HISTORY returns named columns; the statement API doesn't
+        # give us names here, so we shape the rows generically.
+        return [
+            {"version": r[0], "timestamp": r[1], "operation": r[5]} if len(r) >= 6 else {"row": r}
+            for r in rows
+        ]
+
+    # ---- internals -------------------------------------------------------
+
+    def _catalog(self) -> str:
+        return str(self.profile.get("catalog", DEFAULT_CATALOG))
+
+    def _warehouse_id(self) -> str:
+        wh = self.profile.get("warehouse_id") or os.environ.get("DATABRICKS_WAREHOUSE_ID")
+        if not wh:
+            raise RuntimeError(
+                "Databricks adapter requires warehouse_id in profile "
+                "or DATABRICKS_WAREHOUSE_ID in env."
+            )
+        return str(wh)
+
+    def _workspace(self) -> Any:
+        """Construct a WorkspaceClient with one of three auth modes.
+
+        Priority (per profile / env):
+
+        1. **OAuth M2M** (service principal) — ``client_id`` + ``client_secret``.
+           Production-grade; rotation lives in the IdP.
+        2. **PAT** (legacy) — ``token``. Easiest dev setup; rotation
+           manual via Databricks UI.
+        3. **SDK default auth chain** — neither in profile nor env;
+           SDK falls back to azure-cli / databricks-cli / managed
+           identity. Useful for AKS pods running with workload
+           identity bound to the SP.
+
+        S9: when ``KIRIMANA_DATABRICKS_AUTH_MODE`` is set, the
+        constructor asserts that the auto-picked mode matches and
+        raises if it doesn't. Lets operators express the expected
+        deploy-time auth posture (e.g. "this Helm release MUST run
+        OAuth M2M, never PAT") and catch drift early.
+        """
+        if self._client is None:
+            from databricks.sdk import WorkspaceClient
+
+            picked = self._auth_mode()
+            expected = os.environ.get("KIRIMANA_DATABRICKS_AUTH_MODE")
+            if expected and expected != picked:
+                raise RuntimeError(
+                    f"KIRIMANA_DATABRICKS_AUTH_MODE={expected!r} but adapter "
+                    f"would use {picked!r}. Either remove the env, change the "
+                    "profile / env credentials to match, or set the env to "
+                    f"{picked!r} after verifying."
+                )
+
+            host = self.profile.get("host") or os.environ.get("DATABRICKS_HOST")
+            client_id = self.profile.get("client_id") or os.environ.get("DATABRICKS_CLIENT_ID")
+            client_secret = self.profile.get("client_secret") or os.environ.get(
+                "DATABRICKS_CLIENT_SECRET"
+            )
+            token = self.profile.get("token") or os.environ.get("DATABRICKS_TOKEN")
+
+            if client_id and client_secret:
+                self._client = WorkspaceClient(
+                    host=host,
+                    client_id=client_id,
+                    client_secret=client_secret,
+                )
+            elif token:
+                self._client = WorkspaceClient(host=host, token=token)
+            else:
+                # Default chain: azure-cli, workload identity, ~/.databrickscfg.
+                self._client = WorkspaceClient(host=host)
+        return self._client
+
+    def _wait_timeout(self) -> str:
+        """Configurable per-statement wait timeout.
+
+        Default 30s preserves legacy behaviour. Big MERGE on 10M+ rows
+        easily exceeds — operators raise this in kiri.yml profile to
+        match their warehouse + data size:
+
+            targets:
+              prod:
+                adapter: databricks
+                wait_timeout: "180s"   # 3 minutes
+
+        Databricks API caps at ``50s`` for ``wait_timeout`` parameter
+        on /statement-execution; longer values trigger async-mode
+        statements where the SDK polls under the hood. The SDK
+        handles the polling transparently.
+        """
+        value = self.profile.get("wait_timeout", "30s")
+        # Tolerate plain ints — convert to seconds.
+        if isinstance(value, int | float):
+            return f"{int(value)}s"
+        return str(value)
+
+    @staticmethod
+    def _db_type_for(value: Any) -> str:
+        """Map a Python value to Databricks Statement API parameter type.
+
+        Falls back to STRING for unknown types — Databricks coerces
+        most things server-side, but typed ints/booleans/dates avoid
+        a class of MERGE-predicate bugs (``"5" = 5`` is false in
+        strict mode).
+        """
+        # bool first — bool is a subclass of int.
+        if isinstance(value, bool):
+            return "BOOLEAN"
+        if isinstance(value, int):
+            # Python ints are unbounded; Databricks Spark INT is signed
+            # 32-bit (-2^31..2^31-1). Many real-world ID columns (MSSQL
+            # ``bigint``, epoch-ns timestamps, accumulator counters)
+            # exceed that range, and an out-of-range INT parameter on
+            # the Statement Execution API returns a hard cast error.
+            # BIGINT (signed 64-bit) is a safe superset; Spark casts
+            # BIGINT → INT implicitly where the target column is
+            # narrower, so widening here costs nothing and prevents
+            # overflow on the load-bearing path. Live-found 2026-05-23.
+            #
+            # CODEX-FINAL-V2 P2: refuse values outside the 64-bit range
+            # rather than serialising a BIGINT that the Statement API
+            # will reject server-side with an opaque cast error. The
+            # caller can switch to Decimal/string binding if they
+            # genuinely need wider integers (rare for migration data).
+            if not -(2**63) <= value <= 2**63 - 1:
+                raise OverflowError(
+                    f"int value {value!r} is outside Spark BIGINT range "
+                    f"(-2**63..2**63-1); rebind as a Decimal or string "
+                    f"parameter, or narrow the value before passing it to "
+                    f"the Databricks Statement Execution API."
+                )
+            return "BIGINT"
+        if isinstance(value, float):
+            return "DOUBLE"
+        if isinstance(value, datetime):
+            return "TIMESTAMP"
+        if isinstance(value, date):
+            return "DATE"
+        # str + everything else → STRING.
+        return "STRING"
+
+    def _execute(
+        self, sql: str, parameters: list[Any] | None = None
+    ) -> list[tuple[Any, ...]] | None:
+        """Run a statement with typed params + transient-error retry.
+
+        Retries up to 3 times on 429 / 503 / connection errors with
+        exponential backoff (0.5s, 1s, 2s). Hard errors (4xx that's
+        not 429, semantic SQL failures) raise immediately — retrying
+        a CREATE TABLE that's malformed won't help.
+
+        ADR 0049: prepends a structured trace-id comment so the
+        Databricks audit log carries ``kiri_trace_id`` /
+        ``apply_id`` / ``release_sha`` / ``caller`` in
+        ``statement_text``. The Kirimana side issued the same id
+        in its own audit; ``kiri audit join`` matches the two.
+        """
+        from databricks.sdk.service.sql import (
+            StatementParameterListItem,
+            StatementState,
+        )
+
+        # Prepend the trace comment first; the kirimana-prepended
+        # comment must lead so the audit-log parser doesn't
+        # collide with user-authored ``/* ... */`` content downstream
+        # (e.g. dbt-rendered SQL that already starts with comments).
+        sql = current_trace().sql_comment() + " " + sql
+
+        # The Databricks Statement Execution API supports only *named*
+        # parameter markers (``:p0``); positional ``?`` is sent unbound
+        # and rejected with UNBOUND_SQL_PARAMETER. Callers use ``?``, so
+        # rewrite each positional marker to ``:pN`` in lockstep with the
+        # named params here — ``?`` inside single-quoted literals is left
+        # untouched.
+        params_list = list(parameters or [])
+        if params_list:
+            out: list[str] = []
+            in_str = False
+            marker = 0
+            for ch in sql:
+                if ch == "'":
+                    in_str = not in_str
+                    out.append(ch)
+                elif ch == "?" and not in_str:
+                    out.append(f":p{marker}")
+                    marker += 1
+                else:
+                    out.append(ch)
+            if marker != len(params_list):
+                raise ValueError(
+                    f"parameter count mismatch: SQL has {marker} '?' "
+                    f"markers but {len(params_list)} parameters were given."
+                )
+            sql = "".join(out)
+
+        # The SDK serialises each item via ``.as_dict()``; it must be a
+        # ``StatementParameterListItem``, not a raw dict.
+        typed_params = [
+            StatementParameterListItem(
+                name=f"p{i}",
+                value=str(p) if not isinstance(p, str) else p,
+                type=self._db_type_for(p),
+            )
+            for i, p in enumerate(params_list)
+        ] or None
+
+        ws = self._workspace()
+        self._gate_rate_limit()
+        max_attempts = self._retry_attempts
+        backoff_base = self._retry_backoff_base
+        last_error: Exception | None = None
+        attempts_used = 0
+        started_at = time.monotonic()
+        response = None
+        for attempt in range(max_attempts):
+            attempts_used = attempt + 1
+            try:
+                response = ws.statement_execution.execute_statement(
+                    statement=sql,
+                    warehouse_id=self._warehouse_id(),
+                    catalog=self._catalog(),
+                    parameters=typed_params,
+                    wait_timeout=self._wait_timeout(),
+                )
+                break
+            except Exception as e:
+                if not self._is_transient(e):
+                    self._emit_audit(
+                        sql=sql,
+                        duration_ms=int((time.monotonic() - started_at) * 1000),
+                        attempts=attempts_used,
+                        status="failed",
+                        error_class=type(e).__name__,
+                    )
+                    raise
+                last_error = e
+                if attempt < max_attempts - 1:
+                    time.sleep(backoff_base * (2**attempt))
+        else:
+            # All retries exhausted on transient errors.
+            self._emit_audit(
+                sql=sql,
+                duration_ms=int((time.monotonic() - started_at) * 1000),
+                attempts=attempts_used,
+                status="failed",
+                error_class=type(last_error).__name__ if last_error else "Unknown",
+            )
+            raise RuntimeError(
+                f"Statement failed after {max_attempts} attempts (transient errors): {last_error}"
+            ) from last_error
+
+        assert response is not None
+        state = response.status.state if response.status else None
+        if state != StatementState.SUCCEEDED:
+            self._emit_audit(
+                sql=sql,
+                duration_ms=int((time.monotonic() - started_at) * 1000),
+                attempts=attempts_used,
+                status="failed",
+                error_class="UnsuccessfulState",
+            )
+            raise RuntimeError(
+                f"Statement did not succeed: state={state}, "
+                f"error={getattr(response.status, 'error', None)}"
+            )
+
+        self._emit_audit(
+            sql=sql,
+            duration_ms=int((time.monotonic() - started_at) * 1000),
+            attempts=attempts_used,
+            status="success",
+            error_class=None,
+        )
+
+        if response.result and response.result.data_array:
+            return [tuple(row) for row in response.result.data_array]
+        return None
+
+    def _emit_audit(
+        self,
+        *,
+        sql: str,
+        duration_ms: int,
+        attempts: int,
+        status: str,
+        error_class: str | None,
+    ) -> None:
+        """Append one ADR 0092 audit record rendered as log + JSONL."""
+
+        enabled, _disabled_reason = self._audit_enabled()
+        if not enabled:
+            if not self._audit_disabled_emitted:
+                self._audit_disabled_emitted = True
+                _emit_databricks_audit_record(
+                    profile=self.profile,
+                    paths=self._audit_paths,
+                    event="AUDIT_DISABLED",
+                    target="?",
+                    status="failed",
+                    duration_ms=0,
+                    attempts=0,
+                    warehouse_id=self.profile.get("warehouse_id"),
+                    via="adapter",
+                    user=self._current_user(),
+                    error_class=None,
+                    statement_preview=_redact_preview(_strip_leading_trace_comment(sql)),
+                )
+            return
+        _emit_databricks_audit_record(
+            profile=self.profile,
+            paths=self._audit_paths,
+            event=databricks_audit_event(sql),
+            target=databricks_audit_target(sql),
+            status=status,
+            duration_ms=duration_ms,
+            attempts=attempts,
+            warehouse_id=self.profile.get("warehouse_id"),
+            via="adapter",
+            user=self._current_user(),
+            error_class=error_class,
+            statement_preview=_redact_preview(_strip_leading_trace_comment(sql)),
+        )
+
+    def _write_audit_record(self, record: _AuditRecord) -> None:
+        _write_audit_record(self._audit_paths, record)
+
+    def _write_audit_line(self, record: _AuditRecord) -> None:
+        _write_audit_line(self._audit_paths, record)
+
+    def _write_audit_jsonl(self, record: _AuditRecord) -> None:
+        _write_audit_jsonl(self._audit_paths, record)
+
+    def _audit_enabled(self) -> tuple[bool, str | None]:
+        return databricks_audit_enabled(self.profile)
+
+    @staticmethod
+    def _resolve_audit_paths(profile: dict[str, Any]) -> _AuditPaths:
+        return _resolve_databricks_audit_paths(profile)
+
+    def _current_user(self) -> str:
+        if self._audit_user is not None:
+            return self._audit_user
+        try:
+            ws = self._workspace()
+            response = ws.statement_execution.execute_statement(
+                statement="SELECT current_user()",
+                warehouse_id=self._warehouse_id(),
+                wait_timeout=self._wait_timeout(),
+            )
+            user = _extract_current_user(response)
+        except Exception:
+            user = "unknown"
+        self._audit_user = user or "unknown"
+        return self._audit_user
+
+    def _gate_rate_limit(self) -> None:
+        """Throttle Statement Execution API calls to ``statement_rps_limit``.
+
+        S8: belt-and-braces against self-DoS. The Databricks SDK
+        already retries 429s, but a tight ``kiri apply`` loop on a
+        small warehouse can produce sustained 429-storms that waste
+        the retry budget on every statement. This token-bucket
+        sleeps the *next* call so the gap between calls honours the
+        configured rate. Off by default (no profile knob set), so
+        existing setups see no behaviour change.
+        """
+        if self._rps_limit is None:
+            return
+        min_interval = 1.0 / self._rps_limit
+        now = time.monotonic()
+        wait = min_interval - (now - self._last_call_at)
+        if wait > 0:
+            time.sleep(wait)
+            now = time.monotonic()
+        self._last_call_at = now
+
+    def _auth_mode(self) -> str:
+        """Return the auth mode picked for the workspace client.
+
+        S9: makes the silent auth-priority decision observable.
+        Operators can read ``adapter._auth_mode()`` (or set
+        ``KIRIMANA_DATABRICKS_AUTH_MODE`` to assert) without reading
+        the SDK's auth chain implementation.
+        """
+        if self.profile.get("client_id") and self.profile.get("client_secret"):
+            return "oauth_m2m"
+        if os.environ.get("DATABRICKS_CLIENT_ID") and os.environ.get("DATABRICKS_CLIENT_SECRET"):
+            return "oauth_m2m"
+        if self.profile.get("token") or os.environ.get("DATABRICKS_TOKEN"):
+            return "pat"
+        return "default_chain"
+
+    @staticmethod
+    def _is_transient(exc: Exception) -> bool:
+        """Classify transient failures by SDK exception type, with
+        message-based fallback for transport-layer errors.
+
+        S5: the SDK exposes typed exceptions in
+        ``databricks.sdk.errors`` that map to specific HTTP /
+        platform conditions. Catching the type is robust to SDK
+        message changes; the legacy string match was brittle as the
+        SDK kept evolving its error wrappers.
+
+        Transport-level errors (``requests.exceptions.*``,
+        ``urllib3``) don't go through the SDK error mapper; for those
+        we keep a narrow message-based fallback.
+        """
+        try:
+            from databricks.sdk.errors import (
+                DeadlineExceeded,
+                InternalError,
+                OperationTimeout,
+                RequestLimitExceeded,
+                TemporarilyUnavailable,
+                TooManyRequests,
+            )
+        except ImportError:
+            # SDK not installed (unlikely on the Databricks adapter
+            # path; keeps the classifier callable in tests that stub
+            # the SDK away).
+            transient_sdk_types: tuple[type[Exception], ...] = ()
+        else:
+            transient_sdk_types = (
+                TooManyRequests,
+                RequestLimitExceeded,
+                TemporarilyUnavailable,
+                DeadlineExceeded,
+                OperationTimeout,
+                InternalError,
+            )
+
+        if transient_sdk_types and isinstance(exc, transient_sdk_types):
+            return True
+
+        # Transport-layer fallback. The SDK doesn't wrap connection
+        # resets / DNS timeouts / TLS hiccups; those raise from
+        # ``urllib3`` / ``requests`` directly. Narrow on purpose — the
+        # safety net for "request never reached the SDK error mapper,"
+        # not a general string-matcher.
+        msg = str(exc).lower()
+        if "connection" in msg and ("reset" in msg or "aborted" in msg):
+            return True
+        return "timeout" in msg and ("connect" in msg or "read" in msg)
+
+    def _scalar(self, sql: str) -> Any:
+        rows = self._execute(sql)
+        if not rows:
+            return None
+        return rows[0][0]
+
+    def _detect_stale_meta_columns(self, target_fq: str) -> list[str]:
+        """Return ``_dca_*`` meta column names on ``target_fq`` if any survive.
+
+        Used by ``_ingest_landing_zone`` as a one-shot pre-MERGE guard
+        (issue #366). Returns ``[]`` if the table doesn't exist yet
+        (``CREATE TABLE IF NOT EXISTS`` runs immediately after this in
+        ``_merge_one_file``) or if every meta column is already
+        renamed.
+        """
+        try:
+            rows = self._execute(f"DESCRIBE TABLE {target_fq}")
+        except Exception:
+            # Most commonly: TABLE_OR_VIEW_NOT_FOUND. CREATE TABLE IF
+            # NOT EXISTS will run next; no stale schema to guard.
+            return []
+        return _stale_meta_columns_from_describe(rows)
+
+    def _resolve_fixture(self, source: Source, plan: IngestionPlan) -> Path | None:
+        fixtures_dir = self.profile.get("fixtures_dir")
+        if not fixtures_dir:
+            return None
+        return Path(fixtures_dir) / source.name / f"{plan.table.physical_name}.csv"
+
+    def _upload_to_volume(
+        self, local_path: Path, volume: str, source_name: str, filename: str
+    ) -> str:
+        """Upload one local file to a UC Volume (legacy fixture path).
+
+        ADR 0049: the SDK doesn't expose a per-call User-Agent
+        override on ``files.upload()``; instead we set
+        ``Config.user_agent_extra`` once on the WorkspaceClient so
+        every Files API call carries the active trace context
+        in its outgoing User-Agent header. The Files API audit log
+        captures ``user_agent`` verbatim — auditors recover the
+        trace-id from there.
+        """
+        parts = volume.split(".")
+        if len(parts) != 3:
+            raise ValueError(f"ingest_volume must be catalog.schema.volume (got {volume!r})")
+        remote = f"/Volumes/{parts[0]}/{parts[1]}/{parts[2]}/{source_name}/{filename}"
+        ws = self._workspace()
+        # Per-upload trace stamp on the SDK's user-agent. SDK reads
+        # this attribute on every outgoing request, so updating it
+        # here propagates to the very next ``upload`` call without
+        # reconstructing the client. Restored to the prior value on
+        # function exit so concurrent callers don't see leaked state.
+        prior_ua_extra = getattr(ws.config, "user_agent_extra", "")
+        ws.config.user_agent_extra = current_trace().user_agent()
+        try:
+            with local_path.open("rb") as f:
+                ws.files.upload(remote, f, overwrite=True)
+        finally:
+            ws.config.user_agent_extra = prior_ua_extra
+        return remote