interlaced 2.0.0a2__py3-none-any.whl

interlace/exceptions.py

@@ -0,0 +1,66 @@
+"""Exception hierarchy. Everything inherits from :class:`InterlaceError`.
+
+Ported in spirit from v0.x: a single root with an optional structured ``details``
+payload so errors carry machine-readable context to the CLI, API, and event log.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class InterlaceError(Exception):
+    """Base class for all Interlace errors."""
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+
+class ConfigurationError(InterlaceError):
+    """Invalid or missing project/model configuration."""
+
+
+class DefinitionError(InterlaceError):
+    """A model, stream, or check is declared incorrectly."""
+
+
+class CompilationError(InterlaceError):
+    """SQL could not be parsed, qualified, or transpiled."""
+
+
+class DependencyError(InterlaceError):
+    """The dependency graph is invalid (e.g. a cycle)."""
+
+
+class SelectionError(InterlaceError):
+    """A model selector could not be resolved."""
+
+
+class EngineError(InterlaceError):
+    """An engine adapter failed to execute, fetch, or load."""
+
+
+class StateError(InterlaceError):
+    """The state store could not be read or written consistently."""
+
+
+class PlanError(InterlaceError):
+    """A plan could not be computed or applied."""
+
+
+class SchemaError(InterlaceError):
+    """A model's built schema violates its declared column contract."""
+
+
+class StreamError(InterlaceError):
+    """Stream ingestion, the durable log, or a consumer failed."""
+
+
+class Backpressure(StreamError):
+    """The durable log's bounded commit queue is full; callers should retry (HTTP 429)."""
+
+
+class CheckError(InterlaceError):
+    """A data check failed with error severity."""

interlace/exports.py

