interlaced 2.2.0__tar.gz → 2.4.0__tar.gz

{interlaced-2.2.0/src/interlaced.egg-info → interlaced-2.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: interlaced
-Version: 2.2.0
-Summary: Python/SQL-first data platform: transformation, built-in orchestration, and durable streaming ingestion
+Version: 2.4.0
+Summary: Python and SQL models in one DAG. Transformation, orchestration and durable streaming in one process, on DuckDB and Postgres.
 Author-email: Mark <mark@interlace.sh>
 License-Expression: MIT
 Project-URL: Homepage, https://interlace.sh
@@ -13,17 +13,19 @@ Keywords: data,pipeline,orchestration,transformation,etl,streaming,dbt,sqlmesh,d
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Database
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: SQL
+Classifier: Operating System :: POSIX :: Linux
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: sqlglot<29.0,>=25.0
+Requires-Dist: sqlglot<30.0,>=25.0
 Requires-Dist: duckdb>=1.5.3
 Requires-Dist: pyarrow>=17.0
 Requires-Dist: pydantic<3.0,>=2.5
 Requires-Dist: typer<1.0,>=0.12
-Requires-Dist: rich<15.0,>=13.0
+Requires-Dist: rich<16.0,>=13.0
 Requires-Dist: cronsim<3.0,>=2.5
 Requires-Dist: tenacity<10.0,>=8.2
 Requires-Dist: pyyaml<7.0,>=6.0
@@ -59,20 +61,46 @@ Requires-Dist: httpx<1.0,>=0.27; extra == "dev"
 Requires-Dist: pytest-asyncio<2.0,>=1.0; extra == "dev"
 Requires-Dist: ruff<1.0,>=0.6; extra == "dev"
 Requires-Dist: black<27.0,>=24.0; extra == "dev"
-Requires-Dist: mypy<2.0,>=1.11; extra == "dev"
+Requires-Dist: mypy<3.0,>=1.11; extra == "dev"
 Dynamic: license-file
 
 # interlace
 
-**Python/SQL-first data platform: transformation, orchestration, and durable streaming — one process.**
+**Python and SQL models are the same kind of node in one DAG.**
 
-interlace is an independent, MIT-licensed alternative to dbt/SQLMesh that also replaces the
-orchestrator (no Airflow) and the ingestion layer (Cloudflare-Pipelines-style durable streams).
-Models are `.sql` files or Python functions; state is versioned snapshots with virtual
+A `.py` model sits mid-graph with SQL either side, in both directions, with no bridge and no
+separate runtime — running in-process on DuckDB and Postgres, not only on a cloud warehouse.
+The Python model stays a plain function: call it in a test with no warehouse and no session.
+
+How that compares with dbt and SQLMesh, including where they are ahead, is on
+[interlace.sh/why](https://interlace.sh/why).
+
+```sql
+-- models/raw_events.sql                    SQL
+SELECT event_id, user_id, kind, amount, country, ts FROM read_parquet('events/*.parquet')
+```
+```python
+# models/enriched_events.py                 Python, mid-DAG
+@model()                    # the parameter name IS the dependency — no depends_on
+def enriched_events(raw_events):
+    for batch in raw_events.reader():       # Arrow in, Arrow out, bounded memory
+        yield add_revenue(batch)
+```
+```sql
+-- models/event_summary.sql                 SQL again, straight over the Python
+SELECT country, count(*) FILTER (WHERE is_conversion) AS conversions
+FROM enriched_events GROUP BY country
+```
+
+`interlace init` scaffolds exactly this shape, runnable, with no external source.
+
+That is the wedge. The rest is the reveal: interlace is an independent, MIT-licensed alternative
+to dbt/SQLMesh that also replaces the orchestrator (no Airflow) and the ingestion layer
+(Cloudflare-Pipelines-style durable streams). State is versioned snapshots with virtual
 environments and a terraform-style plan/apply; everything runs in a single daemon on
-DuckDB + DuckLake by default.
+DuckDB by default (DuckLake one config line away).
 
-> **Status: 2.0.** Requires Python 3.12+.
+> **2.x — see [releases](https://github.com/interlace-sh/interlace/releases).** Requires Python 3.12+.
 > The package is published to PyPI as **`interlaced`**; the import name and CLI are `interlace`.
 
 ```bash
@@ -80,6 +108,13 @@ pip install 'interlaced[service]'   # the CLI + daemon; core CLI only: pip insta
 # more extras: [adbc] postgres/redshift · [spark] · [polars] · [all]
 ```
 
+> **Platforms.** Developed on Linux; CI runs Linux only. Nothing in the codebase is
+> platform-specific — no `fork`, no signal handling, no POSIX-only calls, no shelling out — and
+> every dependency ships macOS and Windows wheels, so both are expected to work. But
+> **neither is tested**, so treat them as unverified rather than supported. If you run interlace
+> on macOS or Windows, please open an issue either way; that is the fastest route to changing
+> this paragraph.
+
 ## Sixty seconds
 
 ```bash
@@ -127,8 +162,9 @@ def orders(cursor, this):
 ```
 
 **Strategies:** `replace`, `view`, `ephemeral` (CTE-inlined), `merge` (upsert),
-`full_merge` (full-state source applied as a minimal diff), `incremental_by_time`
-(windowed, interval-ledger backfill/catchup), `scd` (history with validity windows).
+`full_merge` (full-state source applied as a minimal diff), `incremental` (one time window
+at a time — rewrites the window, or upserts within it if you give it a `key`), `scd`
+(history with validity windows).
 
 ## Plan / apply
 
@@ -209,7 +245,7 @@ prod, so a dev apply never writes to a live external table (opt in with
 
 ## Multi-engine
 
-Models run on **named engines**: DuckDB/DuckLake by default, Postgres natively over ADBC
+Models run on **named engines**: DuckDB by default (DuckLake opt-in), Postgres natively over ADBC
 (`pip install 'interlaced[adbc]'`), Spark (beta, `[spark]` extra), plus alpha adapters for
 MotherDuck, Redshift, Snowflake and BigQuery (wired and dialect-correct, not yet run against a
 live account), with per-model pinning:
@@ -251,7 +287,8 @@ other processes (CLI runs, ad-hoc DuckDB clients) then share it concurrently by
 
 - The IR is a **sqlglot AST**; the wire format is an **Arrow RecordBatchReader**; strategies
   are AST builders and dialect appears only at `transpile()`.
-- Storage defaults to **DuckLake** (Parquet + SQL catalog) opened as DuckDB's primary database.
+- Storage defaults to a plain **DuckDB** file; **DuckLake** (Parquet + SQL catalog, and
+  concurrent writers) is one `database: ducklake:…` line away.
 - Control plane (snapshots, intervals, queue, events, keys) is **SQLite WAL**; Postgres is the
   scale-out swap.
 - Streams live in their own durable log; the materializer commits data + watermark in one
@@ -268,7 +305,7 @@ Toolchain is pinned with [proto](https://moonrepo.dev/proto), tasks run via
 ```bash
 proto install
 moon run interlace:sync      # install deps
-moon run interlace:test      # 350+ tests
+moon run interlace:test      # 500+ tests
 moon run interlace:check     # black + ruff (CI equivalent)
 moon run interlace:typecheck # mypy
 ```

{interlaced-2.2.0 → interlaced-2.4.0}/README.md

@@ -1,14 +1,40 @@
 # interlace
 
-**Python/SQL-first data platform: transformation, orchestration, and durable streaming — one process.**
+**Python and SQL models are the same kind of node in one DAG.**
 
-interlace is an independent, MIT-licensed alternative to dbt/SQLMesh that also replaces the
-orchestrator (no Airflow) and the ingestion layer (Cloudflare-Pipelines-style durable streams).
-Models are `.sql` files or Python functions; state is versioned snapshots with virtual
+A `.py` model sits mid-graph with SQL either side, in both directions, with no bridge and no
+separate runtime — running in-process on DuckDB and Postgres, not only on a cloud warehouse.
+The Python model stays a plain function: call it in a test with no warehouse and no session.
+
+How that compares with dbt and SQLMesh, including where they are ahead, is on
+[interlace.sh/why](https://interlace.sh/why).
+
+```sql
+-- models/raw_events.sql                    SQL
+SELECT event_id, user_id, kind, amount, country, ts FROM read_parquet('events/*.parquet')
+```
+```python
+# models/enriched_events.py                 Python, mid-DAG
+@model()                    # the parameter name IS the dependency — no depends_on
+def enriched_events(raw_events):
+    for batch in raw_events.reader():       # Arrow in, Arrow out, bounded memory
+        yield add_revenue(batch)
+```
+```sql
+-- models/event_summary.sql                 SQL again, straight over the Python
+SELECT country, count(*) FILTER (WHERE is_conversion) AS conversions
+FROM enriched_events GROUP BY country
+```
+
+`interlace init` scaffolds exactly this shape, runnable, with no external source.
+
+That is the wedge. The rest is the reveal: interlace is an independent, MIT-licensed alternative
+to dbt/SQLMesh that also replaces the orchestrator (no Airflow) and the ingestion layer
+(Cloudflare-Pipelines-style durable streams). State is versioned snapshots with virtual
 environments and a terraform-style plan/apply; everything runs in a single daemon on
-DuckDB + DuckLake by default.
+DuckDB by default (DuckLake one config line away).
 
-> **Status: 2.0.** Requires Python 3.12+.
+> **2.x — see [releases](https://github.com/interlace-sh/interlace/releases).** Requires Python 3.12+.
 > The package is published to PyPI as **`interlaced`**; the import name and CLI are `interlace`.
 
 ```bash
@@ -16,6 +42,13 @@ pip install 'interlaced[service]'   # the CLI + daemon; core CLI only: pip insta
 # more extras: [adbc] postgres/redshift · [spark] · [polars] · [all]
 ```
 
+> **Platforms.** Developed on Linux; CI runs Linux only. Nothing in the codebase is
+> platform-specific — no `fork`, no signal handling, no POSIX-only calls, no shelling out — and
+> every dependency ships macOS and Windows wheels, so both are expected to work. But
+> **neither is tested**, so treat them as unverified rather than supported. If you run interlace
+> on macOS or Windows, please open an issue either way; that is the fastest route to changing
+> this paragraph.
+
 ## Sixty seconds
 
 ```bash
@@ -63,8 +96,9 @@ def orders(cursor, this):
 ```
 
 **Strategies:** `replace`, `view`, `ephemeral` (CTE-inlined), `merge` (upsert),
-`full_merge` (full-state source applied as a minimal diff), `incremental_by_time`
-(windowed, interval-ledger backfill/catchup), `scd` (history with validity windows).
+`full_merge` (full-state source applied as a minimal diff), `incremental` (one time window
+at a time — rewrites the window, or upserts within it if you give it a `key`), `scd`
+(history with validity windows).
 
 ## Plan / apply
 
@@ -145,7 +179,7 @@ prod, so a dev apply never writes to a live external table (opt in with
 
 ## Multi-engine
 
-Models run on **named engines**: DuckDB/DuckLake by default, Postgres natively over ADBC
+Models run on **named engines**: DuckDB by default (DuckLake opt-in), Postgres natively over ADBC
 (`pip install 'interlaced[adbc]'`), Spark (beta, `[spark]` extra), plus alpha adapters for
 MotherDuck, Redshift, Snowflake and BigQuery (wired and dialect-correct, not yet run against a
 live account), with per-model pinning:
@@ -187,7 +221,8 @@ other processes (CLI runs, ad-hoc DuckDB clients) then share it concurrently by
 
 - The IR is a **sqlglot AST**; the wire format is an **Arrow RecordBatchReader**; strategies
   are AST builders and dialect appears only at `transpile()`.
-- Storage defaults to **DuckLake** (Parquet + SQL catalog) opened as DuckDB's primary database.
+- Storage defaults to a plain **DuckDB** file; **DuckLake** (Parquet + SQL catalog, and
+  concurrent writers) is one `database: ducklake:…` line away.
 - Control plane (snapshots, intervals, queue, events, keys) is **SQLite WAL**; Postgres is the
   scale-out swap.
 - Streams live in their own durable log; the materializer commits data + watermark in one
@@ -204,7 +239,7 @@ Toolchain is pinned with [proto](https://moonrepo.dev/proto), tasks run via
 ```bash
 proto install
 moon run interlace:sync      # install deps
-moon run interlace:test      # 350+ tests
+moon run interlace:test      # 500+ tests
 moon run interlace:check     # black + ruff (CI equivalent)
 moon run interlace:typecheck # mypy
 ```

{interlaced-2.2.0 → interlaced-2.4.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "interlaced"
-version = "2.2.0"
-description = "Python/SQL-first data platform: transformation, built-in orchestration, and durable streaming ingestion"
+version = "2.4.0"
+description = "Python and SQL models in one DAG. Transformation, orchestration and durable streaming in one process, on DuckDB and Postgres."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"
@@ -17,19 +17,23 @@ classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Build Tools",
+    "Topic :: Database",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: SQL",
+    # Linux is what CI runs and what this is developed on. Nothing in the codebase
+    # is platform-specific, but macOS and Windows are untested — see the README.
+    "Operating System :: POSIX :: Linux",
 ]
 
 # Core: the IR + engine + state + plan spine (Phase 1). Everything is Arrow- and
 # sqlglot-native. See docs/architecture/architecture.md.
 dependencies = [
-    "sqlglot>=25.0,<29.0",        # canonical IR, transpilation, semantic diff, column lineage
+    "sqlglot>=25.0,<30.0",        # canonical IR, transpilation, semantic diff, column lineage
     "duckdb>=1.5.3",              # default engine + federation hub; DuckLake storage + quack serving
     "pyarrow>=17.0",              # the wire format: RecordBatchReader everywhere
     "pydantic>=2.5,<3.0",         # config + manifest validation (cold paths only)
     "typer>=0.12,<1.0",           # CLI
-    "rich>=13.0,<15.0",           # display, strictly an event subscriber
+    "rich>=13.0,<16.0",           # display, strictly an event subscriber
     "cronsim>=2.5,<3.0",          # cron parsing for the trigger engine
     "tenacity>=8.2,<10.0",        # retries (tasks, DuckLake commit conflicts, transfers)
     "pyyaml>=6.0,<7.0",           # project config (config + env overlays)
@@ -78,7 +82,7 @@ dev = [
     "pytest-asyncio>=1.0,<2.0",
     "ruff>=0.6,<1.0",
     "black>=24.0,<27.0",
-    "mypy>=1.11,<2.0",
+    "mypy>=1.11,<3.0",
 ]
 
 [tool.setuptools.packages.find]

{interlaced-2.2.0 → interlaced-2.4.0}/src/interlace/cli/main.py

@@ -107,7 +107,7 @@ _END = typer.Option("", "--end", help="Window end (ISO), for incremental models.
 _FORWARD_ONLY = typer.Option(
     False,
     "--forward-only",
-    help="Modified history-keeping models (merge/full_merge/scd/incremental_by_time) carry their history "
+    help="Modified history-keeping models (merge/full_merge/scd/incremental) carry their history "
     "forward: it is copied to the new version, the new logic applies to the copy, and checks gate "
     "before views move. Requires a shape-compatible change.",
 )
@@ -205,7 +205,7 @@ async def _render_empty_incrementals(result: ApplyResult, compiled: CompiledProj
 
     for name in result.built:
         model = compiled.models[name]
-        if model.strategy != "incremental_by_time" or model.is_terminal:
+        if model.strategy != "incremental" or model.is_terminal:
             continue
         counts = result.rows.get(name)
         if counts is not None and (counts.inserted or counts.updated):
@@ -404,7 +404,7 @@ def run(
 ) -> None:
     """Force-build models and promote, ignoring change detection.
 
-    For incremental_by_time models, --start/--end set the catchup window
+    For incremental models, --start/--end set the catchup window
     (default: the latest grain interval).
     """
     asyncio.run(_execute(environment, path, select, start, end, restate=False, parallelism=parallelism))

{interlaced-2.2.0 → interlaced-2.4.0}/src/interlace/config/config.py

@@ -84,7 +84,7 @@ class EngineConfig(BaseModel):
     declaring them fails at open until an adapter ships.
     """
 
-    type: str = "ducklake"
+    type: str = "duckdb"
     # Path / URI for DuckDB-family engines. Also accepted on the project top level
     # as ``database:`` (synthesised into the ``default`` engine).
     database: str | None = None
@@ -117,13 +117,14 @@ class ProjectConfig(BaseModel):
     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`.
+    # The warehouse. Default is a plain DuckDB file — simplest, single-process.
+    # Also accepted: a DuckLake catalog (``ducklake:.interlace/warehouse.ducklake``, or
+    # hosted in a SQL DB: ``ducklake:postgres:dbname=... host=...`` — pair with
+    # data_path/metadata_schema) which serialises catalog writes so `interlace serve`
+    # and a separate CLI can share the warehouse concurrently; ":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"
+    database: str = ".interlace/warehouse.duckdb"
     # 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

{interlaced-2.2.0 → interlaced-2.4.0}/src/interlace/dsl/decorators.py

@@ -94,9 +94,9 @@ class ModelDef:
     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
-    # First-build window for incremental_by_time: "auto" derives [min, max] of the
+    interval: str | None = None  # grain for incremental (e.g. "1d")
+    time_column: str | None = None  # partition column for incremental
+    # First-build window for incremental: "auto" derives [min, max] of the
     # time column from the source at apply time and fills it as ONE interval;
     # "none" keeps only the latest grain window; an ISO date pins the start.
     backfill: str = "auto"
@@ -114,6 +114,18 @@ class ModelDef:
     schedule: dict[str, str] | None = None  # {"cron": "0 * * * *"} or {"every": "5m"} for `interlace serve`
     checks: tuple[CheckSpec, ...] = ()  # data-quality checks; error severity gates promotion
 
+    def __post_init__(self) -> None:
+        # `@model(checks=…)` normalises through parse_checks, but a ModelDef built
+        # directly — the dynamic-model path, which is what generated models and dbt
+        # migrations use — stored the dicts raw and only failed at compile time with
+        # `AttributeError: 'dict' object has no attribute 'type'`. Normalise here too,
+        # so one spelling works on both surfaces and a bad check fails at declaration.
+        # Passed through as-is, not as list(...): parse_checks already handles a bare
+        # CheckSpec and reports a non-list clearly, both of which list() would mangle
+        # (TypeError on a CheckSpec; a dict silently degraded to its keys). Always run,
+        # so `checks=[]` normalises to the declared tuple rather than staying a list.
+        self.checks = parse_checks(self.checks, self.name)
+
     @property
     def is_terminal(self) -> bool:
         """A terminal model delivers into an external destination (table/file):

{interlaced-2.2.0 → interlaced-2.4.0}/src/interlace/dsl/discovery.py

@@ -64,7 +64,7 @@ def _sql_model(default_name: str, sql: str, config: dict[str, Any], default_dial
         depends_on=_as_tuple(config.get("depends_on") or ()),
         interval=config.get("interval"),
         time_column=config.get("time_column"),
-        backfill=config.get("backfill", "auto"),  # first-build window for incremental_by_time
+        backfill=config.get("backfill", "auto"),  # first-build window for incremental
         tags=_as_tuple(config.get("tags") or ()),
         owner=config.get("owner"),
         description=config.get("description"),

{interlaced-2.2.0 → interlaced-2.4.0}/src/interlace/engines/duckdb.py

@@ -28,6 +28,7 @@ from __future__ import annotations
 
 import asyncio
 import contextlib
+import re
 import threading
 from collections.abc import Iterator, Sequence
 from uuid import uuid4
@@ -38,6 +39,7 @@ import tenacity
 from sqlglot import exp
 
 from interlace.engines.base import EngineAdapter, EngineCaps, LoadMode
+from interlace.exceptions import ConfigurationError
 from interlace.ir.relation import TableRef
 
 _DUCKDB_CAPS = EngineCaps(
@@ -58,6 +60,39 @@ _commit_retry = tenacity.retry(
 )
 
 
+@contextlib.contextmanager
+def _clean_lock_error(database: str) -> Iterator[None]:
+    """Translate DuckDB's file-lock conflict into one actionable line.
+
+    A DuckDB/DuckLake database is held by a single process. The common way to hit
+    that is running a CLI command (`interlace query`, `plan`, `apply`) while
+    `interlace serve` is up — an obvious thing to do, since serve is the daemon
+    and query is the console's CLI counterpart. Raw, that surfaces as a dozen
+    frames ending in `duckdb.IOException`, which names neither the cause nor the
+    fix. The fix is `--quack`, and it is already documented; the error just never
+    said so.
+    """
+    try:
+        yield
+    except duckdb.IOException as exc:
+        message = str(exc)
+        # "Conflicting lock is held in <exe> (PID n)" is the Linux rendering — DuckDB
+        # names the holder from /proc/locks. Elsewhere the message is the bare "Could
+        # not set lock on file", and a same-process conflict says "already held", so
+        # match all three or macOS/Windows keep the raw traceback.
+        if not any(marker in message for marker in ("Conflicting lock", "Could not set lock", "already held")):
+            raise
+        holder = re.search(r"\(PID (\d+)\)", message)
+        held_by = f" (PID {holder.group(1)})" if holder else ""
+        raise ConfigurationError(
+            f"the warehouse {database!r} is already open in another process{held_by}. "
+            "DuckDB allows one process at a time — stop `interlace serve`, or serve the "
+            "warehouse over the quack protocol (`interlace serve --quack quack:localhost:4213`) "
+            "and point this process at `database: quack:localhost:4213` to share it.",
+            details={"database": database},
+        ) from None
+
+
 def _affected(cur: duckdb.DuckDBPyConnection) -> int:
     """DML/CTAS/COPY return their affected-row count as a one-cell result; DDL returns
     nothing. Never raises — row stats are best-effort decoration, not correctness."""
@@ -108,7 +143,9 @@ class DuckDBAdapter(EngineAdapter):
 
     @classmethod
     def connect(cls, path: str) -> DuckDBAdapter:
-        return cls(duckdb.connect(path), serialise_writes=path.startswith("ducklake:"))
+        with _clean_lock_error(path):
+            conn = duckdb.connect(path)
+        return cls(conn, serialise_writes=path.startswith("ducklake:"))
 
     @classmethod
     def connect_ducklake(
@@ -139,7 +176,8 @@ class DuckDBAdapter(EngineAdapter):
         options_sql = f" ({', '.join(options)})" if options else ""
         escaped = catalog.replace("'", "''")
         alias_sql = exp.to_identifier(alias).sql("duckdb")
-        conn.execute(f"ATTACH IF NOT EXISTS '{escaped}' AS {alias_sql}{options_sql}")
+        with _clean_lock_error(catalog):
+            conn.execute(f"ATTACH IF NOT EXISTS '{escaped}' AS {alias_sql}{options_sql}")
         conn.execute(f"USE {alias_sql}")
         # LOAD, secrets, and ATTACH are all instance-wide — they carry into every
         # cursor and must run ONCE (re-running CREATE OR REPLACE SECRET per cursor
@@ -162,10 +200,23 @@ class DuckDBAdapter(EngineAdapter):
         with contextlib.suppress(Exception):
             self._conn.interrupt()
 
+    def search_files_from(self, directory: str) -> None:
+        """Resolve relative read paths (``read_csv_auto('seeds/x.csv')``) against
+        ``directory`` — the project root — as well as the process CWD.
+
+        Additive: a CWD-relative path still resolves, so this only ever widens what a
+        model can find. GLOBAL scope because a plain ``SET`` is session-scoped and would
+        not reach the per-task cursors that actually run the queries. Reads only —
+        ``COPY`` targets stay CWD-relative, which is why exports resolve their own paths
+        against the root (``plan.apply._resolve_export_path``)."""
+        escaped = directory.replace("'", "''")
+        self._conn.execute(f"SET GLOBAL file_search_path='{escaped}'")
+
     def attach(self, alias: str, uri: str) -> None:
         """ATTACH another database (duckdb/sqlite/postgres/... URI) under ``alias``."""
         escaped = uri.replace("'", "''")
-        self._conn.execute(f"ATTACH IF NOT EXISTS '{escaped}' AS {exp.to_identifier(alias).sql('duckdb')}")
+        with _clean_lock_error(uri):  # attaching a held duckdb/ducklake file conflicts just like opening one
+            self._conn.execute(f"ATTACH IF NOT EXISTS '{escaped}' AS {exp.to_identifier(alias).sql('duckdb')}")
         self._attached.append(alias)
         if uri.startswith("ducklake:"):  # writes may now reach a DuckLake catalog (e.g. table sinks)
             if isinstance(self._write_lock, contextlib.nullcontext):

{interlaced-2.2.0 → interlaced-2.4.0}/src/interlace/engines/spark.py

@@ -7,7 +7,7 @@ come back as Arrow via ``DataFrame.toArrow()``, and Arrow loads go in through
 (``local[*]``, for tests) or a remote one (Spark Connect / a shared session).
 
 **Strategy support.** ``replace``, ``append`` and ``view`` run on any Spark
-catalog. ``merge`` (native ``MERGE``) and ``incremental_by_time`` (windowed
+catalog. ``merge`` (native ``MERGE``) and ``incremental`` (windowed
 ``DELETE`` by literal predicate + ``INSERT``) need a catalog with row-level
 mutations — Delta Lake or Iceberg — configured on the session you hand the
 adapter (the tests use a Delta-backed local session). ``scd`` and ``full_merge``

{interlaced-2.2.0 → interlaced-2.4.0}/src/interlace/graph/project.py

@@ -44,9 +44,9 @@ class CompiledModel:
     materialise: str
     strategy: str
     key: tuple[str, ...]  # business key for keyed strategies (merge)
-    time_column: str | None  # partition column for incremental_by_time
+    time_column: str | None  # partition column for incremental
     cursor: str | None  # column whose max is injected into a Python model's `cursor` param
-    interval: str | None  # grain for incremental_by_time (e.g. "1d")
+    interval: str | None  # grain for incremental (e.g. "1d")
     tags: tuple[str, ...]  # for tag: selection
     schedule: dict[str, str] | None  # cron/interval schedule for the trigger engine
     columns: dict[str, str | None] | None  # output contract validated at apply time

{interlaced-2.2.0 → interlaced-2.4.0}/src/interlace/ir/canonicalize.py

@@ -8,6 +8,8 @@ pruning and the ``impact`` command).
 
 from __future__ import annotations
 
+from typing import cast
+
 import sqlglot
 from sqlglot import exp
 
@@ -86,4 +88,5 @@ def resolve_references(ast: exp.Expression, mapping: dict[str, TableRef]) -> exp
                 node.set("catalog", exp.to_identifier(target.catalog) if target.catalog else None)
         return node
 
-    return ast.transform(rewrite)
+    # sqlglot 29 loosened transform()'s return annotation; it is an Expression.
+    return cast("exp.Expression", ast.transform(rewrite))