ripple-sql 0.1.0__py3-none-any.whl

ripple/graph.py

@@ -0,0 +1,1499 @@
+"""Cross-model column lineage graph.
+
+Runs the engine over every model in a Project (parents before children) and
+stitches per-statement lineage into one graph that can answer:
+
+- breaks(model.column): everything downstream that would be affected
+- trace(model.column): where a column's value comes from, hop by hop
+- to_dict(): the full graph for the canvas, MCP, and CI bot
+
+Honesty model, in order of what can go wrong:
+- every edge carries confidence (0..1) and a trust label
+  (verified / high_confidence / moderate / review_required)
+- trust is always the WORST of: the engine's label, the label implied by
+  confidence, how the source table's name resolved, and the evidence tier
+  (compiled manifest vs raw Jinja vs plain files)
+- a model that yields no lineage still appears, connected to its declared
+  parents by wildcard edges at review_required, so nothing downstream of a
+  failed model is ever hidden
+- an unknown model or column raises with suggestions; it never returns an
+  empty result that reads as "safe"
+"""
+
+from __future__ import annotations
+
+import difflib
+import logging
+from collections import defaultdict, deque
+from dataclasses import dataclass, field
+
+from ripple.engine.budget import TIMED_OUT, budget_seconds, max_sql_bytes, run_within_budget
+from ripple.engine.dispatch import extract_lineage_complete
+from ripple.engine.jinja import convert_jinja_to_sql
+from ripple.engine.preprocess import prepare_sql_for_parse
+from ripple.loaders.identity import _name_suffixes
+from ripple.loaders.identity import strip_placeholders as _strip_placeholders
+from ripple.project import Model, Project
+
+logger = logging.getLogger(__name__)
+
+# worst first; every combinator takes the minimum index
+TRUST_ORDER = ["review_required", "moderate", "high_confidence", "verified"]
+
+# evidence mode -> maximum trust an edge can claim
+EVIDENCE_CAP = {
+    "manifest": "verified",
+    "raw_jinja": "high_confidence",
+    "plain_sql": "high_confidence",
+}
+
+WILDCARD = "*"
+
+
+def _trust_from_confidence(confidence: float) -> str:
+    if confidence >= 1.0:
+        return "verified"
+    if confidence >= 0.8:
+        return "high_confidence"
+    if confidence >= 0.5:
+        return "moderate"
+    return "review_required"
+
+
+def _worst_trust(*labels: str) -> str:
+    return min(labels, key=TRUST_ORDER.index)
+
+
+class UnknownTarget(LookupError):
+    def __init__(self, message: str, suggestions: list[str]):
+        super().__init__(message)
+        self.suggestions = suggestions
+
+
+@dataclass(frozen=True)
+class Edge:
+    src_model: str
+    src_column: str
+    dst_model: str
+    dst_column: str
+    confidence: float
+    trust: str
+    kind: str  # "value" | "filter" | "join" | "window"
+    reason: str = ""  # why trust was downgraded, "" if clean
+
+    def key(self) -> tuple:
+        return (self.src_model, self.src_column, self.dst_model, self.dst_column, self.kind)
+
+
+@dataclass
+class ModelReport:
+    name: str
+    status: str = "failed"  # "ok" | "star_only" | "fallback" | "failed" | "no_sql" | "timed_out"
+    columns: list[str] = field(default_factory=list)
+    error: str | None = None
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def parsed(self) -> bool:
+        return self.status in ("ok", "star_only")
+
+
+@dataclass
+class LineageGraph:
+    project: Project
+    edges: list[Edge] = field(default_factory=list)
+    reports: dict[str, ModelReport] = field(default_factory=dict)
+    _jinja_env: object = None
+    _candidates: dict[str, list[str]] = field(default_factory=dict)
+    _all_candidates: dict[str, list[str]] = field(default_factory=dict)
+    _stem_aliases: set[str] = field(default_factory=set)
+    _models_by_name: dict = None
+    _reads_cache: dict = None
+    _down: dict = None
+    _down_by_model: dict = None
+    _up: dict = None
+    # (dst_model, src_model) -> lowercased except-list of that star edge
+    _star_excepts: dict = field(default_factory=dict)
+    # lowered names of function-minted models (TVFs); call sites bind these
+    _function_relations: set = field(default_factory=set)
+
+    # ---- build ----
+
+    @classmethod
+    def build(cls, project: Project) -> LineageGraph:
+        graph = cls(project=project)
+        graph._candidates = project.name_candidates
+        graph._all_candidates = project.all_name_candidates
+        graph._stem_aliases = project.stem_alias_names
+        real_tables = set(graph._candidates.keys())
+        # a call of a minted TVF by its written name binds that model
+        # instead of degrading as a function/relation collision (F11)
+        graph._function_relations = {
+            m.name.lower() for m in project.models if getattr(m, "is_function", False)
+        }
+        if any(m.evidence != "manifest" for m in project.models):
+            from ripple.render import build_project_environment
+
+            graph._jinja_env = build_project_environment(
+                project.macro_sources,
+                root_package=project.package_name,
+                dialect=project.dialect,
+                project_vars=project.jinja_vars,
+            )
+        for model in graph._topological(project.models):
+            graph._add_model(model, real_tables)
+        graph._fallback_edges()
+        graph._add_downstream()
+        graph._dedupe()
+        graph._index()
+        return graph
+
+    def _topological(self, models: list[Model]) -> list[Model]:
+        """Parents before children, so a child's SELECT * can expand through
+        the columns its parents were just found to have. Cycles and unknown
+        parents fall back to input order at the end."""
+        by_name = {m.name: m for m in models}
+        state: dict[str, int] = {}  # 1 = on stack, 2 = done
+        order: list[Model] = []
+        for root in models:
+            stack: list[tuple[str, bool]] = [(root.name, False)]
+            while stack:
+                name, children_done = stack.pop()
+                if state.get(name) == 2:
+                    continue
+                model = by_name.get(name)
+                if model is None:
+                    state[name] = 2
+                    continue
+                if children_done:
+                    state[name] = 2
+                    order.append(model)
+                    continue
+                if state.get(name) == 1:  # cycle; settle in stack order
+                    continue
+                state[name] = 1
+                stack.append((name, True))
+                for parent in model.declared_parents:
+                    # every candidate, not just the first: a name shared by
+                    # dialect variants must not leave the real one unordered
+                    for candidate in self._all_candidates.get(parent.lower(), ()):
+                        if not state.get(candidate):
+                            stack.append((candidate, False))
+        return order
+
+    def _parent_schema(self, model: Model) -> dict[str, dict[str, str]]:
+        """The project as its own schema: every known column of this model's
+        parents, keyed by each name the SQL might use for them."""
+        if self._models_by_name is None:
+            self._models_by_name = {
+                m.name: m for m in [*self.project.models, *self.project.sources]
+            }
+        schema: dict[str, dict[str, str]] = {}
+        bare_claims: dict[str, dict[str, dict[str, str]]] = {}
+        for parent in model.declared_parents:
+            # binding stays enabled-only, but a model's own star expansion may
+            # read a disabled parent's columns (dbt disables whole branches)
+            resolved = self._candidates.get(parent.lower()) or self._all_candidates.get(
+                parent.lower()
+            )
+            if "." not in parent:
+                # the declared parent is bare; the SQL may have written it
+                # qualified, and an ingested table answers only to that
+                # spelling when another model owns the bare name (Mozilla's
+                # mdn_fred.events_stream beside a model named events_stream)
+                for read in self._reads_as_written(model) or ():
+                    if "." in read and read.split(".")[-1] == parent.lower():
+                        for c in self._candidates.get(read, ()):
+                            if c not in (resolved or []):
+                                resolved = [*(resolved or []), c]
+            if not resolved:
+                continue
+            # a bare parent shared by two relations (Mozilla's telemetry
+            # view over telemetry_derived, same table name) is settled by
+            # the spelling the SQL wrote, exactly as edges are; the old
+            # first-candidate pick stays only when nothing disambiguates
+            bound = [c for c in resolved if self._parent_binds(model, parent, c)]
+            chosen = bound[0] if len(bound) == 1 else resolved[0]
+            if not self._parent_binds(model, parent, chosen):
+                # refused spelling: supplying the bare relation's columns
+                # would fabricate them onto the external (cycle-11, F3)
+                continue
+            report = self.reports.get(chosen)
+            parent_model = self._models_by_name.get(chosen)
+            if report is not None and report.status == "ok":
+                known = report.columns
+            elif report is None and parent_model is not None:
+                # a source never gets a report; ingested warehouse schemas
+                # give it declared columns, which are as good as analyzed ones
+                known = parent_model.declared_columns
+            else:
+                continue
+            if not known:
+                continue
+            columns = {c: "unknown" for c in known if c != WILDCARD}
+            names = {chosen, *(parent_model.aliases if parent_model else set())}
+            for name in names:
+                schema[name] = columns
+            bare_claims.setdefault(chosen.split(".")[-1].lower(), {}).setdefault(chosen, columns)
+        # the engine expands a star by the bare table name; a qualified
+        # parent whose bare spelling another model owns (Mozilla's
+        # mdn_fred.events_stream beside a model named events_stream) still
+        # gets it HERE, per model, unless two of this model's own parents
+        # share it, which would be a guess
+        for bare, owners in bare_claims.items():
+            if len(owners) == 1 and bare not in schema:
+                schema[bare] = next(iter(owners.values()))
+        return schema
+
+    def _add_model(self, model: Model, real_tables: set[str]) -> None:
+        report = ModelReport(name=model.name)
+        self.reports[model.name] = report
+        if model.load_error:
+            report.status = "timed_out"
+            report.error = model.load_error
+            return
+        if not model.sql.strip():
+            if model.declared_columns:
+                # a base table from CREATE TABLE: no derivation, but its columns
+                # are known, so downstream SELECT * resolves against them
+                report.columns = list(model.declared_columns)
+                report.status = "ok"
+            else:
+                report.status = "no_sql"
+                report.error = "no SQL"
+            return
+        self._analyze_sql(model, model.sql, real_tables, report, primary=True)
+        # a table built by CREATE plus UPDATEs is one model; each further
+        # statement adds its lineage to the union (nycdb, PR #28 gap 3)
+        for extra in model.extra_sqls:
+            self._analyze_sql(model, extra, real_tables, report, primary=False)
+
+    def _analyze_sql(
+        self,
+        model: Model,
+        sql: str,
+        real_tables: set[str],
+        report: ModelReport,
+        primary: bool,
+    ) -> None:
+        edge_start = len(self.edges)
+        limit = max_sql_bytes()
+        if limit and len(sql) > limit:
+            message = (
+                f"statement is {len(sql) / 1e6:.1f}MB, over the {limit / 1e6:g}MB analysis "
+                "limit; generated SQL this size wedges the parser for minutes "
+                "(RIPPLE_MAX_SQL_BYTES to raise, 0 to disable)"
+            )
+            if primary:
+                report.status = "timed_out"
+                report.error = f"{message}: {model.path}"
+            else:
+                report.warnings.append(message)
+            return
+        # computed before the worker: it caches onto self, and the worker must
+        # stay pure so an abandoned one cannot race the build
+        warehouse_columns = self._parent_schema(model) if model.declared_parents else None
+        dialect = model.dialect or self.project.dialect
+
+        def analyze():
+            body = sql
+            jinja_cleaner = None
+            if model.evidence != "manifest" and ("{{" in body or "{%" in body):
+                try:  # tier b: real Jinja render beats regex stripping
+                    from ripple.render import render_dbt_sql
+
+                    declared = (
+                        model.jinja_vars
+                        if model.jinja_vars is not None
+                        else self.project.jinja_vars
+                    )
+                    body = render_dbt_sql(
+                        body, model.name, env=self._jinja_env, jinja_vars=declared
+                    )
+                    # rendered SQL has no Jinja left; re-cleaning it corrupts
+                    # regex literals and $-quoted strings in the output
+                except Exception:
+                    jinja_cleaner = convert_jinja_to_sql  # tier c: regex cleaner on the raw SQL
+            extracted = extract_lineage_complete(
+                body,
+                dialect=dialect,
+                real_tables=real_tables,
+                warehouse_columns=warehouse_columns or None,
+                clean_jinja_func=jinja_cleaner,
+                function_relations=self._function_relations or None,
+                # a CTE named after this model shadows only itself; without
+                # this, dbt's `with X as (...) select * from X` house style
+                # marks every correct pass-through edge review_required
+                self_names={model.name, *model.aliases, *model.stem_aliases},
+            )
+            # the same pre-parse pipeline the engine used, or these reparses
+            # drift and drop edges (cycle-10 review, F8)
+            prepared, _ = prepare_sql_for_parse(body, dialect, jinja_cleaner)
+            return extracted, prepared, self._alias_map(prepared, dialect=dialect)
+
+        # the loader's budget caps parse time, but a file can parse fast and
+        # wedge HERE: a generated 3.7MB one-liner parsed in 13s, then spent
+        # 139s inside qualify_tables. Same budget, same honest report.
+        try:
+            outcome = run_within_budget(model.name, analyze)
+        except Exception as e:  # a model that won't parse is a report, not a crash
+            if primary:
+                report.error = f"{type(e).__name__}: {e}"
+            else:
+                report.warnings.append(f"additional statement failed: {type(e).__name__}: {e}")
+            return
+        if outcome is TIMED_OUT:
+            message = (
+                f"analysis exceeded the {budget_seconds():g}s per-file budget: "
+                f"{model.path} (RIPPLE_PARSE_BUDGET_S to raise)"
+            )
+            if primary:
+                report.status = "timed_out"
+                report.error = message
+            else:
+                report.warnings.append(message)
+            return
+        result, prepared_sql, alias_map = outcome
+
+        columns = [c.lower() for c in result.contributing]
+        if primary:
+            report.columns = columns
+        else:
+            report.columns.extend(c for c in columns if c not in report.columns)
+        real_columns = [c for c in columns if c != WILDCARD and c != "null"]
+        if real_columns:
+            if not primary and report.status == "star_only":
+                # the state must read like any partially-starred model:
+                # status ok, no stale error (the cycle-6 review)
+                report.error = None
+            report.status = "ok"
+        elif primary:
+            if columns:
+                report.status = "star_only"
+                report.error = "only SELECT * survived; column-level lineage unavailable"
+            else:
+                report.error = "no columns extracted"
+                return
+        new_warnings = [str(w.get("warning", w)) for w in result.warnings]
+        if primary:
+            report.warnings = new_warnings
+        else:
+            report.warnings.extend(new_warnings)
+
+        # project-inferred schema is good evidence, not warehouse-verified truth
+        cap = EVIDENCE_CAP.get(model.evidence, "high_confidence")
+        if result.qualified_via_schema:
+            cap = _worst_trust(cap, "high_confidence")
+
+        for out_column, upstream_columns in result.contributing.items():
+            for src in upstream_columns:
+                before = len(self.edges)
+                self._append_edge(
+                    model,
+                    out_column.lower(),
+                    src.get("table"),
+                    src.get("column"),
+                    src.get("confidence", 0.5),
+                    src.get("trust_level"),
+                    "value",
+                    cap,
+                )
+                excepted = src.get("except_columns")
+                if excepted and out_column == WILDCARD:
+                    # spellings kept as normalized upstream (quoted
+                    # mixed-case stays exact, F20); same-pair excepts merge
+                    # by union so a column excluded in any union branch
+                    # refuses (F7)
+                    for e in self.edges[before:]:
+                        if e.src_column == WILDCARD and e.dst_column == WILDCARD:
+                            pair = (e.dst_model, e.src_model)
+                            self._star_excepts[pair] = self._star_excepts.get(
+                                pair, frozenset()
+                            ) | frozenset(excepted)
+
+        # An unqualified filter/join column ("where status = ...") can still be
+        # attributed when THIS statement reads from exactly one upstream
+        # relation, and a query-local alias ("FROM stg_orders o ... WHERE
+        # o.status") resolves through the statement's own alias map. Only this
+        # statement's edges count: borrowing an earlier statement's parents
+        # claimed the CTAS source wrote the UPDATE's filter column (the
+        # review of cycle 6).
+        value_parents = {
+            e.src_model
+            for e in self.edges[edge_start:]
+            if e.dst_model == model.name and e.kind == "value"
+        }
+        sole_parent = next(iter(value_parents)) if len(value_parents) == 1 else None
+        if sole_parent is None and not value_parents and not primary:
+            relations = self._statement_relations(prepared_sql, model.dialect)
+            resolved = {
+                found[0]
+                for name in relations
+                if (found := self._candidates.get(name)) and len(found) == 1
+            }
+            if len(resolved) == 1:
+                sole_parent = next(iter(resolved))
+
+        def resolve_relation(table: str | None) -> str | None:
+            if not table:
+                return sole_parent
+            return alias_map.get(table.lower(), table)
+
+        for filt in result.filter_columns:
+            table = resolve_relation(filt.table)
+            confidence = 0.8 if filt.table else 0.6
+            self._append_edge(
+                model, "(row filter)", table, filt.column, confidence, None, "filter", cap
+            )
+        for key in result.window_keys:
+            table = resolve_relation(key.table)
+            confidence = 0.8 if key.table else 0.6
+            self._append_edge(
+                model, "(window key)", table, key.column, confidence, None, "window", cap
+            )
+        for join in result.join_keys:
+            for table, column in (
+                (join.left_table, join.left_column),
+                (join.right_table, join.right_column),
+            ):
+                self._append_edge(
+                    model,
+                    "(join key)",
+                    resolve_relation(table),
+                    column,
+                    0.8 if table else 0.6,
+                    None,
+                    "join",
+                    cap,
+                )
+
+        # A star chain from an unexpanded upstream (source with no declared
+        # columns) still proves the columns this model itself references in
+        # predicates or join keys: they must exist upstream and SELECT * passes
+        # them through, so they get real value edges instead of vanishing.
+        star_parents = {
+            e.src_model
+            for e in self.edges
+            if e.dst_model == model.name
+            and e.kind == "value"
+            and e.src_column == WILDCARD
+            and e.dst_column == WILDCARD
+        }
+        if star_parents:
+            proven = {(f.table, f.column) for f in result.filter_columns}
+            for join in result.join_keys:
+                proven.add((join.left_table, join.left_column))
+                proven.add((join.right_table, join.right_column))
+            for table, column in sorted(
+                (p for p in proven if p[1]), key=lambda p: (p[0] or "", p[1])
+            ):
+                if column.lower() in report.columns:
+                    continue  # already attributed explicitly
+                candidates, _ = self._resolve_name(
+                    resolve_relation(table), model.declared_parents, model.path
+                )
+                for src_model in candidates:
+                    if src_model not in star_parents:
+                        continue
+                    self.edges.append(
+                        Edge(
+                            src_model=src_model,
+                            src_column=column.lower(),
+                            dst_model=model.name,
+                            dst_column=column.lower(),
+                            confidence=0.6,
+                            trust=_worst_trust("moderate", cap),
+                            kind="value",
+                            reason="column proven by this model's own reference; "
+                            "passed through SELECT *",
+                        )
+                    )
+                    if column.lower() not in report.columns:
+                        report.columns.append(column.lower())
+
+    def _append_edge(
+        self,
+        model: Model,
+        out_column: str,
+        src_table: str | None,
+        src_column: str | None,
+        confidence: float,
+        engine_trust: str | None,
+        kind: str,
+        cap: str,
+    ) -> None:
+        if not src_column:
+            return
+        candidates, quality = self._resolve_name(src_table, model.declared_parents, model.path)
+        if candidates == [model.name] and quality != "exact":
+            # a model cannot be its own upstream: when a QUALIFIED reference's
+            # suffix is the model's own name (pg_attribute.sql reading
+            # pg_catalog.pg_attribute, the staging-wrapper pattern), the SQL
+            # named an external relation, and dropping it as a self-loop
+            # erases the model's entire lineage
+            wrapped = (src_table or "").replace('"', "").replace("`", "").lower()
+            if "." in wrapped:
+                candidates, quality = [wrapped], "unknown"
+                confidence = min(confidence, 0.4)
+        reason = ""
+        if not candidates:
+            if not src_table:
+                return
+            cleaned = src_table.replace('"', "").replace("`", "").lower()
+            if kind in ("filter", "join", "window") and "." not in cleaned:
+                # a query-local alias (FROM orders o) we couldn't resolve to a
+                # model; inventing a phantom node named "o" would be a lie
+                report = self.reports.get(model.name)
+                if report is not None:
+                    report.warnings.append(
+                        f"could not attribute a {kind} on '{cleaned}.{src_column}' to a model"
+                    )
+                return
+            # traced to a table this project doesn't own (external table, CTE
+            # remnant). Keep it, but never at confident trust.
+            candidates = [cleaned]
+            confidence = min(confidence, 0.4)
+            disabled = self._all_candidates.get(cleaned) or self._all_candidates.get(
+                cleaned.split(".")[-1]
+            )
+            if disabled:
+                # snowplow ships one copy of a model per warehouse and dbt
+                # disables all but the target's; a read of the bare name is
+                # not an external table and no ingest resolves it
+                reason = (
+                    f"names only disabled models ({len(disabled)}); "
+                    "enable one or set the dbt target"
+                )
+            else:
+                reason = "source table not found in this project"
+            quality = "unknown"
+        elif quality == "ambiguous":
+            reason = f"name matches {len(candidates)} models; edge added for each"
+        elif quality == "suffix":
+            reason = "matched by table name only; schema differs or is missing"
+        elif quality == "unknown":
+            reason = "source table not found in this project"
+        trust = _worst_trust(
+            engine_trust or "verified",
+            _trust_from_confidence(confidence),
+            cap,
+            "review_required" if quality in ("ambiguous", "suffix", "unknown") else "verified",
+        )
+        if trust == "review_required" and not reason and len(candidates) == 1:
+            # the engine downgraded a read of a column the declared schema
+            # lacks, silently; on balboa an ingest of truncated column lists
+            # took review links from 17 to 106 with no reason on any of them
+            if self._models_by_name is None:
+                self._models_by_name = {
+                    m.name: m for m in [*self.project.models, *self.project.sources]
+                }
+            source = self._models_by_name.get(candidates[0])
+            declared = {c.lower() for c in source.declared_columns} if source else set()
+            if declared and src_column.lower() not in declared and src_column != WILDCARD:
+                reason = (
+                    f"'{src_column}' is not in the declared columns of {candidates[0]}; "
+                    "the declared or ingested column list may be incomplete"
+                )
+        for src_model in candidates:
+            if src_model == model.name and not model.self_read:
+                continue  # self-loop from CTE resolution
+            if (
+                src_model == model.name
+                and kind == "value"
+                and src_column.lower() == out_column.lower()
+            ):
+                # 'names depends on its own prior names' is a tautology, not
+                # lineage; only CROSS-column prior-state edges (address <-
+                # house) carry information (nycdb business_addrs)
+                continue
+            if src_model == model.name and not reason:
+                reason = "prior state of the same table"
+            self.edges.append(
+                Edge(
+                    src_model=src_model,
+                    src_column=src_column.lower(),
+                    dst_model=model.name,
+                    dst_column=out_column if out_column.startswith("(") else out_column.lower(),
+                    confidence=round(confidence, 2),
+                    trust=trust,
+                    kind=kind,
+                    reason=reason,
+                )
+            )
+
+    def _add_downstream(self) -> None:
+        """Append the declared-as-code BI edges (dbt metrics, exposures) so a
+        model column traces to the metric and dashboard it feeds. These are
+        ordinary edges with a trust label, so breaks() reaches them for free."""
+        conf = {"verified": 1.0, "high_confidence": 0.85, "moderate": 0.6, "review_required": 0.4}
+        for d in getattr(self.project, "downstream", []):
+            cands = self._candidates.get(d.src_model.lower())
+            src = cands[0] if cands else d.src_model
+            self.edges.append(
+                Edge(
+                    src_model=src,
+                    src_column=WILDCARD if d.src_column == "*" else d.src_column,
+                    dst_model=d.dst_model,
+                    dst_column=WILDCARD if d.dst_column == "*" else d.dst_column,
+                    confidence=conf.get(d.trust, 0.6),
+                    trust=d.trust,
+                    kind="value",
+                    reason=d.reason,
+                )
+            )
+
+    def _statement_relations(self, sql: str, dialect: str | None = None) -> set[str]:
+        """Lowercased real relations one statement reads (tables minus its
+        own CTE names). The anchor for an extra statement's unqualified
+        filter columns when it produced no value edges of its own."""
+        import sqlglot
+        from sqlglot import exp
+
+        from ripple.engine.column_ref import temp_marked_name
+
+        try:
+            parsed = sqlglot.parse_one(sql, dialect=dialect or self.project.dialect)
+        except Exception:
+            return set()
+        ctes = {c.alias_or_name.lower() for c in parsed.find_all(exp.CTE)}
+        return {
+            temp_marked_name(t).lower()
+            for t in parsed.find_all(exp.Table)
+            if t.name and t.name.lower() not in ctes
+        }
+
+    def _alias_map(self, sql: str, dialect: str | None = None) -> dict[str, str]:
+        """Query-local alias -> relation name, resolving single-source CTEs
+        through to their base table. 'FROM stg_orders o JOIN pay p' where pay
+        is a CTE reading stg_payments yields {o: stg_orders, p: stg_payments}.
+        """
+        import sqlglot
+        from sqlglot import exp
+
+        try:
+            parsed = sqlglot.parse_one(sql, dialect=dialect or self.project.dialect)
+        except Exception:
+            return {}
+
+        from ripple.engine.column_ref import qualified_table_name
+        from ripple.engine.preprocess import restore_jinja_dots
+
+        def qualified(t: exp.Table) -> str:
+            # qualifiers kept for the same reason as scope.register_table: a
+            # filter/join/window column on a model named after the table it
+            # wraps must not resolve back into the model and vanish;
+            # placeholder qualifiers dropped for the same reason as
+            # column_ref.qualified_table_name
+            return qualified_table_name(t).lower()
+
+        cte_sources: dict[str, set[tuple[str, str]]] = {}
+        cte_names = set()
+        for cte in parsed.find_all(exp.CTE):
+            name = restore_jinja_dots(cte.alias_or_name.lower())
+            cte_names.add(name)
+            cte_sources[name] = {
+                (restore_jinja_dots(t.name.lower()), qualified(t))
+                for t in cte.this.find_all(exp.Table)
+            }
+        aliases: dict[str, str] = {}
+        for table in parsed.find_all(exp.Table):
+            alias = restore_jinja_dots((table.alias_or_name or "").lower())
+            name = restore_jinja_dots(table.name.lower())
+            if not alias or alias == name:
+                full = qualified(table)
+                if full != name and name not in cte_names:
+                    aliases.setdefault(name, full)
+                continue
+            target = qualified(table)
+            # a CTE alias resolves through the CTE when it reads one real table
+            if name in cte_names:
+                real = {q for (bare, q) in cte_sources.get(name, set()) if bare not in cte_names}
+                if len(real) == 1:
+                    target = next(iter(real))
+                else:
+                    continue  # multi-source CTE: leave unresolved, warn path handles it
+            aliases[alias] = target
+        return aliases
+
+    def _resolve_name(
+        self, table: str | None, scope_parents: set[str], ref_path: str = ""
+    ) -> tuple[list[str], str]:
+        """Resolve a table name from SQL to project models.
+
+        Returns (candidates, quality) where quality is one of exact / scoped /
+        ambiguous / suffix / unknown. Ambiguity returns ALL candidates; the
+        caller emits an edge per candidate at review_required rather than
+        silently binding one.
+        """
+        if not table:
+            return [], "unknown"
+        cleaned = table.replace('"', "").replace("`", "").lower()
+        scope = {
+            resolved[0] for p in scope_parents if (resolved := self._candidates.get(p.lower()))
+        }
+        candidates = self._candidates.get(cleaned)
+        if not candidates and "{" in cleaned:
+            # an ingest names the relation without its deploy-time qualifier;
+            # a templated NAME comes back unchanged and stays unresolved
+            stripped = _strip_placeholders(cleaned)
+            if stripped and "{" not in stripped:
+                if self._models_by_name is None:
+                    self._models_by_name = {
+                        m.name: m for m in [*self.project.models, *self.project.sources]
+                    }
+                # only a declared or ingested table answers to the bare
+                # spelling; a model with SQL of the same name is a different
+                # relation ({{params.dataset_name_raw}}.blocks is not the
+                # derived blocks model, round 11)
+                candidates = [
+                    c
+                    for c in self._candidates.get(stripped, [])
+                    if not (
+                        self._models_by_name.get(c) or Model(name="", sql="", path="")
+                    ).sql.strip()
+                ] or None
+        if candidates:
+            if len(candidates) == 1:
+                return [candidates[0]], "exact"
+            # locality before the scope shortcut: sql-dir declared parents are
+            # the bare names themselves, so scope would collapse to the first
+            # candidate and bind another dump's table (no-op outside sql-dir)
+            local = self._prefer_local(candidates, ref_path)
+            if len(local) == 1:
+                return local, "scoped"
+            in_scope = [c for c in local if c in scope]
+            if len(in_scope) == 1:
+                return in_scope, "scoped"
+            return (in_scope or local), "ambiguous"
+        last = cleaned.split(".")[-1]
+        if last != cleaned:
+            candidates = self._candidates.get(last)
+            if candidates:
+                candidates = [c for c in candidates if self._may_fold_qualified_read(c, cleaned)]
+            if candidates:
+                local = self._prefer_local(candidates, ref_path)
+                if len(local) == 1:
+                    return local, "scoped"
+                in_scope = [c for c in local if c in scope]
+                if len(in_scope) == 1:
+                    return in_scope, "scoped"
+                return (in_scope or local), "suffix"
+        return [], "unknown"
+
+    def _may_fold_qualified_read(self, name: str, read: str) -> bool:
+        """In plain SQL the file is the spelling authority: a relation created
+        bare never owns a schema-qualified read, and qualified spellings must
+        agree (round-5 refuse-to-fold, cycle-6 agreement rule). dbt schema
+        qualifiers are deploy artifacts, so dbt-evidence models keep folding.
+
+        A dotted filename stem counts as an agreeing qualified spelling: the
+        author named eicu_crd.patient.sql with the qualifier, so a read of
+        eicu_crd.patient folds to its relation deliberately (cycle-11 review,
+        F2: pinned as the intended design, not a bypass)."""
+        if self._models_by_name is None:
+            self._models_by_name = {
+                m.name: m for m in [*self.project.models, *self.project.sources]
+            }
+        model = self._models_by_name.get(name)
+        if model is None or model.evidence != "plain_sql":
+            return True
+        spellings = {
+            s.lower() for s in (model.name, *model.aliases, *model.stem_aliases) if "." in s
+        }
+        read_suffixes = _name_suffixes(read)
+        return any(s in read_suffixes or read in _name_suffixes(s) for s in spellings)
+
+    def _reads_as_written(self, model: Model) -> frozenset[str] | None:
+        """Lowercased as-written relation spellings in a model's SQL, or None
+        when nothing parsed (no evidence, so no refusal downstream)."""
+        if self._reads_cache is None:
+            self._reads_cache = {}
+        cached = self._reads_cache.get(model.uid, "unset")
+        if cached != "unset":
+            return cached
+        import sqlglot
+        from sqlglot import exp
+
+        from ripple.engine.column_ref import qualified_table_name
+
+        reads: set[str] = set()
+        parsed_any = False
+        for sql in (model.sql, *model.extra_sqls):
+            if not sql.strip():
+                continue
+            try:
+                parsed = sqlglot.parse_one(sql, read=model.dialect or self.project.dialect)
+            except Exception:
+                continue
+            parsed_any = True
+            for t in parsed.find_all(exp.Table):
+                if t.name:
+                    reads.add((qualified_table_name(t) or t.name).lower())
+        result = frozenset(reads) if parsed_any else None
+        self._reads_cache[model.uid] = result
+        return result
+
+    def _parent_binds(self, model: Model, parent: str, resolved: str) -> bool:
+        """The spelling-authority rule applied to a DECLARED parent link.
+
+        Declared parents are recorded bare, so the sites that resolve them
+        directly (parent schemas, fallback edges, unresolved reporting) were
+        bypassing _may_fold_qualified_read: a SELECT * FROM eicu_crd.patient
+        inherited the bare-created patient's columns and fallback edges
+        reconnected it (cycle-11 review, F3/F4). The read spellings in the
+        model's own SQL are the evidence; the parent binds only when some
+        read of it may fold to the resolved relation."""
+        if self._models_by_name is None:
+            self._models_by_name = {
+                m.name: m for m in [*self.project.models, *self.project.sources]
+            }
+        target = self._models_by_name.get(resolved)
+        if target is None or target.evidence != "plain_sql":
+            return True
+        reads = self._reads_as_written(model)
+        if reads is None:
+            return True
+        names = {s.lower() for s in (target.name, *target.aliases, *target.stem_aliases)}
+        bare = parent.lower().split(".")[-1]
+        relevant = [r for r in reads if r == parent.lower() or r.split(".")[-1] == bare]
+        if not relevant:
+            return True
+        return any(r in names or self._may_fold_qualified_read(resolved, r) for r in relevant)
+
+    def _refused_read_of(self, model: Model, parent: str) -> str | None:
+        """The as-written qualified spelling behind a refused parent link, so
+        the external is reported as the SQL cites it, not as the bare name."""
+        reads = self._reads_as_written(model) or frozenset()
+        bare = parent.lower().split(".")[-1]
+        dotted = sorted(r for r in reads if "." in r and r.split(".")[-1] == bare)
+        return dotted[0] if dotted else None
+
+    def _prefer_local(self, candidates: list[str], ref_path: str) -> list[str]:
+        """Same file first, then same subdirectory: in a sql dir one dump is
+        one database, so a reference never silently binds another dump's file."""
+        if len(candidates) < 2 or not ref_path or self.project.mode != "sql-dir":
+            return candidates
+        if self._models_by_name is None:
+            self._models_by_name = {
+                m.name: m for m in [*self.project.models, *self.project.sources]
+            }
+
+        def path_of(name: str) -> str:
+            model = self._models_by_name.get(name)
+            return model.path if model else ""
+
+        same_file = [c for c in candidates if path_of(c) == ref_path]
+        if same_file:
+            return same_file
+        top = ref_path.split("/", 1)[0]
+        same_dir = [c for c in candidates if path_of(c) and path_of(c).split("/", 1)[0] == top]
+        return same_dir or candidates
+
+    def _fallback_edges(self) -> None:
+        """A model that yielded nothing still sits between its declared parents
+        and everything that reads it. Wildcard edges keep that path visible;
+        review_required says exactly how much to trust it."""
+        for model in self.project.models:
+            report = self.reports.get(model.name)
+            if report is None or report.status not in ("failed", "star_only"):
+                continue
+            connected = False
+            for parent in model.declared_parents:
+                resolved = self._candidates.get(parent.lower())
+                if not resolved:
+                    continue
+                # a bare declared parent that resolves to the model itself is
+                # the self-name-collision shape; a wildcard self-edge would
+                # assert the model feeds itself. A refused spelling must not
+                # reconnect here either: the analysis path already kept the
+                # as-written external edge (cycle-11, F4)
+                non_self = [
+                    c for c in resolved if c != model.name and self._parent_binds(model, parent, c)
+                ]
+                if not non_self:
+                    continue
+                self.edges.append(
+                    Edge(
+                        src_model=non_self[0],
+                        src_column=WILDCARD,
+                        dst_model=model.name,
+                        dst_column=WILDCARD,
+                        confidence=0.3,
+                        trust="review_required",
+                        kind="value",
+                        reason="model could not be analyzed; linked via declared dependency",
+                    )
+                )
+                connected = True
+            if connected and report.status == "failed":
+                report.status = "fallback"
+
+    def _dedupe(self) -> None:
+        best: dict[tuple, Edge] = {}
+        for edge in self.edges:
+            existing = best.get(edge.key())
+            if existing is None or edge.confidence > existing.confidence:
+                best[edge.key()] = edge
+        self.edges = list(best.values())
+
+    def _index(self) -> None:
+        self._down = defaultdict(list)
+        self._down_by_model = defaultdict(list)
+        self._up = defaultdict(list)
+        for edge in self.edges:
+            self._down[(edge.src_model, edge.src_column)].append(edge)
+            self._down_by_model[edge.src_model].append(edge)
+            self._up[(edge.dst_model, edge.dst_column)].append(edge)
+
+    # ---- queries ----
+
+    def _model_owns_column(self, name: str, column: str) -> bool:
+        if self._down.get((name, column)) or self._up.get((name, column)):
+            return True
+        report = self.reports.get(name)
+        if report and any(c.lower() == column for c in report.columns):
+            return True
+        # sources count: a declared source schema is ownership evidence for
+        # multi-relation star resolution (cycle-12, F9)
+        for m in [*self.project.models, *self.project.sources]:
+            if m.name == name:
+                return any(c.lower() == column for c in m.declared_columns)
+        return False
+
+    def _pick_stem_claimant(self, canonical: list[str], column: str) -> str | None:
+        """The one stem claimant the asked column picks, or None to refuse.
+
+        A claimant whose outputs are unenumerated (a star passthrough) may
+        well own the column too; picking the visible owner past it would
+        answer with false confidence (the cycle-6 review, the
+        elimination rule's wildcard guard applied to the pick). The
+        benchmark harness resolves case models through this same method."""
+        wanted = column.lower()
+        owners = [c for c in canonical if self._model_owns_column(c, wanted)]
+        veiled = [
+            c
+            for c in canonical
+            if c not in owners
+            and (report := self.reports.get(c)) is not None
+            and WILDCARD in report.columns
+        ]
+        if len(owners) == 1 and not veiled:
+            return owners[0]
+        return None
+
+    def _also_matches(self, asked: str, chosen: str) -> list[str]:
+        """The other models a spelling names when it was settled by being one
+        model's own name; the answer says so instead of picking silently."""
+        others = [c for c in self._candidates.get(asked.lower(), []) if c != chosen]
+        return sorted(self._askable_name(c) for c in others)
+
+    def _askable_name(self, canonical: str) -> str:
+        """The spelling a person would type for a model: its shortest dotted
+        alias (telemetry_derived.events_v1), never the path-mangled canonical
+        name a collision assigned (sql__moz-fx...__events_v1__view__events_v1)."""
+        if self._models_by_name is None:
+            self._models_by_name = {
+                m.name: m for m in [*self.project.models, *self.project.sources]
+            }
+        target = self._models_by_name.get(canonical)
+        dotted = sorted((a for a in (target.aliases if target else ()) if "." in a), key=len)
+        return dotted[0] if dotted else canonical
+
+    def _external_targets(self) -> dict[str, str]:
+        """lowercased spelling -> as-written name of every table the graph
+        reads but does not define, so a question about one still answers."""
+        if getattr(self, "_externals", None) is None:
+            self._externals = {
+                e.src_model.lower(): e.src_model
+                for e in self.edges
+                if e.src_model not in self.reports
+            }
+        return self._externals
+
+    def _require_target(self, model: str, column: str) -> tuple[str, str]:
+        canonical = self._candidates.get(model.lower())
+        if not canonical:
+            # a dbt-disabled model is still askable: its own analysis exists
+            canonical = self._all_candidates.get(model.lower())
+        if not canonical:
+            external = self._external_targets().get(model.lower())
+            if external is not None:
+                canonical = [external]
+        if not canonical:
+            known = list(self.reports.keys())
+            close = difflib.get_close_matches(model, known, n=3)
+            raise UnknownTarget(f"no model named '{model}'", close)
+        if len(canonical) > 1:
+            # a spelling that IS one model's own name is that model, even
+            # when another model carries it as an alias (postgresDBSamples:
+            # base table Employee beside a path-qualified derived employee)
+            exact = [c for c in canonical if c.lower() == model.lower()]
+            if len(exact) == 1:
+                canonical = exact
+        if len(canonical) > 1:
+            # a file stem naming several relations is DELIBERATELY ambiguous
+            # and only until the column picks one (webtool_tables.invCount,
+            # holdout round 5). Any other shared spelling, like two files
+            # creating the same table, is a real collision: picking whichever
+            # owns the asked column would hand the user the wrong model's
+            # blast radius silently (the review of PR #28)
+            picked = (
+                self._pick_stem_claimant(canonical, column)
+                if model.lower() in self._stem_aliases
+                else None
+            )
+            if picked is None:
+                raise UnknownTarget(
+                    f"'{model}' names {len(canonical)} different models; ask by full name",
+                    sorted(self._askable_name(c) for c in canonical),
+                )
+            canonical = [picked]
+        name = canonical[0]
+        report = self.reports.get(name)
+        column = column.lower()
+        if report is None or (report.status != "ok" and not report.columns):
+            # outside the project, or defined without columns (CREATE TABLE
+            # ... LIKE in redshift-utils): the only columns Ripple knows are
+            # the ones its models read. "0 impacted, complete" for a column
+            # it never saw read as a clean bill of health (balboa walk)
+            seen = sorted({c for (m, c) in (self._down or {}) if m == name and c != WILDCARD})
+            if column not in seen:
+                raise UnknownTarget(
+                    f"'{name}' is outside this project; Ripple only knows the "
+                    f"columns its models read from it",
+                    seen,  # the full list: an agent copies it into ingest_schema, and
+                    # mattermost's telemetry event table is read on 200+ columns
+                )
+        if report and report.status == "ok" and column not in report.columns:
+            has_edges = bool(self._down.get((name, column)) or self._up.get((name, column)))
+            if not has_edges:
+                close = difflib.get_close_matches(column, report.columns, n=3)
+                raise UnknownTarget(f"'{name}' has no column '{column}'", close)
+        return name, column
+
+    def breaks(self, model: str, column: str, max_depth: int = 25) -> dict:
+        """Everything downstream of model.column.
+
+        Trust is path-aware: a hit reached only through an uncertain hop is
+        reported at that path's worst trust, not the last edge's. Row-level
+        impact (this column used in a downstream WHERE/JOIN) is reported per
+        model rather than fanned out, so counts stay column-true.
+        """
+        name, column = self._require_target(model, column)
+        also = self._also_matches(model, name)
+        # worst path trust each node has been expanded with; a node is
+        # re-expanded when a WORSE path reaches it, so downgrades propagate
+        # to everything downstream of a convergence point (fixed point,
+        # each node expands at most len(TRUST_ORDER) times)
+        expanded_at: dict[tuple[str, str], str] = {}
+        seen: dict[tuple[str, str], dict] = {}
+        row_impact: dict[str, dict] = {}
+        truncated = False
+        frontier: deque = deque([((name, column), 0, "verified")])
+        while frontier:
+            node, depth, path_trust = frontier.popleft()
+            previous = expanded_at.get(node)
+            if previous is not None and TRUST_ORDER.index(path_trust) >= TRUST_ORDER.index(
+                previous
+            ):
+                continue
+            if depth >= max_depth:
+                truncated = True
+                continue
+            expanded_at[node] = path_trust
+            node_model, node_column = node
+            outgoing = list(self._down.get(node, []))
+            if node_column == WILDCARD:
+                # a wildcard node means "some unknown column of this model":
+                # anything reading any of its columns might be affected
+                outgoing = self._down_by_model.get(node_model, [])
+            else:
+                outgoing += self._down.get((node_model, WILDCARD), [])
+            for edge in outgoing:
+                through_wildcard = WILDCARD in (edge.src_column, edge.dst_column, node_column)
+                trust = _worst_trust(
+                    path_trust, edge.trust, *(["review_required"] if through_wildcard else [])
+                )
+                if edge.kind in ("filter", "join", "window"):
+                    entry = row_impact.setdefault(
+                        edge.dst_model,
+                        {"model": edge.dst_model, "uses": [], "trust": trust},
+                    )
+                    entry["uses"].append(f"{edge.src_model}.{edge.src_column} ({edge.kind})")
+                    entry["trust"] = _worst_trust(entry["trust"], trust)
+                    continue
+                hit = {
+                    "model": edge.dst_model,
+                    "column": edge.dst_column,
+                    "via": f"{edge.src_model}.{edge.src_column}",
+                    "kind": edge.kind,
+                    "trust": trust,
+                    "edge_trust": edge.trust,
+                    "confidence": edge.confidence,
+                    "depth": depth + 1,
+                }
+                if edge.reason:
+                    hit["reason"] = edge.reason
+                key = (edge.dst_model, edge.dst_column)
+                previous = seen.get(key)
+                if previous is None:
+                    seen[key] = hit
+                else:
+                    # a second path to the same column never upgrades trust,
+                    # and an uncertain path is never hidden by a confident one
+                    previous["trust"] = _worst_trust(previous["trust"], trust)
+                if not edge.dst_column.startswith("("):
+                    frontier.append(((edge.dst_model, edge.dst_column), depth + 1, trust))
+        # stable: same-model hits keep the order the walk met them in (select order)
+        hits = sorted(
+            seen.values(),
+            key=lambda h: (h["depth"], TRUST_ORDER[::-1].index(h["edge_trust"]), h["model"]),
+        )
+        by_model: dict[str, list[dict]] = defaultdict(list)
+        for hit in hits:
+            # the numeric score is a branch constant, not a probability;
+            # public output carries the categorical label and the reason
+            hit.pop("confidence", None)
+            by_model[hit["model"]].append(hit)
+        return {
+            "source": {"model": name, "column": column},
+            "impacted_columns": len(hits),
+            "impacted_models": len(by_model),
+            "review_required": sum(1 for h in hits if h["trust"] == "review_required"),
+            "by_model": dict(by_model),
+            "row_level_impact": sorted(row_impact.values(), key=lambda r: r["model"]),
+            "row_impacted_models": len(row_impact),
+            "complete": not truncated,
+            **({"truncated_at_depth": max_depth} if truncated else {}),
+            **({"also_matches": also} if also else {}),
+        }
+
+    def breaks_all(self, model: str, max_depth: int = 25) -> dict:
+        """Blast radius of the whole model changing at once (a predicate or
+        join change alters every row, so every output column is a source)."""
+        canonical = self._candidates.get(model.lower())
+        if not canonical:
+            raise UnknownTarget(
+                f"no model named '{model}'",
+                difflib.get_close_matches(model, list(self.reports), n=3),
+            )
+        name = canonical[0]
+        report = self.reports.get(name)
+        columns = [c for c in (report.columns if report else []) if c != WILDCARD]
+        merged: dict = {"impacted": {}, "row": {}}
+        complete = True
+        for column in columns or [WILDCARD]:
+            try:
+                result = self.breaks(name, column, max_depth=max_depth)
+            except UnknownTarget:
+                continue
+            complete = complete and result.get("complete", True)
+            for hits in result["by_model"].values():
+                for hit in hits:
+                    key = (hit["model"], hit["column"])
+                    existing = merged["impacted"].get(key)
+                    if existing is None:
+                        merged["impacted"][key] = hit
+                    else:
+                        existing["trust"] = _worst_trust(existing["trust"], hit["trust"])
+            for row in result["row_level_impact"]:
+                merged["row"][row["model"]] = row
+        hits = list(merged["impacted"].values())
+        by_model: dict[str, list[dict]] = defaultdict(list)
+        for hit in hits:
+            by_model[hit["model"]].append(hit)
+        return {
+            "source": {"model": name, "column": "(all columns)"},
+            "impacted_columns": len(hits),
+            "impacted_models": len(by_model),
+            "review_required": sum(1 for h in hits if h["trust"] == "review_required"),
+            "by_model": dict(by_model),
+            "row_level_impact": sorted(merged["row"].values(), key=lambda r: r["model"]),
+            "row_impacted_models": len(merged["row"]),
+            "complete": complete,
+        }
+
+    def trace(self, model: str, column: str, max_depth: int = 25) -> dict:
+        """Where model.column comes from, hop by hop. Trust accumulates along
+        the path from the target, same contract as breaks()."""
+        name, column = self._require_target(model, column)
+        expanded_at: dict[tuple[str, str], str] = {}
+        hops: dict[tuple, dict] = {}
+        truncated = False
+        frontier: deque = deque([((name, column), 0, "verified")])
+        while frontier:
+            node, depth, path_trust = frontier.popleft()
+            previous = expanded_at.get(node)
+            if previous is not None and TRUST_ORDER.index(path_trust) >= TRUST_ORDER.index(
+                previous
+            ):
+                continue
+            if depth >= max_depth:
+                truncated = True
+                continue
+            expanded_at[node] = path_trust
+            node_model, node_column = node
+            incoming = list(self._up.get(node, []))
+            if node_column != WILDCARD:
+                incoming += self._up.get((node_model, WILDCARD), [])
+            for edge in incoming:
+                if edge.kind != "value":
+                    continue
+                trust = _worst_trust(path_trust, edge.trust)
+                key = (edge.src_model, edge.src_column, edge.dst_model, edge.dst_column)
+                existing = hops.get(key)
+                if existing is None:
+                    hop = {
+                        "model": edge.src_model,
+                        "column": edge.src_column,
+                        "feeds": f"{edge.dst_model}.{edge.dst_column}",
+                        "trust": trust,
+                        "edge_trust": edge.trust,
+                        "confidence": edge.confidence,
+                        "depth": depth + 1,
+                    }
+                    if edge.reason:
+                        hop["reason"] = edge.reason
+                    hops[key] = hop
+                else:
+                    existing["trust"] = _worst_trust(existing["trust"], trust)
+                frontier.append(((edge.src_model, edge.src_column), depth + 1, trust))
+        ordered = sorted(hops.values(), key=lambda h: (h["depth"], h["model"], h["column"]))
+        for hop in ordered:
+            hop.pop("confidence", None)
+        return {
+            "target": {"model": name, "column": column},
+            "upstream": ordered,
+            "complete": not truncated,
+            **({"truncated_at_depth": max_depth} if truncated else {}),
+        }
+
+    def resolve_star_column(self, model: str, column: str) -> list[tuple[str, str]]:
+        """Resolve a named column through the model's star projection:
+        [(source_relation, column)] when the star provably carries it,
+        [] when it is excepted or ownership is unknowable."""
+        from ripple.star_resolution import resolve_star_column
+
+        return resolve_star_column(self, model, column)
+
+    # ---- export ----
+
+    def stats(self) -> dict:
+        by_status = defaultdict(list)
+        for report in self.reports.values():
+            by_status[report.status].append(report.name)
+        failed = {
+            name: self.reports[name].error
+            for name in [
+                *by_status.get("failed", []),
+                *by_status.get("fallback", []),
+                *by_status.get("timed_out", []),
+            ]
+        }
+        return {
+            "mode": self.project.mode,
+            "dialect": self.project.dialect,
+            "models": len(self.project.models),
+            "sources": len(self.project.sources),
+            "ok": len(by_status.get("ok", [])),
+            "star_only": len(by_status.get("star_only", [])),
+            "fallback": len(by_status.get("fallback", [])),
+            "timed_out": len(by_status.get("timed_out", [])),
+            "failed": len(by_status.get("failed", [])) + len(by_status.get("no_sql", [])),
+            "failure_reasons": dict(list(failed.items())[:20]),
+            "edges": len(self.edges),
+            "review_required_edges": sum(1 for e in self.edges if e.trust == "review_required"),
+            "verified_edges": sum(1 for e in self.edges if e.trust == "verified"),
+        }
+
+    def unresolved_tables(self) -> list[dict]:
+        """External relations referenced by models but with no known columns:
+        names that resolve to nothing, plus sources and base tables whose
+        columns nobody has declared. Sorted by how much coverage they block."""
+        if self._models_by_name is None:
+            self._models_by_name = {
+                m.name: m for m in [*self.project.models, *self.project.sources]
+            }
+        import re
+
+        cte_re = re.compile(r"\b([A-Za-z_][A-Za-z0-9_]*)\s+as\s*\(", re.I)
+        entries: dict[str, dict] = {}
+        for model in self.project.models:
+            report = self.reports.get(model.name)
+            status = report.status if report else "failed"
+            own_ctes = {m.lower() for m in cte_re.findall(model.sql)} if model.sql else set()
+            for parent in model.declared_parents:
+                if "{" in parent or any(c.isspace() for c in parent):
+                    continue  # jinja leftover, not an ingestable table name
+                if parent.lower() in own_ctes:
+                    continue  # a CTE of this model's own script, not a table
+                resolved = self._candidates.get(parent.lower()) or self._all_candidates.get(
+                    parent.lower()
+                )
+                as_written = None
+                if resolved and not self._parent_binds(model, parent, resolved[0]):
+                    # refused spelling: the read names an external relation,
+                    # reported as the SQL cites it (cycle-11, F3)
+                    name = self._refused_read_of(model, parent) or parent.lower()
+                    if "{" in name:
+                        stripped = _strip_placeholders(name)
+                        if "{" not in stripped:
+                            as_written, name = name, stripped or parent.lower()
+                    known = self._candidates.get(name.lower(), [])
+                    if len(known) == 1 and (
+                        (self.reports.get(known[0]) or ModelReport(name="")).status == "ok"
+                        or (
+                            self._models_by_name.get(known[0]) or Model(name="", sql="", path="")
+                        ).declared_columns
+                    ):
+                        continue  # the spelling the SQL wrote was ingested; nothing to do
+                    qualified = name if "." in name else None
+                elif resolved:
+                    target = self._models_by_name.get(resolved[0])
+                    target_report = self.reports.get(resolved[0])
+                    if target_report is not None and target_report.status == "ok":
+                        continue
+                    if target is None or target.sql.strip() or target.declared_columns:
+                        continue  # a real model that failed is not a schema gap
+                    name = resolved[0]
+                    qualified = max((a for a in target.aliases if "." in a), key=len, default=None)
+                else:
+                    name = parent.lower()
+                    qualified = name if "." in name else None
+                    as_written = None
+                    if qualified is None:
+                        # the declared parent is bare; the SQL may have
+                        # written it qualified, and that spelling is the one
+                        # an ingest must use (balboa's slow_query reads
+                        # snowflake_sample_data.tpch_sf1.region)
+                        written = [
+                            _strip_placeholders(r)
+                            for r in (self._reads_as_written(model) or ())
+                            if r.split(".")[-1] == name
+                        ]
+                        written = [w for w in written if "." in w]
+                        qualified = min(written, key=len) if written else None
+                        as_written = next(
+                            (
+                                r
+                                for r in (self._reads_as_written(model) or ())
+                                if "{" in r and r.split(".")[-1] == name
+                            ),
+                            None,
+                        )
+                entry = entries.setdefault(
+                    name,
+                    {
+                        "table": name,
+                        **({"qualified_name": qualified} if qualified else {}),
+                        **({"as_written": as_written} if as_written else {}),
+                        "referencing_models": 0,
+                        "blocked_models": 0,
+                        "statuses": {},
+                    },
+                )
+                entry["referencing_models"] += 1
+                if status in ("star_only", "failed", "fallback", "no_sql"):
+                    entry["blocked_models"] += 1
+                entry["statuses"][status] = entry["statuses"].get(status, 0) + 1
+        # tables only the engine saw: a raw table read by name inside a dbt
+        # model is no declared parent, yet its edges say "not found"
+        # (balboa's _airbyte_raw_zip_coordinates)
+        seen_pairs: set[tuple[str, str]] = set()
+        for edge in self.edges:
+            if edge.src_model in self.reports or "not found" not in edge.reason:
+                continue  # disabled-only names carry their own reason and are skipped
+            written = edge.src_model.lower()
+            key = _strip_placeholders(written) if "{" in written else written
+            if not key or "{" in key or any(ch.isspace() for ch in key):
+                continue  # a templated name or jinja remnant: cited as written, not ingestable
+            if key in entries or (key, edge.dst_model) in seen_pairs:
+                continue
+            seen_pairs.add((key, edge.dst_model))
+            entry = entries.setdefault(
+                key,
+                {
+                    "table": key,
+                    **({"qualified_name": key} if "." in key else {}),
+                    **({"as_written": written} if written != key else {}),
+                    "referencing_models": 0,
+                    "blocked_models": 0,
+                    "statuses": {},
+                },
+            )
+            entry["referencing_models"] += 1
+            status = self.reports[edge.dst_model].status if edge.dst_model in self.reports else "ok"
+            entry["statuses"][status] = entry["statuses"].get(status, 0) + 1
+        return sorted(
+            entries.values(),
+            key=lambda e: (-e["blocked_models"], -e["referencing_models"], e["table"]),
+        )
+
+    def suggest_target(self) -> dict | None:
+        """The column with the widest blast radius, for a copy-pasteable
+        first command. Direct fanout shortlists; transitive reach decides."""
+        shortlist = []
+        for (src_model, src_column), edges in (self._down or {}).items():
+            if src_column == WILDCARD or src_column.startswith("("):
+                continue
+            report = self.reports.get(src_model)
+            # only models this project owns: breaks() cannot target an external
+            # table, and on filecoin-data-portal the 197 highest-fanout columns
+            # were external, so the top-8 probe never reached a real model and
+            # the suggestion came back empty
+            if report is None or report.status != "ok":
+                continue
+            fanout = sum(1 for e in edges if e.kind == "value")
+            if fanout:
+                shortlist.append((fanout, src_model, src_column))
+        shortlist.sort(reverse=True)
+        # a path-qualified collision name (sql__2024__cookies__cookies) is
+        # not something a person types; prefer a spelling they can, and fall
+        # back to the mangled names only when nothing else has reach
+        # (HTTP Archive's almanac)
+        askable = [t for t in shortlist if self._askable_name(t[1]) == t[1] and "__" not in t[1]]
+        shortlist = askable or shortlist
+        best = None
+        for _, model, column in shortlist[:8]:
+            try:
+                reach = self.breaks(model, column)["impacted_columns"]
+            except LookupError:
+                continue
+            if best is None or reach > best["fanout"]:
+                best = {"model": model, "column": column, "fanout": reach}
+        return best
+
+    def to_dict(self) -> dict:
+        nodes = []
+        for m in self.project.sources:
+            nodes.append(
+                {"name": m.name, "id": m.uid, "type": "source", "columns": m.declared_columns}
+            )
+        for m in self.project.models:
+            report = self.reports.get(m.name)
+            nodes.append(
+                {
+                    "name": m.name,
+                    "id": m.uid,
+                    "type": "model",
+                    "path": m.path,
+                    "status": report.status if report else "failed",
+                    "parsed": bool(report and report.parsed),
+                    "columns": report.columns if report else [],
+                    **({"warnings": report.warnings[:10]} if report and report.warnings else {}),
+                }
+            )
+        return {
+            "stats": self.stats(),
+            "nodes": nodes,
+            "edges": [
+                {
+                    "src": f"{e.src_model}.{e.src_column}",
+                    "dst": f"{e.dst_model}.{e.dst_column}",
+                    "kind": e.kind,
+                    "trust": e.trust,
+                    **({"reason": e.reason} if e.reason else {}),
+                }
+                for e in self.edges
+            ],
+        }