wherobots-dbt 0.1.0__py3-none-any.whl

dbt/adapters/wherobots/__init__.py

@@ -0,0 +1,35 @@
+"""dbt plugin shim for the Wherobots adapter.
+
+dbt discovers adapters at ``dbt.adapters.<name>``, but the implementation lives in the top-level
+``dbt_wherobots`` package (see that package's docstring for why). This module is the thin bridge: it
+exposes the dbt ``AdapterPlugin`` wiring the adapter, the credentials, and the include package path.
+
+No ``dependencies`` are declared (clean-room): the adapter dispatches to ``default__`` macros in
+dbt's global project rather than depending on another adapter's project. The plugin's
+``project_name`` defaults to ``dbt_<include-dir-name>`` (``dbt_wherobots``), which must equal the
+``name`` in ``dbt/include/wherobots/dbt_project.yml`` so dbt loads the macro library (plan §10 F1).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from dbt.adapters.base import AdapterPlugin
+
+from dbt.include import wherobots
+from dbt_wherobots.credentials import WherobotsCredentials
+from dbt_wherobots.impl import WherobotsAdapter
+
+if TYPE_CHECKING:
+    from dbt.adapters.protocol import AdapterProtocol
+
+# dbt's ``AdapterProtocol`` (TODO CT-211 upstream) declares connection-manager methods such as
+# ``set_query_header`` directly on the adapter, so no real ``SQLAdapter`` subclass satisfies it
+# structurally — every adapter only delegates to its manager. ``cast`` is the typed bridge across
+# that upstream imprecision (not an inline suppression): ``WherobotsAdapter`` is the concrete
+# adapter the registry instantiates.
+Plugin = AdapterPlugin(
+    adapter=cast("type[AdapterProtocol[Any, Any, Any, Any]]", WherobotsAdapter),
+    credentials=WherobotsCredentials,
+    include_path=str(wherobots.PACKAGE_PATH),
+)

dbt/adapters/wherobots/__version__.py

@@ -0,0 +1,11 @@
+"""Adapter version for dbt's plugin registry.
+
+dbt's adapter factory reads ``dbt.adapters.<name>.__version__.version`` (falling back from
+``__about__``) to record the adapter version in run metadata. dbt validates this as a strict
+semantic version (``dbt_common.semver``), so it tracks the release line of the package version in
+``pyproject.toml`` without the PEP 440 ``.devN`` suffix that semver rejects.
+"""
+
+from __future__ import annotations
+
+version = "0.1.0"

dbt/include/wherobots/__init__.py

@@ -0,0 +1,5 @@
+"""dbt include package for wherobots (macros + project scaffolding land in M1+)."""
+
+from pathlib import Path
+
+PACKAGE_PATH = Path(__file__).parent

dbt/include/wherobots/dbt_project.yml

@@ -0,0 +1,3 @@
+name: dbt_wherobots
+config-version: 2
+macro-paths: ["macros"]

dbt/include/wherobots/macros/adapters.sql

@@ -0,0 +1,240 @@
+{#
+  Wherobots dialect macros (component #7) — schema/relation/column metadata.
+
+  Pinned to the live-wire facts (plan §3) and ADR-0007a (stateless, backtick-quoted,
+  fully-qualified rendering — no USE). SHOW/DESCRIBE parsing lives here in Jinja by design
+  (plan §4); cosmic-ray mutates Python only, so the acceptance/functional assertions are the
+  sole guard on these macros (plan §10 F6) and are deliberately discriminating.
+#}
+
+
+{% macro wherobots__create_schema(relation) -%}
+  {#- Fact 1: a fully-qualified create succeeds cold; `if not exists` is idempotent. -#}
+  {%- call statement('create_schema') -%}
+    create schema if not exists {{ relation.without_identifier() }}
+  {%- endcall -%}
+{%- endmacro %}
+
+
+{% macro wherobots__drop_schema(relation) -%}
+  {#- Fact 10: dropping an empty schema needs no CASCADE (dbt drops relations first). -#}
+  {%- call statement('drop_schema') -%}
+    drop schema if exists {{ relation.without_identifier() }}
+  {%- endcall -%}
+{%- endmacro %}
+
+
+{% macro wherobots__drop_relation(relation) -%}
+  {#-
+    V4 / ADR-0010(b): DROP is type-segregated — a wrong-type `drop ... if exists` is a SILENT NO-OP
+    (the object survives — a leak). So branch on `relation.is_view` to emit `drop view if exists`
+    for a view and `drop table if exists` for a table. Both are idempotent with `if exists` (V6 — a
+    missing object is acknowledged). The relation type comes from the typed cache the `show tables`
+    ∪ `show views` union (`list_relations_without_caching`) now populates; a null-type relation
+    never reaches this macro because the base `SQLAdapter.drop_relation` null-type guard is restored
+    (the M1 override is removed — §4.4a / ADR-0010(b)).
+  -#}
+  {%- set relation_type = 'view' if relation.is_view else 'table' -%}
+  {%- call statement('drop_relation') -%}
+    drop {{ relation_type }} if exists {{ relation }}
+  {%- endcall -%}
+{%- endmacro %}
+
+
+{% macro wherobots__rename_relation(from_relation, to_relation) -%}
+  {#-
+    Fact 4: ALTER TABLE ... RENAME TO works ONLY with a BARE single-identifier target — a
+    fully-qualified target silently strips the catalog and fails TABLE_OR_VIEW_NOT_FOUND. So the
+    target is rendered as the bare identifier, never the three-part name.
+  -#}
+  {%- call statement('rename_relation') -%}
+    alter table {{ from_relation }} rename to {{ to_relation.identifier }}
+  {%- endcall -%}
+{%- endmacro %}
+
+
+{% macro wherobots__list_schemas(database) -%}
+  {#- Fact 6: `show schemas in <catalog>` returns the namespace at index 0; the base
+      `list_schemas` reads row[0], so this macro just returns the result table.
+      `database` is interpolated AS-IS, never re-quoted: on the real `dbt run` path dbt passes it
+      already backtick-quoted, so `adapter.quote(database)` would DOUBLE-quote it (`` ``cat`` ``)
+      and the engine rejects that with PARSE_SYNTAX_ERROR (caught live by the conformance run).
+      The already-quoted (live) and unquoted (direct test-call) forms both parse (F2). -#}
+  {%- call statement('list_schemas', fetch_result=True) -%}
+    show schemas in {{ database }}
+  {%- endcall -%}
+  {{ return(load_result('list_schemas').table) }}
+{%- endmacro %}
+
+
+{% macro wherobots__list_relations_without_caching(schema_relation) -%}
+  {#-
+    V2 / ADR-0010(b): catalog visibility is DISJOINT by type — `show tables` lists tables ONLY and
+    `show views` lists views ONLY (each ['namespace','name','isTemporary'], identifier at INDEX 1,
+    namespace at index 0). So the relation list is the UNION of both lenses, tagging each row with
+    its type (`table` / `view`) — NOT a subtraction, no double-counting. The type must round-trip
+    into the relation cache so dbt drops/replaces each object with the right DDL (type-aware
+    drop_relation, V4) and a table↔view switch can pre-drop the stale object (V7).
+
+    TEMPORARY rows are SKIPPED (isTemporary at index 2, a real boolean through the port's agate
+    boundary): Spark lists session temp views in BOTH lenses with an EMPTY namespace, and our own
+    incremental materialization creates such views (`<model>__dbt_tmp_<hash>`, ADR-0012(c),
+    ADR-0028). They are
+    session-scoped, not namespace objects — caching them corrupts every cache consumer
+    (get_relation, type-aware drops), and `drop_schema`'s emptying loop would render them with an
+    empty schema segment (`` `cat`.``.`name` ``), which the live Iceberg REST catalog rejects with
+    ForbiddenException (caught live: CI run 27393162479 teardowns).
+
+    Returns rows shaped (database, identifier, schema, type) so the base SQLAdapter
+    `list_relations_without_caching` can build the relations (it consumes the 4-tuple type as-is —
+    no Python row-shape change needed, plan §4.5 F3a).
+  -#}
+  {%- set relations = [] -%}
+  {%- call statement('list_tables', fetch_result=True) -%}
+    show tables in {{ schema_relation }}
+  {%- endcall -%}
+  {%- for row in load_result('list_tables').table -%}
+    {%- if not row[2] -%}
+      {%- do relations.append((schema_relation.database, row[1], row[0], 'table')) -%}
+    {%- endif -%}
+  {%- endfor -%}
+  {%- call statement('list_views', fetch_result=True) -%}
+    show views in {{ schema_relation }}
+  {%- endcall -%}
+  {%- for row in load_result('list_views').table -%}
+    {%- if not row[2] -%}
+      {%- do relations.append((schema_relation.database, row[1], row[0], 'view')) -%}
+    {%- endif -%}
+  {%- endfor -%}
+  {{ return(relations) }}
+{%- endmacro %}
+
+
+{% macro wherobots__make_temp_relation(base_relation, suffix) -%}
+  {#-
+    ADR-0012(c) / I1: the incremental staging relation is a session-scoped TEMPORARY VIEW, and
+    temp views are NOT namespaced — so the temp relation carries NO database and NO schema (a
+    fresh relation, not an `incorporate` of the namespaced base). Typed `view` so the type-aware
+    drop (V4) and any cache interaction see an honest type.
+
+    ADR-0028: the SQL session is shared by every connection on the runtime, including other
+    `dbt` processes, so a bare `<identifier><suffix>` collided between runs that build a
+    same-named model into different schemas or catalogs, and each run inserted the other's staged
+    rows (DB-699). The name therefore ends with the first 8 hex digits of the md5 of the base
+    relation's `<database>.<schema>`: `<identifier><suffix>_<hash>`, rendered bare and
+    backtick-quoted. Deterministic per target, so reruns and snapshots stay stable.
+  -#}
+  {%- set namespace_hash = local_md5(base_relation.database ~ '.' ~ base_relation.schema)[:8] -%}
+  {%- set temp_identifier = base_relation.identifier ~ suffix ~ '_' ~ namespace_hash -%}
+  {%- do return(api.Relation.create(identifier=temp_identifier, type='view')) -%}
+{%- endmacro %}
+
+
+{% macro wherobots__alter_relation_add_remove_columns(relation, add_columns, remove_columns) -%}
+  {#-
+    ADR-0012(d) / I6: the `on_schema_change='append_new_columns'` path adds columns in ONE batch
+    `alter table <fq> add columns (col type, ...)` (the wire-proven Spark/Iceberg shape) — not the
+    stock per-column `add column` loop. Column removal never reaches this macro on the supported
+    paths (`sync_all_columns`, the only remover, is rejected up front — §13.6); it is declared
+    unsupported here too so a future caller fails loudly instead of silently leaking columns.
+  -#}
+  {%- if remove_columns -%}
+    {{ exceptions.raise_compiler_error("Removing columns is unsupported on the Wherobots adapter: only on_schema_change='append_new_columns' (column ADDITION) is supported (ADR-0012(d)).") }}
+  {%- endif -%}
+  {%- if add_columns -%}
+    {%- set additions = [] -%}
+    {%- for column in add_columns -%}
+      {%- do additions.append(adapter.quote(column.name) ~ ' ' ~ column.data_type) -%}
+    {%- endfor -%}
+    {%- call statement('alter_relation_add_columns') -%}
+      alter table {{ relation }} add columns ({{ additions | join(', ') }})
+    {%- endcall -%}
+  {%- endif -%}
+{%- endmacro %}
+
+
+{% macro wherobots__check_for_schema_changes(source_relation, target_relation) -%}
+  {#-
+    ADR-0026: the stock diff, then the CRS for any geometry column the model adds. DESCRIBE reports
+    geometry as bare `geometry`, which the engine rejects in `add columns`. On an Iceberg V3 target
+    the adapter resolves it to `geometry(<srid>)`: the column's declared `data_type` in the model's
+    YAML, else the SRID of its values (no values and no declaration fails); on a legacy target it
+    fails before any statement, pointing at `--full-refresh` (it never toggles session flags: the
+    session is shared across threads and processes). Only `append_new_columns` adds columns: under
+    `fail`, dbt raises its own schema-mismatch error right after this macro, so nothing is checked
+    or probed (`ignore` never calls it; `sync_all_columns` is rejected up front).
+  -#}
+  {%- set changes = default__check_for_schema_changes(source_relation, target_relation) -%}
+  {%- set added = changes['source_not_in_target'] -%}
+  {%- set appending = config.get('on_schema_change') == 'append_new_columns' -%}
+  {%- if appending and added and adapter.has_crs_less_geometry_columns(added) -%}
+    {%- do adapter.require_native_geometry_table(target_relation, added) -%}
+    {%- set resolved = [] -%}
+    {%- for column in added -%}
+      {%- if adapter.is_crs_less_geometry(column) -%}
+        {%- set quoted = adapter.quote(column.name) -%}
+        {%- set srids = run_query('select distinct ST_SRID(' ~ quoted ~ ') as srid from ' ~ source_relation ~ ' where ' ~ quoted ~ ' is not null') -%}
+        {#- A `data_type: geometry(<srid>)` in the model's YAML declares the CRS (matched by name,
+            case-insensitively); the values are still probed so a contradiction fails here. -#}
+        {%- set declared = namespace(data_type=none) -%}
+        {%- for name, info in (model.get('columns') or {}).items() -%}
+          {%- if name | lower == column.name | lower -%}
+            {%- set declared.data_type = info.get('data_type') -%}
+          {%- endif -%}
+        {%- endfor -%}
+        {%- do resolved.append(adapter.added_geometry_column(column, srids.columns[0].values(), declared.data_type)) -%}
+      {%- else -%}
+        {%- do resolved.append(column) -%}
+      {%- endif -%}
+    {%- endfor -%}
+    {%- do changes.update({'source_not_in_target': resolved}) -%}
+  {%- endif -%}
+  {{ return(changes) }}
+{%- endmacro %}
+
+
+{% macro wherobots__get_catalog_relations(information_schema, relations) -%}
+  {#-
+    ADR-0018: the TARGETED `docs generate` catalog path (capability SchemaMetadataByRelations
+    Supported). A THIN delegation to the typed `@available` assembly on the adapter — no agate
+    construction in Jinja (unlintable/unmutatable) and no new SQL verb: the assembly reuses the
+    `show tables` ∪ `show views` union (for the per-relation type) and `describe table` (for the
+    columns). The base still applies `_catalog_filter_table` + the thread-per-catalog wrapper.
+  -#}
+  {{ return(adapter.assemble_catalog_for_relations(information_schema, relations)) }}
+{%- endmacro %}
+
+
+{% macro wherobots__get_catalog(information_schema, schemas) -%}
+  {#-
+    ADR-0018: the UNFILTERED `docs generate` fallback path (> 100 relations, or the capability
+    unsupported). Same thin delegation as `wherobots__get_catalog_relations`, but assembling EVERY
+    relation in each involved schema (no relation filter).
+  -#}
+  {{ return(adapter.assemble_catalog_for_schemas(information_schema, schemas)) }}
+{%- endmacro %}
+
+
+{% macro wherobots__get_columns_in_relation(relation) -%}
+  {#-
+    Fact 8: plain `describe table` returns ['col_name','data_type','comment'] — name at index 0,
+    type at index 1. Use plain DESCRIBE (not EXTENDED, which dumps Iceberg metadata columns and a
+    `# Detailed Table Information` block). Stop at the first blank or `#` row so trailing metadata
+    is dropped. Fact 9 / §10 F7: a null comment cell normalizes to NaN — harmless here, the build
+    reads only columns 0 and 1.
+  -#}
+  {%- call statement('get_columns_in_relation', fetch_result=True) -%}
+    describe table {{ relation }}
+  {%- endcall -%}
+  {%- set result = load_result('get_columns_in_relation').table -%}
+  {%- set columns = [] -%}
+  {%- for row in result -%}
+    {%- set col_name = row[0] -%}
+    {%- set trimmed = (col_name | string | trim) if col_name is not none else '' -%}
+    {%- if trimmed == '' or trimmed.startswith('#') -%}
+      {%- break -%}
+    {%- endif -%}
+    {%- do columns.append(api.Column(col_name, row[1])) -%}
+  {%- endfor -%}
+  {{ return(columns) }}
+{%- endmacro %}

dbt/include/wherobots/macros/create_table_as.sql

@@ -0,0 +1,97 @@
+{#
+  wherobots__create_table_as (component #7) — the single source of the CTAS SQL.
+
+  ADR-0007c: one atomic `create or replace table <fq> as ( ... )`. No `USING` clause — a bare CTAS
+  produces an Iceberg table on Wherobots (fact 3), and create-or-replace truly replaces both schema
+  and data in one statement (fact 2). The `table` materialization reaches this only through
+  `get_create_table_as_sql` -> `create_table_as` dispatch, so the replace SQL lives in exactly one
+  place (ADR-0007c / plan §10 F3).
+
+  ADR-0012(c): `temporary=true` (the incremental staging path) emits a session-scoped
+  `create or replace temporary view <identifier> as ( ... )` instead — temp views are not
+  namespaced (I1), so the relation renders UNQUALIFIED (defensively forced via `include`, though
+  `wherobots__make_temp_relation` already strips database/schema). CREATE-OR-REPLACE keeps the
+  staging idempotent against a same-session name collision or a failure-path leftover (§13.8).
+
+  ADR-0014(a): the NON-temporary branch threads the `partition_by` model config (Template Method —
+  this existing hook) through `partition_by_clause` below, rendering
+  `create or replace table <fq> partitioned by (...) as ( ... )` — the live-proven P1/P2 shape.
+  Because the `table` materialization reaches this same macro, `partition_by` works on plain table
+  models too (accepted scope — same code path, live-covered). The temporary branch (the staging
+  view) never partitions — views cannot be partitioned.
+
+  ADR-0029: the table SQL lives in `create_or_replace_table_as` below, which takes the
+  partition spec as an argument, so the `delete+insert` staging table reuses it UNPARTITIONED (a
+  model that drops one of its partition columns stays valid there, ADR-0013).
+#}
+{% macro wherobots__create_table_as(temporary, relation, sql) -%}
+  {%- set sql_header = config.get('sql_header', none) -%}
+  {{ sql_header if sql_header is not none }}
+  {%- if temporary %}
+  create or replace temporary view {{ relation.include(database=false, schema=false) }} as (
+    {{ sql }}
+  )
+  {%- else %}
+  {{- create_or_replace_table_as(relation, sql, config.get('partition_by')) }}
+  {%- endif %}
+{%- endmacro %}
+
+
+{#
+  create_or_replace_table_as — UNPREFIXED helper (not a dispatch override): the one rendering of
+  `create or replace table <fq> [partitioned by (...)] as ( ... )`. `partition_by` is passed in, not
+  read from config, so a caller can build an unpartitioned table for a partitioned model (the
+  `delete+insert` staging table, ADR-0029). The caller emits any `sql_header`.
+#}
+{% macro create_or_replace_table_as(relation, sql, partition_by) -%}
+  {%- set partition_clause = partition_by_clause(partition_by) %}
+  create or replace table {{ relation }}{% if partition_clause %} {{ partition_clause }}{% endif %} as (
+    {{ sql }}
+  )
+{%- endmacro %}
+
+
+{#
+  partition_by_clause — UNPREFIXED on purpose (a helper beside its only caller, not a dispatch
+  override; the `wherobots__` prefix is reserved for dispatch — plan 131 §10.13).
+
+  ADR-0014(a): renders the `partition_by` model config as `partitioned by (a, b)`, or '' when the
+  config is unset/empty. Accepts a string or a list of strings (dbt-spark parity); values are
+  PASS-THROUGH — rendered unquoted and unparsed. Plain column names are wire-proven (P1); Iceberg
+  transforms (`days(ts)`, `bucket(16, id)`) and reserved-word/special-char column names pass
+  through syntactically but are documented untested-but-unblocked (§10.11). Any other truthy shape
+  (e.g. the dbt-bigquery dict habit) is rejected with a compiler error — it would render garbage
+  through the join. (The insert_overwrite strategy additionally hard-errors on an UNSET
+  partition_by before reaching this macro — ADR-0014(c), validated in the materialization.)
+#}
+{% macro partition_by_clause(partition_by) %}
+  {#- Review pad 138 findings 2+3: a whitespace-only STRING is unset (aligned with the
+      materialization's §4.4 trim); list ENTRIES must be non-empty strings — explicit garbage in
+      a list is a compiler error, not `partitioned by ()` engine garbage. -#}
+  {%- if partition_by is string -%}
+    {%- if (partition_by | trim) == '' -%}
+      {% do return('') %}
+    {%- endif -%}
+    {%- set partition_cols = [partition_by | trim] -%}
+  {%- elif partition_by is not mapping and partition_by is sequence -%}
+    {%- set partition_cols = [] -%}
+    {%- for entry in partition_by -%}
+      {%- if entry is not string or (entry | trim) == '' -%}
+        {%- do exceptions.raise_compiler_error(
+          "partition_by entries must be non-empty strings, got: " ~ (entry | string)
+        ) -%}
+      {%- endif -%}
+      {%- do partition_cols.append(entry | trim) -%}
+    {%- endfor -%}
+    {%- if not partition_cols -%}
+      {% do return('') %}
+    {%- endif -%}
+  {%- elif not partition_by -%}
+    {% do return('') %}
+  {%- else -%}
+    {%- do exceptions.raise_compiler_error(
+      "partition_by must be a string or a list of strings, got: " ~ partition_by
+    ) -%}
+  {%- endif -%}
+  {% do return('partitioned by (' ~ (partition_cols | join(', ')) ~ ')') %}
+{% endmacro %}

dbt/include/wherobots/macros/create_view_as.sql

@@ -0,0 +1,21 @@
+{#
+  wherobots__create_view_as (component #7) — the single source of the view DDL.
+
+  ADR-0010(a) / V1: one atomic `create or replace view <fq> as ( ... )`, the view sibling of the
+  table CTAS (ADR-0007c). create-or-replace truly replaces a view in one statement (V1), so there is
+  no drop / intermediate / rename dance (the fully-qualified-rename foot-gun ADR-0007 rejects, fact
+  4). The `view` materialization reaches this only through `get_create_view_as_sql` ->
+  `create_view_as` dispatch, so the replace SQL lives in exactly one place.
+
+  Unlike `create_table_as`, the dbt-core `create_view_as` signature takes no `temporary` arg
+  (verified against the public `global_project` view macros, plan §4.1). The leading
+  `{{ sql_header if ... }}` line is load-bearing whitespace — the frozen compiled-view CTAS snapshot
+  (ADR-0008) was hand-derived to match this byte-for-byte; do not reformat.
+#}
+{% macro wherobots__create_view_as(relation, sql) -%}
+  {%- set sql_header = config.get('sql_header', none) -%}
+  {{ sql_header if sql_header is not none }}
+  create or replace view {{ relation }} as (
+    {{ sql }}
+  )
+{%- endmacro %}

dbt/include/wherobots/macros/materializations/incremental/incremental.sql

@@ -0,0 +1,173 @@
+{#
+  The `incremental` materialization for Wherobots (component #7) — ADR-0012(a).
+
+  A hand-rolled block (bent Template Method, the table/view precedent — ADR-0007c/0010a): the stock
+  incremental materialization swaps full-refresh builds via `make_intermediate_/backup_relation` +
+  `adapter.rename_relation`, and the fully-qualified rename is the exact foot-gun ADR-0007
+  rejected. The rename is baked into the stock block (not a dispatchable hook), so the whole block
+  is copied and the swap replaced:
+
+  * First build (`existing_relation is none`) AND full-refresh -> ONE atomic
+    `create or replace table <fq> as ( ... )` DIRECT to target (ADR-0007 / I7) — no intermediate,
+    no backup, no rename.
+  * Existing relation is a VIEW -> full-refresh ACROSS types: create-or-replace is type-scoped
+    (ADR-0010 V7 / I7), so the squatting view is pre-dropped (`drop view if exists <fq>` via the
+    type-aware drop) THEN the table is created (plan §13.1).
+  * Incremental update -> stage new rows into a session-scoped TEMPORARY VIEW (ADR-0012(c) / I1),
+    run `process_schema_changes` for `on_schema_change` (ADR-0012(d)), dispatch the strategy macro
+    (the committed Strategy pattern, ADR-0012(b)) in statement('main'), then drop the temp view.
+    Exception (ADR-0029): `delete+insert` with a `unique_key` stages into a real TABLE beside
+    the target, `<database>.<schema>.<model>__dbt_tmp_<hash>` (the staging view's name, qualified),
+    dropped after statement('main'). Its DELETE and INSERT are two
+    statements, and a lazy view would be evaluated again for the INSERT, after the DELETE; a model
+    whose `is_incremental()` filter reads `{{ this }}` then staged different rows (DB-700).
+
+  Deliberate EXCLUSIONS from the stock block (recorded in ADR-0012(a), auditable here):
+
+  * `adapter.expand_target_column_types` — the base implements it via `alter column ... type`,
+    which the Iceberg catalog REJECTS for widening (I6; dbt-spark also omits it). Plan §13.5.
+  * `create_indexes` — a default no-op with no Wherobots analog.
+
+  Adapter-agnostic plumbing preserved verbatim: run_hooks pre/post (inside + outside transaction),
+  persist_docs, apply_grants, adapter.commit() (an honest no-op — Spark has no transactions),
+  contract handling (carried by `get_create_table_as_sql` on the build paths; the update path's
+  only contract use in the stock block gates the excluded `expand_target_column_types`), and
+  return({'relations': [target_relation]}).
+#}
+{% materialization incremental, adapter='wherobots' %}
+
+  {%- set existing_relation = load_cached_relation(this) -%}
+  {%- set target_relation = this.incorporate(type='table') -%}
+  {%- set temp_relation = make_temp_relation(target_relation) -%}
+
+  {%- set unique_key = config.get('unique_key') -%}
+  {%- set is_view_swap = existing_relation is not none and existing_relation.is_view -%}
+  {%- set full_refresh_mode = should_full_refresh() or is_view_swap -%}
+  {#- Validated UP FRONT (plan §13.6): our unprefixed `incremental_validate_on_schema_change`
+      hard-errors on `sync_all_columns` BEFORE any statement reaches the wire. -#}
+  {%- set on_schema_change = incremental_validate_on_schema_change(config.get('on_schema_change'), default='ignore') -%}
+  {%- set grant_config = config.get('grants') -%}
+  {%- set staged = false -%}
+
+  {{ run_hooks(pre_hooks, inside_transaction=False) }}
+  {{ run_hooks(pre_hooks, inside_transaction=True) }}
+
+  {#- Resolved BEFORE branching (the stock placement): an unsupported builtin strategy
+      (`microbatch` — the only omission from valid_incremental_strategies, ADR-0012(b)/0014(e))
+      fails here with dbt-core's own clean "not valid for this adapter" error, even on a first
+      build, before any DDL/DML is emitted. -#}
+  {%- set incremental_strategy = config.get('incremental_strategy') or 'default' -%}
+  {%- set strategy_sql_macro_func = adapter.get_incremental_strategy_macro(context, incremental_strategy) -%}
+
+  {#- ADR-0029: `delete+insert` with a `unique_key` runs a DELETE and then an INSERT, so its
+      staged rows are materialized into a table first; the INSERT then reads what the DELETE read,
+      even when the model's filter reads `{{ this }}`. It takes the staging view's hashed name
+      (ADR-0028), qualified beside the target, so it cannot collide with another target's
+      staging or replace a user table such as a model named `<model>__dbt_tmp`. Without a
+      unique_key the strategy is a single INSERT and keeps the temp view. dbt-adapters also
+      resolves the spelling `delete_insert` to the same strategy macro, so both spellings stage. -#}
+  {%- set stage_in_table = incremental_strategy in ('delete+insert', 'delete_insert') and unique_key -%}
+  {%- if stage_in_table -%}
+    {%- set temp_relation = target_relation.incorporate(path={'identifier': temp_relation.identifier}) -%}
+  {%- endif -%}
+
+  {#- ADR-0014(c) — validated UP FRONT, immediately after strategy resolution and BEFORE the
+      existing_relation branch (plan §10.3 pinned placement; the Capability-flag stance, the
+      `incremental_validate_on_schema_change` precedent): `insert_overwrite` without a USABLE
+      `partition_by` hard-errors on the FIRST build too, before any DDL/DML — under the
+      engine-default STATIC mode a partition_by-less overwrite silently replaces the WHOLE table
+      (P6), and the unpartitioned-replace niche is already served by the atomic CORTAS.
+      Truthiness per §10.8: an empty string/list is unset; non-str/list shapes (the dbt-bigquery
+      dict habit) are rejected with the same error. -#}
+  {%- if incremental_strategy == 'insert_overwrite' -%}
+    {%- set partition_by_config = config.get('partition_by') -%}
+    {%- set partition_by_usable = false -%}
+    {%- if partition_by_config is string -%}
+      {%- set partition_by_usable = (partition_by_config | trim) != '' -%}
+    {%- elif partition_by_config is not mapping and partition_by_config is sequence -%}
+      {#- Review pad 138 finding 2: validate the ENTRIES too — a non-string or empty entry
+          would otherwise surface as an opaque Jinja/engine error downstream. -#}
+      {%- set usable = namespace(value=(partition_by_config | length) > 0) -%}
+      {%- for entry in partition_by_config -%}
+        {%- if entry is not string or (entry | trim) == '' -%}
+          {%- set usable.value = false -%}
+        {%- endif -%}
+      {%- endfor -%}
+      {%- set partition_by_usable = usable.value -%}
+    {%- endif -%}
+    {%- if not partition_by_usable -%}
+      {%- set partition_by_msg -%}
+incremental_strategy='insert_overwrite' requires a non-empty partition_by (a string or a list of
+strings) on {{ this }} — without it a dynamic overwrite would replace the WHOLE table. For
+whole-table replacement use materialized='table' (or --full-refresh) instead. Note: adopting
+insert_overwrite on an existing table, or changing partition_by, requires --full-refresh
+(ADR-0014).
+      {%- endset -%}
+      {%- do exceptions.raise_compiler_error(partition_by_msg) -%}
+    {%- endif -%}
+  {%- endif -%}
+
+  {% if existing_relation is none %}
+    {%- set build_sql = get_create_table_as_sql(False, target_relation, sql) -%}
+  {% elif full_refresh_mode %}
+    {%- if is_view_swap -%}
+      {#- §13.1 / ADR-0010 V7: a cross-type create-or-replace over a VIEW errors — pre-drop the
+          squatting view (the type-aware drop emits `drop view if exists <fq>`), THEN create. -#}
+      {{ drop_relation_if_exists(existing_relation) }}
+    {%- endif -%}
+    {%- set build_sql = get_create_table_as_sql(False, target_relation, sql) -%}
+  {% else %}
+    {#- Stage into the session-scoped temporary view (ADR-0012(c)): `create or replace temporary
+        view` is idempotent against same-session leftovers (§13.8). `delete+insert` with a
+        unique_key stages into a table instead (ADR-0029); `create or replace table` is
+        likewise idempotent against a leftover from a failed run. -#}
+    {%- if stage_in_table -%}
+      {#- Never partitioned: the staged rows may lack a partition column the target keeps (the
+          null-filled INSERT supplies it, ADR-0013). -#}
+      {%- set sql_header = config.get('sql_header', none) -%}
+      {%- do run_query((sql_header ~ '\n' if sql_header is not none else '') ~ create_or_replace_table_as(temp_relation, sql, none)) -%}
+    {%- else -%}
+      {%- do run_query(get_create_table_as_sql(True, temp_relation, sql)) -%}
+    {%- endif -%}
+    {%- set staged = true -%}
+    {%- set dest_columns = process_schema_changes(on_schema_change, temp_relation, existing_relation) -%}
+    {%- if not dest_columns -%}
+      {%- set dest_columns = adapter.get_columns_in_relation(existing_relation) -%}
+    {%- endif -%}
+    {%- set incremental_predicates = config.get('predicates', none) or config.get('incremental_predicates', none) -%}
+    {%- set strategy_arg_dict = ({'target_relation': target_relation, 'temp_relation': temp_relation, 'unique_key': unique_key, 'dest_columns': dest_columns, 'incremental_predicates': incremental_predicates}) -%}
+    {%- set build_sql = strategy_sql_macro_func(strategy_arg_dict) -%}
+  {% endif %}
+
+  {% call statement("main") %}
+      {{ build_sql }}
+  {% endcall %}
+
+  {% if staged %}
+    {#- Post-strategy cleanup (ADR-0012(c)): drop the temp view once the strategy statement ran.
+        If the strategy statement raises, the materialization aborts before this line — the
+        session-scoped self-cleaning of temporary views is the backstop (§13.8), and the
+        create-or-replace staging above tolerates any leftover on the next run. A staging table
+        (ADR-0029) is dropped the same way; a leftover from a failed run is replaced by the
+        next run's `create or replace table`. -#}
+    {%- if stage_in_table -%}
+      {%- do run_query("drop table if exists " ~ temp_relation) -%}
+    {%- else -%}
+      {%- do run_query("drop view if exists " ~ temp_relation) -%}
+    {%- endif -%}
+  {% endif %}
+
+  {% set should_revoke = should_revoke(existing_relation, full_refresh_mode) %}
+  {% do apply_grants(target_relation, grant_config, should_revoke=should_revoke) %}
+
+  {% do persist_docs(target_relation, model) %}
+
+  {{ run_hooks(post_hooks, inside_transaction=True) }}
+
+  {% do adapter.commit() %}
+
+  {{ run_hooks(post_hooks, inside_transaction=False) }}
+
+  {{ return({'relations': [target_relation]}) }}
+
+{% endmaterialization %}

dbt/include/wherobots/macros/materializations/incremental/on_schema_change.sql

@@ -0,0 +1,38 @@
+{#
+  incremental_validate_on_schema_change — UNPREFIXED on purpose (plan §13.6 / ADR-0012(d)).
+
+  The stock macro (`on_schema_change.sql`) is called DIRECTLY by the incremental materialization,
+  never through `adapter.dispatch` — so a `wherobots__` prefix here would be dead code (the
+  `wherobots__*` convention is reserved for dispatch overrides). Defining the same-named macro in
+  this package shadows the global_project copy for our hand-rolled caller.
+
+  Capability flag, not NotImplementedError (banned), not a silent downgrade: `sync_all_columns` is
+  declared UNSUPPORTED with a clear domain error — its type-sync step calls `alter column ... type`,
+  which the Iceberg catalog rejects for widening (probe fact I6). The stock behavior is preserved
+  for everything else: `ignore` / `fail` / `append_new_columns` pass through, and an UNKNOWN value
+  logs and silently downgrades to the default — exactly the stock contract.
+#}
+{% macro incremental_validate_on_schema_change(on_schema_change, default='ignore') %}
+
+  {%- if on_schema_change == 'sync_all_columns' -%}
+
+    {%- set msg -%}
+      on_schema_change='sync_all_columns' is unsupported on the Wherobots adapter: syncing column
+      types requires `alter column ... type`, which the Iceberg catalog rejects (ADR-0012(d)).
+      Use 'append_new_columns', 'fail', or 'ignore' instead.
+    {%- endset -%}
+    {{ exceptions.raise_compiler_error(msg) }}
+
+  {%- elif on_schema_change not in ['append_new_columns', 'fail', 'ignore'] -%}
+
+    {%- set log_message = 'Invalid value for on_schema_change (%s) specified. Setting default value of %s.' % (on_schema_change, default) -%}
+    {% do log(log_message) %}
+    {{ return(default) }}
+
+  {%- else -%}
+
+    {{ return(on_schema_change) }}
+
+  {%- endif -%}
+
+{% endmacro %}