interlaced 2.0.0a2__py3-none-any.whl

interlace/config/__init__.py

@@ -0,0 +1,7 @@
+"""Project configuration."""
+
+from __future__ import annotations
+
+from interlace.config.config import CONFIG_FILE, ProjectConfig, load_config
+
+__all__ = ["CONFIG_FILE", "ProjectConfig", "load_config"]

interlace/config/config.py

@@ -0,0 +1,172 @@
+"""Project configuration loaded from ``interlace.yaml``.
+
+A small pydantic model with sensible defaults so a project works with no config
+file at all. Paths are relative to the project root.
+
+``${VAR}`` references anywhere in the YAML are substituted from the environment
+before parsing (unset variables are left literal), so DSNs and secret values
+never need to be committed: ``database: "ducklake:postgres:${WAREHOUSE_DSN}"``.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError
+
+from interlace.exceptions import ConfigurationError
+
+CONFIG_FILE = "interlace.yaml"
+
+_ENV_REF = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+class SecretConfig(BaseModel):
+    """A DuckDB ``CREATE SECRET`` issued at engine open (currently ``type: s3``) —
+    how a DuckLake warehouse whose ``data_path`` is an object store authenticates.
+    Values normally arrive via ``${VAR}`` interpolation."""
+
+    type: str = "s3"
+    key_id: str = ""
+    secret: str = ""
+    endpoint: str | None = None  # host[:port], no scheme; None => AWS default
+    region: str | None = None
+    url_style: str | None = None  # 'path' for MinIO/RustFS-style endpoints
+    use_ssl: bool | None = None
+    scope: str | None = None  # e.g. s3://bucket — pin the secret to one prefix
+
+
+_ENGINE_TYPES = frozenset({"duckdb", "ducklake", "quack"})
+_TYPE_DIALECT = {
+    "duckdb": "duckdb",
+    "ducklake": "duckdb",
+    "quack": "duckdb",
+    "postgres": "postgres",
+    "snowflake": "snowflake",
+    "bigquery": "bigquery",
+}
+
+
+class EngineConfig(BaseModel):
+    """One named execution engine (warehouse gateway).
+
+    DuckDB-family types (``duckdb`` / ``ducklake`` / ``quack``) are fully supported.
+    Additional types are reserved for remote adapters (Postgres, Snowflake, …);
+    declaring them fails at open until an adapter ships.
+    """
+
+    type: str = "ducklake"
+    # Path / URI for DuckDB-family engines. Also accepted on the project top level
+    # as ``database:`` (synthesised into the ``default`` engine).
+    database: str | None = None
+    # The catalog's ATTACH alias. Defaults to the engine name, or the project name
+    # for the ``default`` engine. Set it when a SCHEMA inside the warehouse would
+    # otherwise share the alias — DuckDB cannot bind ``x.y`` when ``x`` is both a
+    # catalog and a schema, so a project named `seccl` holding a `seccl` schema
+    # needs one of the two renamed.
+    alias: str | None = None
+    data_path: str | None = None
+    metadata_schema: str | None = None
+    secrets: dict[str, SecretConfig] = Field(default_factory=dict)
+    quack_token: str | None = None
+    attach: dict[str, str] = Field(default_factory=dict)
+    dialect: str | None = None  # defaults from type (duckdb for DuckDB-family)
+
+    def resolved_dialect(self) -> str:
+        if self.dialect:
+            return self.dialect
+        return _TYPE_DIALECT.get(self.type, "duckdb")
+
+
+class ProjectConfig(BaseModel):
+    """Top-level project settings."""
+
+    name: str = "interlace"
+    default_dialect: str = "duckdb"
+    # Named engines (see ``engines``). Single-engine projects leave this as
+    # ``default`` and use the top-level ``database`` / ``attach`` fields.
+    default_engine: str = "default"
+    engines: dict[str, EngineConfig] = Field(default_factory=dict)
+    state_path: str = ".interlace/state.db"  # SQLite control-plane database
+    # The warehouse. Default is DuckLake (Parquet data + SQL catalog) via DuckDB.
+    # Also accepted: a DuckLake catalog hosted in a SQL database
+    # ("ducklake:postgres:dbname=... host=..." — pair with data_path/metadata_schema),
+    # a plain DuckDB file path, ":memory:", or "quack:<host>:<port>" to connect to a
+    # warehouse served by `interlace serve --quack`.
+    # When ``engines.default`` is not set, these top-level fields synthesise it.
+    database: str = "ducklake:.interlace/warehouse.ducklake"
+    # The warehouse catalog's ATTACH alias (defaults to ``name``). Set it when a
+    # schema inside the warehouse shares the project name — see EngineConfig.alias.
+    alias: str | None = None
+    # DuckLake attach options for non-default layouts: where the Parquet data lives
+    # (local dir or s3://bucket/prefix/) and which schema of the catalog database
+    # holds this warehouse's ducklake_* metadata (multiple warehouses can share one
+    # catalog database, one schema each).
+    data_path: str | None = None
+    metadata_schema: str | None = None
+    # Secrets to CREATE on the engine at open (name -> config), e.g. the S3
+    # credential for an object-store data_path.
+    secrets: dict[str, SecretConfig] = Field(default_factory=dict)
+    quack_token: str | None = None  # token for quack: databases (or INTERLACE_QUACK_TOKEN)
+    stream_path: str = ".interlace/streams.db"  # durable stream log (SQLite WAL)
+    # Databases to ATTACH to the warehouse engine at open: alias -> DuckDB attach
+    # URI/path (a .duckdb file, "postgres:...", "sqlite:...", ...). Models can read
+    # them and table exports can write to them as <alias>.<schema>.<table>.
+    # This is T0 federation (all SQL still runs in DuckDB) — see docs/architecture/MULTI_ENGINE.md.
+    attach: dict[str, str] = Field(default_factory=dict)
+    model_paths: list[str] = Field(default_factory=lambda: ["models"])
+
+    def engine_configs(self) -> dict[str, EngineConfig]:
+        """Resolved engine map: explicit ``engines`` plus a synthesised ``default``
+        from the top-level warehouse fields when that name is not already set."""
+        result = dict(self.engines)
+        if "default" not in result:
+            result["default"] = _default_engine_from_top_level(self)
+        return result
+
+
+def _infer_engine_type(database: str) -> str:
+    if database.startswith("quack:"):
+        return "quack"
+    if database.startswith("ducklake:"):
+        return "ducklake"
+    return "duckdb"
+
+
+def _default_engine_from_top_level(config: ProjectConfig) -> EngineConfig:
+    return EngineConfig(
+        type=_infer_engine_type(config.database),
+        database=config.database,
+        alias=config.alias,
+        data_path=config.data_path,
+        metadata_schema=config.metadata_schema,
+        secrets=config.secrets,
+        quack_token=config.quack_token,
+        attach=config.attach,
+        dialect=config.default_dialect if config.default_dialect != "duckdb" else None,
+    )
+
+
+def _interpolate_env(text: str) -> str:
+    """Replace ``${VAR}`` with the environment value; unset vars stay literal (so a
+    missing variable surfaces as an obvious ``${VAR}`` in errors, never silently '')."""
+    return _ENV_REF.sub(lambda m: os.environ.get(m.group(1), m.group(0)), text)
+
+
+def load_config(path: Path) -> ProjectConfig:
+    """Load and validate config, returning defaults when the file is absent."""
+    if not path.exists():
+        return ProjectConfig()
+    try:
+        data = yaml.safe_load(_interpolate_env(path.read_text())) or {}
+    except yaml.YAMLError as exc:
+        raise ConfigurationError("could not parse config", details={"path": str(path), "error": str(exc)}) from exc
+    if not isinstance(data, dict):
+        raise ConfigurationError("config root must be a mapping", details={"path": str(path)})
+    try:
+        return ProjectConfig(**data)
+    except ValidationError as exc:
+        raise ConfigurationError("invalid config", details={"path": str(path), "error": str(exc)}) from exc

interlace/contracts.py

@@ -0,0 +1,35 @@
+"""Model output contracts.
+
+A model may declare its expected output columns (and optionally types) via
+per-model config. After a model is built, ``apply`` introspects the physical
+table and validates it against the contract, raising ``SchemaError`` on drift —
+a missing contracted column, or a type mismatch — before the environment is
+promoted. Extra columns beyond the contract are allowed (additive evolution).
+"""
+
+from __future__ import annotations
+
+from interlace.exceptions import SchemaError
+
+Contract = dict[str, str | None]
+
+
+def validate_contract(model: str, actual: dict[str, str], contract: Contract) -> None:
+    """Raise ``SchemaError`` if the built columns violate the contract."""
+    missing = [column for column in contract if column not in actual]
+    if missing:
+        raise SchemaError(
+            f"model {model!r} is missing contracted column(s): {', '.join(sorted(missing))}",
+            details={"model": model, "missing": sorted(missing)},
+        )
+
+    mismatches = {
+        column: {"expected": expected, "actual": actual[column]}
+        for column, expected in contract.items()
+        if expected is not None and actual[column].upper() != expected.upper()
+    }
+    if mismatches:
+        raise SchemaError(
+            f"model {model!r} has column type mismatch(es): {sorted(mismatches)}",
+            details={"model": model, "mismatches": mismatches},
+        )

interlace/dsl/__init__.py

@@ -0,0 +1,16 @@
+"""Declarative surface: decorators and the project registry."""
+
+from __future__ import annotations
+
+from interlace.dsl.decorators import REGISTRY, CheckDef, ModelDef, Registry, StreamDef, check, model, stream
+
+__all__ = [
+    "REGISTRY",
+    "CheckDef",
+    "ModelDef",
+    "Registry",
+    "StreamDef",
+    "check",
+    "model",
+    "stream",
+]

interlace/dsl/decorators.py

@@ -0,0 +1,222 @@
+"""The ``@model`` / ``@stream`` / ``@check`` decorator DX and the in-process registry.
+
+These decorators only *declare* intent — they capture metadata into a registry and
+return the original function unchanged, so models stay ordinary, testable Python.
+Compilation, planning, and execution happen later over the registry. UK spelling
+``materialise`` is intentional (matches v0.x and the config schema).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from interlace.checks.spec import CheckSpec, parse_checks
+from interlace.exceptions import DefinitionError
+from interlace.exports import ExportConfig
+
+ModelFn = Callable[..., Any]
+
+_MATERIALISATIONS = frozenset({"table", "view", "ephemeral", "incremental", "none"})
+_DRIFT_MODES = frozenset({"evolve", "reject", "quarantine"})
+
+
+def _as_tuple(value: str | Sequence[str]) -> tuple[str, ...]:
+    return (value,) if isinstance(value, str) else tuple(value)
+
+
+def _as_columns(value: dict[str, str | None] | Sequence[str] | None) -> dict[str, str | None] | None:
+    """Normalise a column contract: a list of names -> {name: None}; a mapping kept as name->type."""
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        return {str(name): (str(dtype) if dtype is not None else None) for name, dtype in value.items()}
+    return {str(name): None for name in value}
+
+
+def _as_export(value: ExportConfig | dict[str, Any] | None) -> ExportConfig | None:
+    if value is None or isinstance(value, ExportConfig):
+        return value
+    return ExportConfig.from_dict(value)
+
+
+@dataclass
+class ModelDef:
+    """Declared metadata for one model (Python or SQL)."""
+
+    name: str
+    fn: ModelFn | None = None
+    sql: str | None = None
+    materialise: str = "table"
+    strategy: str = "full"
+    key: tuple[str, ...] = ()
+    dialect: str | None = None
+    engine: str | None = None  # named engine from config (None → project default_engine)
+    depends_on: tuple[str, ...] = ()
+    interval: str | None = None  # grain for incremental_by_time (e.g. "1d")
+    time_column: str | None = None  # partition column for incremental_by_time
+    cursor: str | None = None  # column whose max is injected into the fn's `cursor` param
+    tags: tuple[str, ...] = ()
+    owner: str | None = None
+    description: str | None = None
+    columns: dict[str, str | None] | None = None  # output contract: column -> type (None = any)
+    export: ExportConfig | None = None  # presence makes this model a sink (no table/view)
+    schedule: dict[str, str] | None = None  # {"cron": "0 * * * *"} or {"every": "5m"} for `interlace serve`
+    checks: tuple[CheckSpec, ...] = ()  # data-quality checks; error severity gates promotion
+
+
+@dataclass
+class StreamDef:
+    """Declared metadata for one durable ingestion stream."""
+
+    name: str
+    schema: dict[str, str]
+    idempotency_key: str | None = None
+    retention: str | None = None
+    on_schema_drift: str = "reject"
+    rate_limit: str | None = None
+
+
+@dataclass
+class CheckDef:
+    """Declared metadata for one data check; results gate promotion."""
+
+    name: str
+    model: str
+    fn: ModelFn
+    severity: str = "error"
+
+
+@dataclass
+class Registry:
+    """Holds everything declared in a project. One instance per process."""
+
+    models: dict[str, ModelDef] = field(default_factory=dict)
+    streams: dict[str, StreamDef] = field(default_factory=dict)
+    checks: list[CheckDef] = field(default_factory=list)
+
+    def register_model(self, definition: ModelDef) -> None:
+        if definition.name in self.models:
+            raise DefinitionError(f"duplicate model name: {definition.name!r}")
+        self.models[definition.name] = definition
+
+    def register_stream(self, definition: StreamDef) -> None:
+        if definition.name in self.streams:
+            raise DefinitionError(f"duplicate stream name: {definition.name!r}")
+        self.streams[definition.name] = definition
+
+    def register_check(self, definition: CheckDef) -> None:
+        self.checks.append(definition)
+
+    def clear(self) -> None:
+        self.models.clear()
+        self.streams.clear()
+        self.checks.clear()
+
+
+REGISTRY = Registry()
+
+
+def model(
+    name: str | None = None,
+    *,
+    materialise: str = "table",
+    strategy: str = "full",
+    key: str | Sequence[str] = (),
+    dialect: str | None = None,
+    engine: str | None = None,
+    depends_on: str | Sequence[str] = (),
+    interval: str | None = None,
+    time_column: str | None = None,
+    cursor: str | None = None,
+    tags: str | Sequence[str] = (),
+    owner: str | None = None,
+    description: str | None = None,
+    columns: dict[str, str | None] | Sequence[str] | None = None,
+    export: ExportConfig | dict[str, Any] | None = None,
+    schedule: dict[str, str] | None = None,
+    checks: Sequence[dict[str, Any] | CheckSpec] | None = None,
+) -> Callable[[ModelFn], ModelFn]:
+    """Declare a Python model. The function returns a ``Relation`` (or composes one).
+
+    ``cursor`` names a column of this model's own output; at run time the max of
+    that column in the previous materialisation is injected into the function's
+    ``cursor`` parameter (``None`` on first build), so incremental extractors can
+    resume from where the warehouse actually is instead of tracking side state.
+
+    ``engine`` pins the model to a named engine from ``interlace.yaml`` (defaults
+    to the project's ``default_engine``).
+    """
+    if materialise not in _MATERIALISATIONS:
+        raise DefinitionError(f"unknown materialise {materialise!r}; expected one of {sorted(_MATERIALISATIONS)}")
+    if materialise == "ephemeral":
+        raise DefinitionError("Python models cannot be ephemeral; ephemeral requires SQL (it is inlined as a CTE)")
+    if materialise == "view":
+        raise DefinitionError("Python models cannot be views; a view requires SQL the engine can evaluate")
+
+    def decorator(fn: ModelFn) -> ModelFn:
+        REGISTRY.register_model(
+            ModelDef(
+                name=name or fn.__name__,
+                fn=fn,
+                materialise=materialise,
+                strategy=strategy,
+                key=_as_tuple(key),
+                dialect=dialect,
+                engine=engine,
+                depends_on=_as_tuple(depends_on),
+                interval=interval,
+                time_column=time_column,
+                cursor=cursor,
+                tags=_as_tuple(tags),
+                owner=owner,
+                description=description,
+                columns=_as_columns(columns),
+                export=_as_export(export),
+                schedule=schedule,
+                checks=parse_checks(checks, name or fn.__name__),
+            )
+        )
+        return fn
+
+    return decorator
+
+
+def stream(
+    name: str,
+    *,
+    schema: dict[str, str],
+    idempotency_key: str | None = None,
+    retention: str | None = None,
+    on_schema_drift: str = "reject",
+    rate_limit: str | None = None,
+) -> Callable[[ModelFn], ModelFn]:
+    """Declare a durable ingestion stream with an HTTP publish endpoint."""
+    if on_schema_drift not in _DRIFT_MODES:
+        raise DefinitionError(f"unknown on_schema_drift {on_schema_drift!r}; expected one of {sorted(_DRIFT_MODES)}")
+
+    def decorator(fn: ModelFn) -> ModelFn:
+        REGISTRY.register_stream(
+            StreamDef(
+                name=name,
+                schema=schema,
+                idempotency_key=idempotency_key,
+                retention=retention,
+                on_schema_drift=on_schema_drift,
+                rate_limit=rate_limit,
+            )
+        )
+        return fn
+
+    return decorator
+
+
+def check(*, model: str, name: str | None = None, severity: str = "error") -> Callable[[ModelFn], ModelFn]:
+    """Declare a data check bound to a model. Failure at error severity blocks promotion."""
+
+    def decorator(fn: ModelFn) -> ModelFn:
+        REGISTRY.register_check(CheckDef(name=name or fn.__name__, model=model, fn=fn, severity=severity))
+        return fn
+
+    return decorator