@@ -0,0 +1,145 @@
+"""Sinks / exports — pushing a model's result to an external destination.
+
+A model with an ``export`` block is a *sink*: it produces no managed table and no
+environment view; instead its (resolved) query result is written to a
+destination. Two families:
+
+- **files** — ``to: parquet|csv|json`` + ``path``, via DuckDB ``COPY``.
+- **tables** (reverse ETL) — ``to: table`` + ``target: <alias>.<schema>.<table>``
+  where ``alias`` is a database attached via the project's ``attach:`` config
+  (Postgres, SQLite, another DuckDB, ...). ``mode`` picks the delivery:
+  ``replace`` (DELETE all + INSERT — the live table is never dropped, so grants
+  and readers survive), ``append``, or the keyed ``merge_by_key`` /
+  ``full_merge`` — which reuse the *same strategy AST builders* as managed
+  models, pointed at the external catalog.
+
+Exports are side-effecting — no view-swap rollback (see v2-design §6).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import sqlglot
+from sqlglot import exp
+
+from interlace.engines.base import EngineCaps
+from interlace.exceptions import ConfigurationError, PlanError
+from interlace.ir.relation import EngineRef, SqlRelation, TableRef
+from interlace.ir.schema import empty_schema
+from interlace.strategies.base import RowCounts
+
+_FILE_FORMATS = frozenset({"parquet", "csv", "json"})
+_TABLE_MODES = frozenset({"replace", "append", "merge_by_key", "full_merge"})
+
+
+@dataclass(frozen=True)
+class ExportConfig:
+    """Where a sink writes. ``to`` is the destination type; ``path`` (files) or
+    ``target`` + ``mode`` (+ ``key`` for keyed modes) for tables."""
+
+    to: str
+    path: str = ""
+    target: str = ""
+    mode: str = "replace"
+    key: tuple[str, ...] = ()
+
+    @classmethod
+    def from_dict(cls, data: Any) -> ExportConfig:
+        if not isinstance(data, dict) or "to" not in data:
+            raise ConfigurationError("export requires 'to'", details={"got": data})
+        to = str(data["to"])
+        key = data.get("key") or ()
+        config = cls(
+            to=to,
+            path=str(data.get("path", "")),
+            target=str(data.get("target", "")),
+            mode=str(data.get("mode", "replace")),
+            key=(key,) if isinstance(key, str) else tuple(key),
+        )
+        if to in _FILE_FORMATS and not config.path:
+            raise ConfigurationError(f"export to {to!r} requires 'path'", details={"got": data})
+        if to == "table":
+            if not config.target:
+                raise ConfigurationError("export to table requires 'target'", details={"got": data})
+            if config.mode not in _TABLE_MODES:
+                raise ConfigurationError(f"unknown export mode {config.mode!r}; expected one of {sorted(_TABLE_MODES)}")
+            if config.mode in ("merge_by_key", "full_merge") and not config.key:
+                raise ConfigurationError(f"export mode {config.mode!r} requires 'key'", details={"got": data})
+        return config
+
+
+def export_target_ref(target: str) -> TableRef:
+    parts = target.split(".")
+    if len(parts) == 3:
+        return TableRef(catalog=parts[0], schema=parts[1], name=parts[2])
+    if len(parts) == 2:
+        return TableRef(catalog=parts[0], schema="main", name=parts[1])
+    raise PlanError(
+        f"export target {target!r} must be <alias>.<schema>.<table> (or <alias>.<table> for the main schema)"
+    )
+
+
+def table_export_statements(
+    export: ExportConfig,
+    query: exp.Expression,
+    dialect: str,
+    engine: str = "default",
+    columns: Sequence[str] | None = None,
+) -> list[exp.Expression]:
+    """Deliver ``query`` into the external table — never DROP it (grants/readers survive).
+
+    ``columns`` names the target's column order when the source has been aligned to an
+    existing target (see ``plan.apply._deliver_table_export``): replace/append inserts
+    then carry an explicit column list. The keyed modes reuse the strategy builders,
+    whose inserts bind positionally — safe because the aligned projection reproduces
+    the target's column order exactly."""
+    from interlace.strategies import FullMerge, MergeByKey  # runtime import: strategies build on ir like this module
+
+    target = export_target_ref(export.target)
+    table = target.to_expr()
+    relation = SqlRelation(ast=query, engine=EngineRef(name=engine, dialect=dialect), schema=empty_schema())
+
+    if export.mode == "merge_by_key":
+        return MergeByKey(export.key).plan_statements(relation, target, EngineCaps())
+    if export.mode == "full_merge":
+        return FullMerge(export.key).plan_statements(relation, target, EngineCaps())
+
+    derived = exp.select("*").from_(exp.Subquery(this=query.copy(), alias=exp.TableAlias(this="_s")))
+    ensure = exp.Create(this=table.copy(), kind="TABLE", exists=True, expression=derived.copy().limit(0))
+    insert_this: exp.Expression = table.copy()
+    if columns:
+        insert_this = exp.Schema(this=table.copy(), expressions=[exp.to_identifier(c) for c in columns])
+    insert = exp.Insert(this=insert_this, expression=query.copy())
+    if export.mode == "append":
+        return [ensure, insert]
+    wipe = exp.Delete(this=table.copy())  # replace: empty in place, never drop
+    return [ensure, wipe, insert]
+
+
+def export_row_counts(export: ExportConfig, counts: Sequence[int]) -> RowCounts:
+    """Interpret a table delivery's per-statement counts for its mode."""
+    from interlace.strategies import FullMerge, MergeByKey
+
+    if export.mode == "merge_by_key":
+        return MergeByKey(export.key).row_counts(counts)
+    if export.mode == "full_merge":
+        return FullMerge(export.key).row_counts(counts)
+    if export.mode == "append":  # [ensure, insert]
+        return RowCounts(inserted=counts[1] if len(counts) > 1 else 0)
+    # replace: [ensure, wipe, insert] — the wipe clears the previous delivery
+    return RowCounts(inserted=counts[2] if len(counts) > 2 else 0, deleted=counts[1] if len(counts) > 1 else 0)
+
+
+def export_statements(
+    export: ExportConfig, query: exp.Expression, resolved_path: str, dialect: str
+) -> list[exp.Expression]:
+    """Build the statements that write ``query`` to a file export destination."""
+    if export.to not in _FILE_FORMATS:
+        raise PlanError(f"unsupported export destination: {export.to!r}", details={"to": export.to})
+    options = "FORMAT csv, HEADER" if export.to == "csv" else f"FORMAT {export.to}"
+    query_sql = query.sql(dialect=dialect)
+    escaped = resolved_path.replace("'", "''")
+    return [sqlglot.parse_one(f"COPY ({query_sql}) TO '{escaped}' ({options})", read=dialect)]

interlace/graph/__init__.py

@@ -0,0 +1,17 @@
+"""Dependency graph, compilation, lineage, and selectors."""
+
+from __future__ import annotations
+
+from interlace.graph.column_lineage import column_lineage
+from interlace.graph.dag import DependencyGraph
+from interlace.graph.project import CompiledModel, CompiledProject, compile_models
+from interlace.graph.selectors import select_models
+
+__all__ = [
+    "CompiledModel",
+    "CompiledProject",
+    "DependencyGraph",
+    "column_lineage",
+    "compile_models",
+    "select_models",
+]

interlace/graph/column_lineage.py

@@ -0,0 +1,69 @@
+"""Column-level lineage.
+
+For each model output column, which upstream ``(table, column)`` it derives from.
+Built in topological order: each model's SQL is qualified against a schema graph
+accumulated from upstream models, ``*`` and unqualified columns are resolved, and
+the columns feeding each projection are extracted. Best-effort — a model whose
+SQL can't be qualified (e.g. a Python model, or an unresolvable query) yields no
+column lineage rather than failing the whole project.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlglot import exp
+from sqlglot.optimizer.qualify import qualify
+
+from interlace.graph.project import CompiledProject
+
+ColumnSources = dict[str, list[tuple[str, str]]]  # output column -> [(table, column), ...]
+
+
+def _table_name(table: exp.Table) -> str:
+    return f"{table.db}.{table.name}" if table.db else table.name
+
+
+def _insert_schema(schema: dict[str, Any], model_name: str, columns: dict[str, str]) -> None:
+    """Insert a model's columns into the (possibly nested) schema graph by name parts."""
+    *namespaces, leaf = model_name.split(".")
+    node = schema
+    for namespace in namespaces:
+        node = node.setdefault(namespace, {})
+    node[leaf] = columns
+
+
+def _model_lineage(ast: exp.Expression, schema: dict[str, Any], dialect: str) -> ColumnSources | None:
+    try:
+        qualified = qualify(ast.copy(), schema=schema, dialect=dialect)
+    except Exception:
+        return None
+    if not isinstance(qualified, exp.Select):
+        return None
+
+    aliases = {table.alias_or_name: _table_name(table) for table in qualified.find_all(exp.Table)}
+    lineage: ColumnSources = {}
+    for projection in qualified.selects:
+        sources: list[tuple[str, str]] = []
+        for column in projection.find_all(exp.Column):
+            ref = (aliases.get(column.table, column.table), column.name)
+            if ref not in sources:
+                sources.append(ref)
+        lineage[projection.alias_or_name] = sources
+    return lineage
+
+
+def column_lineage(project: CompiledProject) -> dict[str, ColumnSources]:
+    """Compute per-model column lineage for the whole project (topological order)."""
+    schema: dict[str, Any] = {}
+    result: dict[str, ColumnSources] = {}
+    for name in project.graph.topological_sort():
+        model = project.models[name]
+        if model.ast is None:
+            result[name] = {}
+            continue
+        lineage = _model_lineage(model.ast, schema, model.dialect)
+        result[name] = lineage or {}
+        if lineage is not None:
+            _insert_schema(schema, name, dict.fromkeys(lineage, "UNKNOWN"))
+    return result

interlace/graph/dag.py