interlace/dsl/discovery.py

@@ -0,0 +1,75 @@
+"""Discover models in a project directory.
+
+Walks the configured model paths: ``.sql`` files become SQL models named by
+their path (``models/silver/orders.sql`` -> ``silver.orders``); ``.py`` files are
+imported so their ``@model`` decorators register (Python models name themselves
+via the decorator or function name). Both populate the global registry, which is
+cleared first for a clean load.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Any
+
+from interlace.checks.spec import parse_checks
+from interlace.dsl.decorators import _MATERIALISATIONS, REGISTRY, ModelDef, _as_columns, _as_export, _as_tuple
+from interlace.dsl.sql_config import extract_sql_config
+from interlace.exceptions import DefinitionError
+
+
+def discover_models(root: Path, model_paths: list[str], default_dialect: str) -> list[ModelDef]:
+    REGISTRY.clear()
+    for relative in model_paths:
+        base = root / relative
+        if not base.is_dir():
+            continue
+        for sql_file in sorted(base.rglob("*.sql")):
+            config, sql = extract_sql_config(sql_file.read_text())
+            REGISTRY.register_model(_sql_model(_model_name(base, sql_file), sql, config, default_dialect))
+        for py_file in sorted(base.rglob("*.py")):
+            if py_file.name.startswith("_"):
+                continue
+            _import_module(base, py_file)
+    return list(REGISTRY.models.values())
+
+
+def _sql_model(default_name: str, sql: str, config: dict[str, Any], default_dialect: str) -> ModelDef:
+    materialise = config.get("materialise", "table")
+    if materialise not in _MATERIALISATIONS:
+        raise DefinitionError(f"unknown materialise {materialise!r}", details={"model": default_name})
+    return ModelDef(
+        name=config.get("name", default_name),
+        sql=sql,
+        materialise=materialise,
+        strategy=config.get("strategy", "full"),
+        key=_as_tuple(config.get("key") or ()),
+        dialect=config.get("dialect"),  # None → compile fills from engine dialect
+        engine=config.get("engine"),
+        depends_on=_as_tuple(config.get("depends_on") or ()),
+        interval=config.get("interval"),
+        time_column=config.get("time_column"),
+        tags=_as_tuple(config.get("tags") or ()),
+        owner=config.get("owner"),
+        description=config.get("description"),
+        columns=_as_columns(config.get("columns")),
+        export=_as_export(config.get("export")),
+        schedule=config.get("schedule"),
+        checks=parse_checks(config.get("checks"), default_name),
+    )
+
+
+def _model_name(base: Path, file: Path) -> str:
+    return ".".join(file.relative_to(base).with_suffix("").parts)
+
+
+def _import_module(base: Path, file: Path) -> None:
+    module_name = "interlace_model_" + "_".join(file.relative_to(base).with_suffix("").parts)
+    spec = importlib.util.spec_from_file_location(module_name, file)
+    if spec is None or spec.loader is None:
+        raise DefinitionError("could not import model module", details={"path": str(file)})
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)

interlace/dsl/sql_config.py

@@ -0,0 +1,47 @@
+"""Per-model config for SQL files.
+
+A SQL model may declare its materialisation, strategy, key, etc. via a leading
+block comment whose YAML is namespaced under ``interlace`` — valid SQL, no Jinja,
+ignored by the engine:
+
+    /*
+    interlace:
+      materialise: view
+      key: order_id
+    */
+    SELECT ...
+
+Only the first block comment is considered, and only when it parses to a mapping
+with a top-level ``interlace`` key; otherwise the SQL is left untouched.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import yaml
+
+from interlace.exceptions import ConfigurationError
+
+_BLOCK_COMMENT = re.compile(r"/\*(.*?)\*/", re.DOTALL)
+
+
+def extract_sql_config(content: str) -> tuple[dict[str, Any], str]:
+    """Return ``(config, sql)`` — the parsed config and the SQL with the block removed."""
+    match = _BLOCK_COMMENT.search(content)
+    if match is None:
+        return {}, content
+    try:
+        parsed = yaml.safe_load(match.group(1))
+    except yaml.YAMLError:
+        return {}, content
+    if not isinstance(parsed, dict) or "interlace" not in parsed:
+        return {}, content
+
+    config = parsed["interlace"] or {}
+    if not isinstance(config, dict):
+        raise ConfigurationError("SQL model config must be a mapping", details={"got": type(config).__name__})
+
+    sql = (content[: match.start()] + content[match.end() :]).strip()
+    return config, sql

interlace/engines/__init__.py

@@ -0,0 +1,16 @@
+"""Engine adapters: one per backend, the only home for dialect-specific code."""
+
+from __future__ import annotations
+
+from interlace.engines.base import EngineAdapter, EngineCaps, LoadMode
+from interlace.engines.duckdb import DuckDBAdapter
+from interlace.engines.registry import EngineRegistry, as_registry
+
+__all__ = [
+    "DuckDBAdapter",
+    "EngineAdapter",
+    "EngineCaps",
+    "EngineRegistry",
+    "LoadMode",
+    "as_registry",
+]

interlace/engines/base.py

@@ -0,0 +1,86 @@
+"""The engine adapter — the only place dialect-specific code is allowed to live.
+
+Every backend (DuckDB, DuckLake, Postgres, Snowflake, BigQuery) implements this
+one interface. The planner and strategies stay dialect-neutral by emitting
+canonical sqlglot ASTs; :meth:`EngineAdapter.transpile` is the single seam where
+a dialect reappears. :class:`EngineCaps` lets strategies degrade gracefully
+(e.g. rewrite ``MERGE`` to ``DELETE`` + ``INSERT``) on engines that lack a feature.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal
+
+import pyarrow as pa
+import sqlglot
+from sqlglot import exp
+
+from interlace.ir.relation import TableRef
+
+LoadMode = Literal["create", "append"]
+
+
+@dataclass(frozen=True)
+class EngineCaps:
+    """Feature flags that drive strategy fallbacks. Conservative defaults (all off)."""
+
+    supports_create_or_replace: bool = False
+    supports_star_exclude: bool = False  # SELECT * EXCLUDE (...) — scd_type_2 needs it
+
+
+class EngineAdapter(ABC):
+    """Executes canonical ASTs and moves Arrow data in and out of one backend."""
+
+    dialect: str
+    caps: EngineCaps
+
+    @abstractmethod
+    async def execute(self, ast: exp.Expression) -> None:
+        """Run a statement (DDL/DML) with no result set."""
+
+    @abstractmethod
+    async def fetch(self, ast: exp.Expression) -> pa.RecordBatchReader:
+        """Extract: evaluate a query and stream the result as Arrow batches."""
+
+    @abstractmethod
+    async def load(self, table: TableRef, reader: pa.RecordBatchReader, mode: LoadMode) -> int:
+        """Load: write Arrow batches into a table, creating or appending.
+        Returns the number of rows written (0 when the backend cannot tell)."""
+
+    @abstractmethod
+    async def create_view(self, name: TableRef, target: TableRef) -> None:
+        """Point a virtual-environment view at a physical snapshot table."""
+
+    @abstractmethod
+    async def create_schema(self, name: str) -> None:
+        """Create a schema/namespace if it does not already exist."""
+
+    @abstractmethod
+    async def describe(self, table: TableRef) -> dict[str, str]:
+        """Return a table or view's columns as an ordered ``{name: type}`` mapping."""
+
+    async def table_exists(self, table: TableRef) -> bool:
+        """Whether the table (or view) exists. Adapters override with a direct probe."""
+        return bool(await self.describe(table))
+
+    async def execute_all(self, statements: Sequence[exp.Expression]) -> list[int]:
+        """Run statements in order; returns affected-row counts per statement (0 when
+        unknown). Override to make the batch atomic (one transaction)."""
+        for statement in statements:
+            await self.execute(statement)
+        return [0] * len(statements)
+
+    async def execute_sql(self, sql: str) -> None:
+        """Run one raw SQL statement written in this engine's dialect."""
+        await self.execute(sqlglot.parse_one(sql, read=self.dialect))
+
+    async def fetch_sql(self, sql: str) -> pa.RecordBatchReader:
+        """Evaluate one raw SQL query written in this engine's dialect."""
+        return await self.fetch(sqlglot.parse_one(sql, read=self.dialect))
+
+    def transpile(self, ast: exp.Expression) -> str:
+        """Canonical AST -> this engine's SQL. The one place dialect leaks back in."""
+        return ast.sql(dialect=self.dialect)