@@ -0,0 +1,81 @@
+"""The dependency DAG.
+
+A directed acyclic graph of model names with edges pointing from a node to its
+upstreams. Kahn's algorithm gives a deterministic topological order (upstreams
+before downstreams); a short order means a cycle. No third-party graph library —
+this is ~40 lines of stdlib.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable
+
+from interlace.exceptions import DependencyError
+
+
+class DependencyGraph:
+    """Model names and their upstream dependencies."""
+
+    def __init__(self) -> None:
+        self._upstreams: dict[str, set[str]] = {}
+
+    def add_node(self, name: str) -> None:
+        self._upstreams.setdefault(name, set())
+
+    def add_dependency(self, node: str, upstream: str) -> None:
+        """Record that ``node`` depends on ``upstream``. Self-edges are ignored."""
+        self.add_node(node)
+        self.add_node(upstream)
+        if node != upstream:
+            self._upstreams[node].add(upstream)
+
+    def nodes(self) -> list[str]:
+        return list(self._upstreams)
+
+    def upstreams(self, node: str) -> set[str]:
+        return set(self._upstreams.get(node, set()))
+
+    def downstreams(self, node: str) -> set[str]:
+        return {n for n, ups in self._upstreams.items() if node in ups}
+
+    def ancestors(self, node: str) -> set[str]:
+        """All transitive upstreams of ``node``."""
+        return self._reach(node, self.upstreams)
+
+    def descendants(self, node: str) -> set[str]:
+        """All transitive downstreams of ``node``."""
+        return self._reach(node, self.downstreams)
+
+    def _reach(self, node: str, step: Callable[[str], set[str]]) -> set[str]:
+        result: set[str] = set()
+        stack = list(step(node))
+        while stack:
+            current = stack.pop()
+            if current not in result:
+                result.add(current)
+                stack.extend(step(current))
+        return result
+
+    def topological_sort(self) -> list[str]:
+        """Return nodes ordered upstreams-first. Raises ``DependencyError`` on a cycle."""
+        indegree = {n: len(ups) for n, ups in self._upstreams.items()}
+        adjacency: dict[str, list[str]] = {n: [] for n in self._upstreams}
+        for node, ups in self._upstreams.items():
+            for upstream in ups:
+                adjacency[upstream].append(node)
+
+        queue = deque(sorted(n for n, deg in indegree.items() if deg == 0))
+        order: list[str] = []
+        while queue:
+            node = queue.popleft()
+            order.append(node)
+            for downstream in sorted(adjacency[node]):
+                indegree[downstream] -= 1
+                if indegree[downstream] == 0:
+                    queue.append(downstream)
+
+        if len(order) != len(self._upstreams):
+            cyclic = sorted(set(self._upstreams) - set(order))
+            raise DependencyError("dependency cycle detected", details={"nodes": cyclic})
+        return order

interlace/graph/project.py

@@ -0,0 +1,242 @@
+"""Compile declared models into a fingerprinted dependency graph.
+
+Takes the registry's :class:`ModelDef`s and produces a :class:`CompiledProject`:
+each model parsed (SQL) or source-hashed (Python), its dependencies resolved
+(explicit ``depends_on`` plus implicit table references that match a known
+model), topologically ordered, and fingerprinted upstream-first. The plan step
+consumes this — diffing fingerprints against the state store to classify changes
+and build the snapshots it persists.
+"""
+
+from __future__ import annotations
+
+import inspect
+import textwrap
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from sqlglot import exp
+
+from interlace.checks.spec import CheckSpec
+from interlace.dsl.decorators import CheckDef, ModelDef, ModelFn
+from interlace.exceptions import DefinitionError
+from interlace.exports import ExportConfig
+from interlace.graph.dag import DependencyGraph
+from interlace.ir.canonicalize import parse, table_references
+from interlace.ir.fingerprint import canonical_sql, data_fingerprint, metadata_fingerprint
+from interlace.ir.relation import TableRef
+
+_PHYSICAL_PREFIX = "interlace__"
+
+
+@dataclass(frozen=True)
+class CompiledModel:
+    """A model resolved to a fingerprint, physical table, and dependency set."""
+
+    name: str
+    dialect: str
+    engine: str  # named engine that executes and stores this model
+    dependencies: tuple[str, ...]
+    fingerprint: str  # full: SQL + config + upstream fingerprints
+    local_fingerprint: str  # SQL + config only — separates direct from indirect changes
+    metadata_hash: str
+    definition_sql: str | None  # canonical SQL, for change classification (None for Python models)
+    physical_table: TableRef
+    materialise: str
+    strategy: str
+    key: tuple[str, ...]  # business key for keyed strategies (merge_by_key)
+    time_column: str | None  # partition column for incremental_by_time
+    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")
+    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
+    export: ExportConfig | None  # presence makes this a sink (no physical table/view)
+    ast: exp.Expression | None  # parsed SQL, or None for Python models
+    owner: str | None = None  # surfaced in the catalog/API (metadata, not fingerprinted into data)
+    description: str | None = None
+    fn: ModelFn | None = None  # the Python model function (source is fingerprinted; None for SQL)
+    checks: tuple[CheckSpec, ...] = ()  # metadata-fingerprinted: changing a check never rebuilds data
+
+
+@dataclass
+class CompiledProject:
+    """All compiled models plus the dependency graph that orders them."""
+
+    models: dict[str, CompiledModel]
+    graph: DependencyGraph
+    python_checks: dict[str, tuple[CheckDef, ...]] = field(default_factory=dict)  # @check fns by model
+
+    def ordered(self) -> list[CompiledModel]:
+        return [self.models[name] for name in self.graph.topological_sort()]
+
+
+def _split_name(name: str) -> tuple[str, str]:
+    schema, _, base = name.rpartition(".")
+    return (schema or "main"), base
+
+
+def _physical_table(name: str, fingerprint: str, catalog: str | None) -> TableRef:
+    schema, base = _split_name(name)
+    return TableRef(schema=f"{_PHYSICAL_PREFIX}{schema}", name=f"{base}__{fingerprint}", catalog=catalog)
+
+
+def _resolve_dependencies(
+    model: ModelDef, names: set[str], default_dialect: str
+) -> tuple[tuple[str, ...], exp.Expression | None, str]:
+    dialect = model.dialect or default_dialect
+    deps: list[str] = []
+    seen: set[str] = set()
+
+    def add(candidate: str) -> None:
+        if candidate != model.name and candidate in names and candidate not in seen:
+            seen.add(candidate)
+            deps.append(candidate)
+
+    for explicit in model.depends_on:
+        add(explicit)
+
+    ast: exp.Expression | None = None
+    if model.sql is not None:
+        ast = parse(model.sql, dialect)
+        for ref in table_references(ast):
+            if ref in names:
+                add(ref)
+            else:
+                add(ref.rsplit(".", 1)[-1])  # match a qualified ref to a model by its tail
+
+    return tuple(deps), ast, dialect
+
+
+def _fingerprint_query(model: ModelDef, ast: exp.Expression | None) -> str | exp.Expression:
+    if ast is not None:
+        return ast
+    if model.fn is not None:
+        return textwrap.dedent(inspect.getsource(model.fn))
+    raise DefinitionError(f"model {model.name!r} has neither SQL nor a function body")
+
+
+def compile_models(
+    models: Iterable[ModelDef],
+    *,
+    default_dialect: str = "duckdb",
+    default_engine: str = "default",
+    engine_dialects: dict[str, str] | None = None,
+    known_engines: set[str] | None = None,
+    catalog: str | None = None,
+    checks: Iterable[CheckDef] = (),
+) -> CompiledProject:
+    """Compile models into a fingerprinted, topologically-ordered project.
+
+    ``checks`` are ``@check``-decorated Python functions, attached by model name.
+    ``engine_dialects`` maps engine name → sqlglot dialect (used when a model
+    omits ``dialect``). ``known_engines`` validates model ``engine`` pins.
+    """
+    definitions = {m.name: m for m in models}
+    names = set(definitions)
+    dialects_by_engine = engine_dialects or {}
+    engines = known_engines
+
+    resolved: dict[str, tuple[tuple[str, ...], exp.Expression | None, str, str]] = {}
+    graph = DependencyGraph()
+    for name, definition in definitions.items():
+        engine = definition.engine or default_engine
+        if engines is not None and engine not in engines:
+            raise DefinitionError(
+                f"model {name!r} references unknown engine {engine!r}",
+                details={"engines": sorted(engines)},
+            )
+        # Authoring dialect: explicit model dialect, else the engine's, else project default.
+        model_default_dialect = dialects_by_engine.get(engine, default_dialect)
+        deps, ast, dialect = _resolve_dependencies(definition, names, model_default_dialect)
+        resolved[name] = (deps, ast, dialect, engine)
+        graph.add_node(name)
+        for dep in deps:
+            graph.add_dependency(name, dep)
+
+    compiled: dict[str, CompiledModel] = {}
+    for name in graph.topological_sort():  # upstreams first; raises on cycle
+        definition = definitions[name]
+        deps, ast, dialect, engine = resolved[name]
+        for dep in deps:  # topo order: deps already compiled
+            if compiled[dep].engine != engine and compiled[dep].materialise == "ephemeral":
+                raise DefinitionError(
+                    f"model {name!r} on engine {engine!r} inlines ephemeral {dep!r} declared on engine "
+                    f"{compiled[dep].engine!r}; an ephemeral model must share its consumers' engine "
+                    f"(see docs/architecture/MULTI_ENGINE.md)"
+                )
+        strategy_config = {
+            "materialise": definition.materialise,
+            "strategy": definition.strategy,
+            "key": list(definition.key),
+            "interval": definition.interval,
+            "time_column": definition.time_column,
+            "cursor": definition.cursor,
+            "engine": engine,
+            "export": (
+                {
+                    "to": definition.export.to,
+                    "path": definition.export.path,
+                    "target": definition.export.target,
+                    "mode": definition.export.mode,
+                    "key": list(definition.export.key),
+                }
+                if definition.export
+                else None
+            ),
+            "dialect": dialect,
+        }
+        query = _fingerprint_query(definition, ast)
+        # render the canonical SQL once: it feeds both fingerprints and definition_sql
+        canonical = canonical_sql(query) if isinstance(query, exp.Expression) else query
+        local_fingerprint = data_fingerprint(query=canonical, strategy_config=strategy_config, upstream_fingerprints=[])
+        fingerprint = data_fingerprint(
+            query=canonical,
+            strategy_config=strategy_config,
+            upstream_fingerprints=[compiled[dep].fingerprint for dep in deps],
+        )
+        metadata_hash = metadata_fingerprint(
+            {
+                "owner": definition.owner,
+                "tags": list(definition.tags),
+                "description": definition.description,
+                "checks": [
+                    {"type": c.type, "columns": list(c.columns), "severity": c.severity, "params": c.params}
+                    for c in definition.checks
+                ],
+            }
+        )
+        compiled[name] = CompiledModel(
+            name=name,
+            dialect=dialect,
+            engine=engine,
+            dependencies=deps,
+            fingerprint=fingerprint,
+            local_fingerprint=local_fingerprint,
+            metadata_hash=metadata_hash,
+            definition_sql=canonical if ast is not None else None,
+            physical_table=_physical_table(name, fingerprint, catalog),
+            materialise=definition.materialise,
+            strategy=definition.strategy,
+            key=definition.key,
+            time_column=definition.time_column,
+            cursor=definition.cursor,
+            interval=definition.interval,
+            tags=definition.tags,
+            schedule=definition.schedule,
+            columns=definition.columns,
+            export=definition.export,
+            ast=ast,
+            owner=definition.owner,
+            description=definition.description,
+            fn=definition.fn,
+            checks=definition.checks,
+        )
+
+    python_checks: dict[str, tuple[CheckDef, ...]] = {}
+    for check in checks:
+        if check.model not in compiled:
+            raise DefinitionError(f"@check {check.name!r} references unknown model {check.model!r}")
+        python_checks[check.model] = (*python_checks.get(check.model, ()), check)
+
+    return CompiledProject(models=compiled, graph=graph, python_checks=python_checks)

interlace/graph/selectors.py

@@ -0,0 +1,45 @@
+"""dbt-style model selection.
+
+A selector is one of: ``model`` (exact), ``+model`` (model + ancestors),
+``model+`` (model + descendants), ``+model+`` (both), or ``tag:<name>``. Multiple
+selectors (space- or comma-separated, or repeated) union together. An empty
+selector list means "all models".
+"""
+
+from __future__ import annotations
+
+from interlace.exceptions import SelectionError
+from interlace.graph.project import CompiledProject
+
+
+def select_models(selectors: list[str], project: CompiledProject) -> set[str]:
+    if not selectors:
+        return set(project.models)
+    chosen: set[str] = set()
+    for raw in selectors:
+        for token in _tokens(raw):
+            chosen |= _resolve(token, project)
+    return chosen
+
+
+def _tokens(raw: str) -> list[str]:
+    return [token for token in raw.replace(",", " ").split() if token]
+
+
+def _resolve(token: str, project: CompiledProject) -> set[str]:
+    if token.startswith("tag:"):
+        tag = token[4:]
+        return {name for name, model in project.models.items() if tag in model.tags}
+
+    include_ancestors = token.startswith("+")
+    include_descendants = token.endswith("+")
+    name = token.strip("+")
+    if name not in project.models:
+        raise SelectionError(f"unknown model in selector: {name!r}", details={"selector": token})
+
+    chosen = {name}
+    if include_ancestors:
+        chosen |= project.graph.ancestors(name)
+    if include_descendants:
+        chosen |= project.graph.descendants(name)
+    return chosen