coltrace 0.1.0.dev4__py3-none-any.whl

coltrace/analysis.py

@@ -0,0 +1,2206 @@
+"""Conservative, ordered interpretation of a deliberately small Pandas subset.
+
+Only ASTs and abstract values are interpreted. Project code and data sources are
+never imported, evaluated, or opened by this module.
+"""
+
+from __future__ import annotations
+
+import ast
+import hashlib
+import io
+import tokenize
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+from typing import Literal
+
+from .callbacks import summarize_callback
+from .lineage_models import (
+    Column,
+    Completeness,
+    Confidence,
+    Consumption,
+    Edge,
+    Frame,
+    HistoryEvent,
+    LineageReport,
+    Operation,
+)
+from .models import Diagnostic, Location
+from .scanner import ScanConfig, scan_project
+
+
+def _identifier(prefix: str, *parts: object) -> str:
+    digest = hashlib.sha256(repr(parts).encode("utf-8")).hexdigest()[:24]
+    return f"{prefix}:{digest}"
+
+
+def _confidence(*values: Confidence) -> Confidence:
+    if "unresolved" in values:
+        return "unresolved"
+    return "inferred" if "inferred" in values else "confirmed"
+
+
+def _completeness(*values: Completeness) -> Completeness:
+    if "unresolved" in values:
+        return "partial" if "complete" in values or "partial" in values else "unresolved"
+    return "partial" if "partial" in values else "complete"
+
+
+@dataclass
+class _Value:
+    kind: Literal[
+        "unknown",
+        "literal",
+        "series",
+        "frame",
+        "symbol",
+        "function",
+        "rows",
+        "index",
+        "mask",
+        "accessor",
+    ] = "unknown"
+    frame: _State | None = None
+    dependencies: tuple[str, ...] = ()
+    symbol: str = ""
+    function: _Function | None = None
+    evidence: Confidence = "confirmed"
+    completeness: Completeness = "unresolved"
+    escaped: tuple[str, ...] = ()
+    epochs: tuple[tuple[str, int], ...] = ()
+    components: tuple[_Value, ...] | None = None
+    index_key: str | None = None
+    producer: str = "derive"
+    expression: str = ""
+    history: tuple[str, ...] = ()
+
+
+@dataclass
+class _Module:
+    name: str
+    path: str
+    source: str
+    tree: ast.Module
+    env: dict[str, _Value] = field(default_factory=dict)
+    status: Literal["new", "visiting", "done"] = "new"
+
+
+@dataclass
+class _Function:
+    module: _Module
+    node: ast.FunctionDef
+    defaults: dict[str, _Value]
+    frame_parameters: set[str]
+    called: bool = False
+
+
+@dataclass
+class _Context:
+    module: _Module
+    scope: str
+    key: str
+    env: dict[str, _Value]
+    stack: tuple[tuple[str, str], ...] = ()
+    parent_history: tuple[str, ...] = ()
+
+
+@dataclass
+class _Snapshot:
+    state: _State
+    current: dict[str, str]
+    fallback: _Copy | None
+    schema: set[str] | None
+    epoch: int
+    tainted: bool
+    versions: dict[str, int]
+    removed: set[str]
+    history: tuple[str, ...]
+
+
+@dataclass
+class _Copy:
+    source: _Snapshot
+    names: dict[str, str]
+    context: _Context
+    node: ast.AST
+    evidence: Confidence
+
+
+@dataclass
+class _State:
+    record: Frame
+    current: dict[str, str] = field(default_factory=dict)
+    versions: dict[str, int] = field(default_factory=dict)
+    fallback: _Copy | None = None
+    schema: set[str] | None = None
+    epoch: int = 0
+    tainted: bool = False
+    removed: set[str] = field(default_factory=set)
+    index_key: str = ""
+    positional: tuple[_Value, ...] | None = None
+    history: tuple[str, ...] = ()
+
+
+class _Analyzer:
+    MAX_CALLS = 1000
+    MAX_DEPTH = 32
+
+    def __init__(self, modules: dict[str, _Module], ambiguous: set[str]) -> None:
+        self.modules = modules
+        self.ambiguous = ambiguous
+        self.frames: list[Frame] = []
+        self.states: dict[str, _State] = {}
+        self.columns: dict[str, Column] = {}
+        self.operations: list[Operation] = []
+        self.edges: list[Edge] = []
+        self.consumptions: list[Consumption] = []
+        self.diagnostics: list[Diagnostic] = []
+        self.functions: list[_Function] = []
+        self.call_count = 0
+        self.api_mutations: set[str] = set()
+        self.history: list[HistoryEvent] = []
+        self.column_history: dict[str, str] = {}
+        self.frame_boundaries: dict[str, str] = {}
+
+    @staticmethod
+    def _code(context: _Context, node: ast.AST) -> str:
+        return ast.get_source_segment(context.module.source, node) or ast.unparse(node)
+
+    def _event(
+        self,
+        context: _Context,
+        node: ast.AST,
+        kind: str,
+        label: str,
+        *,
+        frames: tuple[str, ...] = (),
+        inputs: tuple[str, ...] = (),
+        outputs: tuple[str, ...] = (),
+        parents: tuple[str, ...] = (),
+        expression: str | None = None,
+        evidence: Confidence = "confirmed",
+        completeness: Completeness = "complete",
+    ) -> str:
+        sequence = len(self.history)
+        evidence = _confidence(
+            evidence, "inferred" if context.key.startswith("template:") else "confirmed"
+        )
+        parents = tuple(sorted(set(parents)))
+        event = HistoryEvent(
+            _identifier("history", context.key, self._location(context, node), kind, sequence),
+            sequence,
+            kind,
+            label,
+            self._location(context, node),
+            context.module.name,
+            context.scope,
+            context.key,
+            tuple(sorted(set(frames))),
+            tuple(sorted(set(inputs))),
+            tuple(sorted(set(outputs))),
+            self._code(context, node) if expression is None else expression,
+            evidence,
+            completeness,
+            parents,
+        )
+        self.history.append(event)
+        return event.id
+
+    def _parents(self, value: _Value) -> tuple[str, ...]:
+        return tuple(
+            dict.fromkeys(
+                value.history
+                + tuple(
+                    self.column_history[item]
+                    for item in value.dependencies
+                    if item in self.column_history
+                )
+            )
+        )
+
+    @staticmethod
+    def _location(context: _Context, node: ast.AST) -> Location:
+        lines = context.module.source.split("\n")
+
+        def offset(line: int, byte: int) -> int:
+            if not 1 <= line <= len(lines):
+                return byte
+            return len(lines[line - 1].encode("utf-8")[:byte].decode("utf-8", errors="ignore"))
+
+        line = getattr(node, "lineno", 1)
+        end_line = getattr(node, "end_lineno", None)
+        end_col = getattr(node, "end_col_offset", None)
+        return Location(
+            context.module.path,
+            line,
+            offset(line, getattr(node, "col_offset", 0)),
+            end_line,
+            offset(end_line, end_col) if end_line is not None and end_col is not None else None,
+        )
+
+    def _diagnose(self, context: _Context, node: ast.AST, code: str, message: str) -> None:
+        self.diagnostics.append(
+            Diagnostic(
+                code,
+                "warning",
+                message,
+                self._location(context, node),
+                context.scope,
+                "Inspect this boundary; lineage beyond it may be incomplete.",
+            )
+        )
+
+    def _new_frame(
+        self,
+        context: _Context,
+        node: ast.AST,
+        origin: str,
+        evidence: Confidence = "confirmed",
+    ) -> _State:
+        location = self._location(context, node)
+        if context.key.startswith("template:"):
+            evidence = _confidence(evidence, "inferred")
+        record = Frame(
+            _identifier("df", location, context.key, origin),
+            origin,
+            location,
+            context.module.name,
+            context.scope,
+            context.key,
+            evidence,
+        )
+        state = _State(record, index_key=record.id)
+        self.frames.append(record)
+        self.states[record.id] = state
+        if origin.startswith("parameter:"):
+            state.history = (
+                self._event(
+                    context,
+                    node,
+                    "parameter",
+                    f"DataFrame parameter {origin.split(':', 1)[1]}",
+                    frames=(record.id,),
+                    evidence=evidence,
+                    completeness="partial",
+                ),
+            )
+        return state
+
+    @staticmethod
+    def _frame_value(state: _State) -> _Value:
+        return _Value(
+            "frame",
+            frame=state,
+            evidence=state.record.evidence,
+            completeness="complete",
+            history=state.history,
+        )
+
+    def _operation(
+        self,
+        context: _Context,
+        node: ast.AST,
+        kind: str,
+        suffix: str,
+        evidence: Confidence,
+        completeness: Completeness,
+    ) -> Operation:
+        location = self._location(context, node)
+        operation = Operation(
+            _identifier("op", location, context.key, kind, suffix),
+            kind,
+            location,
+            context.module.name,
+            context.scope,
+            context.key,
+            evidence,
+            completeness,
+        )
+        self.operations.append(operation)
+        return operation
+
+    def _write(
+        self,
+        state: _State,
+        name: str,
+        value: _Value,
+        context: _Context,
+        node: ast.AST,
+        kind: str = "derive",
+    ) -> str:
+        value = self._refresh(value)
+        previous = state.current.get(name)
+        state.positional = None
+        if kind == "derive":
+            kind = value.producer
+        # Reserve the epoch's external version even when that column has not
+        # been observed yet: an older lazy copy can materialize it later.
+        version = state.versions.get(name, state.epoch) + 1
+        state.versions[name] = version
+        evidence = _confidence(state.record.evidence, value.evidence)
+        if value.kind not in {"literal", "series"}:
+            evidence = "unresolved"
+            kind = "opaque"
+            self._diagnose(
+                context,
+                node,
+                "CT_UNRESOLVED_VALUE",
+                "The assigned value has unresolved provenance; no hidden dependencies are assumed.",
+            )
+        column = Column(
+            _identifier("col", state.record.id, name, version),
+            state.record.id,
+            name,
+            version,
+            self._location(context, node),
+            context.module.name,
+            context.scope,
+            context.key,
+            "write" if kind != "source" else "source",
+            evidence,
+            value.completeness,
+        )
+        self.columns[column.id] = column
+        state.current[name] = column.id
+        state.removed.discard(name)
+        if state.schema is not None:
+            state.schema.add(name)
+        operation = self._operation(context, node, kind, column.id, evidence, value.completeness)
+        for dependency in dict.fromkeys(value.dependencies):
+            self.edges.append(Edge(dependency, operation.id, "read", evidence))
+        self.edges.append(Edge(operation.id, column.id, "write", evidence))
+        event_kind = "boundary" if kind == "opaque" else kind
+        label = f"{name} = {value.expression or kind}"
+        if previous is not None and kind not in {"rename", "source"}:
+            event_kind = "overwrite"
+            label = f"Overwrite {name}: {value.expression or kind}"
+        self.column_history[column.id] = self._event(
+            context,
+            node,
+            event_kind,
+            label,
+            frames=(state.record.id,),
+            inputs=value.dependencies,
+            outputs=(column.id,),
+            parents=tuple(dict.fromkeys(state.history + self._parents(value))),
+            expression=f"{self._code(context, node)} = {value.expression}"
+            if value.expression
+            else None,
+            evidence=evidence,
+            completeness=value.completeness,
+        )
+        return column.id
+
+    def _external(self, snapshot: _Snapshot, name: str, context: _Context, node: ast.AST) -> str:
+        state = snapshot.state
+        identifier = _identifier("external", state.record.id, name, snapshot.epoch)
+        if identifier not in self.columns:
+            evidence = "unresolved" if snapshot.tainted else state.record.evidence
+            version = snapshot.versions.get(name, snapshot.epoch) if snapshot.tainted else 0
+            state.versions[name] = max(state.versions.get(name, -1), version)
+            self.columns[identifier] = Column(
+                identifier,
+                state.record.id,
+                name,
+                version,
+                self._location(context, node),
+                context.module.name,
+                context.scope,
+                context.key,
+                "opaque" if snapshot.tainted else "external_unknown",
+                evidence,
+                "unresolved" if snapshot.tainted else "partial",
+            )
+            self.column_history[identifier] = self._event(
+                context,
+                node,
+                "boundary" if snapshot.tainted else "external",
+                (
+                    f"Provenance lost before observing {name}"
+                    if snapshot.tainted
+                    else f"Observe input column {name}; definition in external data is unknown"
+                ),
+                frames=(state.record.id,),
+                outputs=(identifier,),
+                parents=snapshot.history,
+                evidence=evidence,
+                completeness="unresolved" if snapshot.tainted else "partial",
+            )
+        snapshot.current[name] = identifier
+        return identifier
+
+    @staticmethod
+    def _snapshot(state: _State) -> _Snapshot:
+        return _Snapshot(
+            state,
+            dict(state.current),
+            state.fallback,
+            None if state.schema is None else set(state.schema),
+            state.epoch,
+            state.tainted,
+            dict(state.versions),
+            set(state.removed),
+            state.history,
+        )
+
+    def _lookup_snapshot(
+        self, snapshot: _Snapshot, name: str, context: _Context, node: ast.AST
+    ) -> str | None:
+        if name in snapshot.current:
+            return snapshot.current[name]
+        if name in snapshot.removed or (
+            snapshot.schema is not None and name not in snapshot.schema
+        ):
+            self._diagnose(
+                context,
+                node,
+                "CT_MISSING_COLUMN",
+                f"Column {name!r} is absent from the known schema.",
+            )
+            return None
+        if snapshot.fallback is not None:
+            copy = snapshot.fallback
+            source_name = copy.names.get(name, name)
+            source = self._lookup_snapshot(copy.source, source_name, copy.context, copy.node)
+            if source is None:
+                return None
+            evidence = _confidence(copy.evidence, self.columns[source].evidence)
+            identifier = _identifier("copy", snapshot.state.record.id, name, snapshot.epoch)
+            if identifier not in self.columns:
+                record = snapshot.state.record
+                version = 0
+                snapshot.state.versions[name] = max(snapshot.state.versions.get(name, -1), version)
+                column = Column(
+                    identifier,
+                    record.id,
+                    name,
+                    version,
+                    self._location(copy.context, copy.node),
+                    copy.context.module.name,
+                    copy.context.scope,
+                    copy.context.key,
+                    "copy",
+                    evidence,
+                    self.columns[source].completeness,
+                )
+                self.columns[identifier] = column
+                operation = self._operation(
+                    copy.context,
+                    copy.node,
+                    "rename" if name in copy.names else "pass",
+                    identifier,
+                    evidence,
+                    column.completeness,
+                )
+                self.edges.extend(
+                    [
+                        Edge(source, operation.id, "read", evidence),
+                        Edge(operation.id, identifier, "write", evidence),
+                    ]
+                )
+                kind = "rename" if name in copy.names else record.origin
+                self.column_history[identifier] = self._event(
+                    copy.context,
+                    copy.node,
+                    kind,
+                    f"{source_name} -> {name}"
+                    if kind == "rename"
+                    else f"Preserve {name} through {kind}",
+                    frames=(copy.source.state.record.id, record.id),
+                    inputs=(source,),
+                    outputs=(identifier,),
+                    parents=tuple(
+                        dict.fromkeys(
+                            snapshot.history
+                            + (
+                                (self.column_history[source],)
+                                if source in self.column_history
+                                else ()
+                            )
+                        )
+                    ),
+                    evidence=evidence,
+                    completeness=column.completeness,
+                )
+            snapshot.current[name] = identifier
+            return identifier
+        return self._external(snapshot, name, context, node)
+
+    def _read(
+        self,
+        state: _State,
+        name: str,
+        context: _Context,
+        node: ast.AST,
+        *,
+        record: bool = True,
+    ) -> _Value:
+        if state.positional is not None and state.schema is None:
+            self._diagnose(
+                context,
+                node,
+                "CT_UNSUPPORTED_POSITIONAL_COLUMN",
+                "Unlabeled row-result columns require a matching multi-column assignment.",
+            )
+            return _Value()
+        snapshot = self._snapshot(state)
+        identifier = self._lookup_snapshot(snapshot, name, context, node)
+        if identifier is None:
+            return _Value()
+        state.current[name] = identifier
+        self.consumptions.append(
+            Consumption(
+                identifier,
+                self._location(context, node),
+                context.module.name,
+                context.scope,
+                context.key,
+            )
+        )
+        column = self.columns[identifier]
+        parents = (self.column_history[identifier],) if identifier in self.column_history else ()
+        if record:
+            parents = (
+                self._event(
+                    context,
+                    node,
+                    "read",
+                    f"Read column {name}",
+                    frames=(state.record.id,),
+                    inputs=(identifier,),
+                    parents=parents,
+                    evidence=column.evidence,
+                    completeness=column.completeness,
+                ),
+            )
+        return _Value(
+            "series",
+            dependencies=(identifier,),
+            evidence=column.evidence,
+            completeness=column.completeness,
+            epochs=((state.record.id, state.epoch),),
+            index_key=state.index_key,
+            history=parents,
+        )
+
+    def _refresh(self, value: _Value) -> _Value:
+        if any(self.states[identifier].epoch != epoch for identifier, epoch in value.epochs):
+            return _Value(
+                value.kind,
+                evidence="unresolved",
+                completeness="unresolved",
+                escaped=tuple(
+                    dict.fromkeys(
+                        value.escaped + tuple(identifier for identifier, _ in value.epochs)
+                    )
+                ),
+            )
+        return value
+
+    def _invalidate(
+        self,
+        values: list[_Value],
+        context: _Context | None = None,
+        node: ast.AST | None = None,
+    ) -> None:
+        states: dict[str, _State] = {}
+        for value in values:
+            if value.frame is not None:
+                states[value.frame.record.id] = value.frame
+            for dependency in value.dependencies:
+                frame_id = self.columns[dependency].dataframe_id
+                states[frame_id] = self.states[frame_id]
+            for frame_id in value.escaped:
+                states[frame_id] = self.states[frame_id]
+        if states and context is not None and node is not None:
+            location = self._location(context, node)
+            prior = {event.id: event for event in self.history}
+            already = all(
+                state.record.id in self.frame_boundaries
+                and prior[self.frame_boundaries[state.record.id]].location == location
+                and prior[self.frame_boundaries[state.record.id]].context == context.key
+                for state in states.values()
+            )
+            if not already:
+                diagnostic = next(
+                    (
+                        item
+                        for item in reversed(self.diagnostics)
+                        if item.location == location and item.scope == context.scope
+                    ),
+                    None,
+                )
+                event = self._event(
+                    context,
+                    node,
+                    "boundary",
+                    f"Provenance interrupted: {diagnostic.code}"
+                    if diagnostic
+                    else "Unresolved mutation effects",
+                    frames=tuple(states),
+                    # Forgetting abstract state is an analysis boundary, not
+                    # evidence that the statement read every known column.
+                    parents=tuple(
+                        dict.fromkeys(
+                            parent for state in states.values() for parent in state.history
+                        )
+                    ),
+                    evidence="unresolved",
+                    completeness="unresolved",
+                )
+                for frame_id in states:
+                    self.frame_boundaries[frame_id] = event
+        for state in states.values():
+            state.current.clear()
+            state.fallback = None
+            state.schema = None
+            state.removed.clear()
+            state.epoch += 1
+            state.index_key = _identifier("index", state.record.id, state.epoch)
+            state.positional = None
+            state.tainted = True
+            if state.record.id in self.frame_boundaries:
+                state.history = (self.frame_boundaries[state.record.id],)
+            state.versions = {name: version + 1 for name, version in state.versions.items()}
+
+    def _escaped(self, values: list[_Value]) -> tuple[str, ...]:
+        identifiers: list[str] = []
+        for value in values:
+            identifiers.extend(value.escaped)
+            if value.frame is not None:
+                identifiers.append(value.frame.record.id)
+            identifiers.extend(self.columns[column].dataframe_id for column in value.dependencies)
+        return tuple(dict.fromkeys(identifiers))
+
+    def _consume(self, value: _Value, context: _Context, node: ast.AST, kind: str) -> str | None:
+        dependencies = value.dependencies
+        if value.frame is not None:
+            dependencies = tuple(value.frame.current.values())
+        for identifier in value.escaped:
+            dependencies += tuple(self.states[identifier].current.values())
+        for identifier in dict.fromkeys(dependencies):
+            self.consumptions.append(
+                Consumption(
+                    identifier,
+                    self._location(context, node),
+                    context.module.name,
+                    context.scope,
+                    context.key,
+                    kind,
+                )
+            )
+        frames = self._escaped([value])
+        if dependencies or frames:
+            event_kind = (
+                "boundary"
+                if kind == "opaque_call"
+                else (kind if kind in {"sink", "return", "filter"} else "consume")
+            )
+            event = self._event(
+                context,
+                node,
+                event_kind,
+                kind.replace("_", " "),
+                frames=frames,
+                inputs=dependencies,
+                parents=self._parents(value)
+                + (value.frame.history if value.frame is not None else ()),
+                evidence="unresolved" if kind == "opaque_call" else value.evidence,
+                completeness="unresolved" if kind == "opaque_call" else value.completeness,
+                expression=f"Callback {node.name}(...)"
+                if isinstance(node, ast.FunctionDef)
+                else None,
+            )
+            if event_kind == "boundary":
+                for frame_id in frames:
+                    self.frame_boundaries[frame_id] = event
+            return event
+        return None
+
+    def _symbol(self, node: ast.AST, context: _Context) -> str:
+        if isinstance(node, ast.Name):
+            value = context.env.get(node.id, _Value())
+            return value.symbol if value.kind == "symbol" else ""
+        if isinstance(node, ast.Attribute):
+            base = self._symbol(node.value, context)
+            symbol = f"{base}.{node.attr}" if base else ""
+            if any(
+                symbol == changed or symbol.startswith(changed + ".")
+                for changed in self.api_mutations
+            ):
+                return ""
+            return symbol
+        return ""
+
+    @staticmethod
+    def _literal(node: ast.AST) -> bool:
+        if isinstance(node, ast.Constant):
+            return True
+        if isinstance(node, (ast.List, ast.Tuple, ast.Set)):
+            return all(_Analyzer._literal(item) for item in node.elts)
+        if isinstance(node, ast.Dict):
+            return all(key is not None and _Analyzer._literal(key) for key in node.keys) and all(
+                _Analyzer._literal(value) for value in node.values
+            )
+        return (
+            isinstance(node, ast.UnaryOp)
+            and isinstance(node.op, (ast.UAdd, ast.USub))
+            and (_Analyzer._literal(node.operand))
+        )
+
+    @staticmethod
+    def _column_target(node: ast.Subscript) -> tuple[ast.expr, str | None]:
+        receiver = node.value
+        label: ast.AST = node.slice
+        if isinstance(receiver, ast.Attribute) and receiver.attr == "loc":
+            receiver = receiver.value
+            if not isinstance(label, ast.Tuple) or len(label.elts) != 2:
+                return receiver, None
+            rows, label = label.elts
+            if not isinstance(rows, ast.Slice) or any((rows.lower, rows.upper, rows.step)):
+                return receiver, None
+        if isinstance(label, ast.Constant) and isinstance(label.value, str):
+            return receiver, label.value
+        return receiver, None
+
+    @staticmethod
+    def _column_names(node: ast.AST) -> tuple[str, ...] | None:
+        if isinstance(node, (ast.List, ast.Tuple)) and all(
+            isinstance(item, ast.Constant) and isinstance(item.value, str) for item in node.elts
+        ):
+            names = tuple(str(item.value) for item in node.elts if isinstance(item, ast.Constant))
+            return names if names and len(names) == len(set(names)) else None
+        return None
+
+    @staticmethod
+    def _combined(values: list[_Value], *, kind: Literal["series", "mask"] = "series") -> _Value:
+        indexes = {value.index_key for value in values if value.index_key is not None}
+        return _Value(
+            kind,
+            dependencies=tuple(dict.fromkeys(d for value in values for d in value.dependencies)),
+            evidence=_confidence(*(value.evidence for value in values)),
+            completeness=_completeness(*(value.completeness for value in values)),
+            epochs=tuple(dict.fromkeys(epoch for value in values for epoch in value.epochs)),
+            index_key=next(iter(indexes)) if len(indexes) == 1 else None,
+            history=tuple(dict.fromkeys(item for value in values for item in value.history)),
+        )
+
+    def _materialize(self, state: _State, context: _Context, node: ast.AST) -> None:
+        for name in sorted(self._known_columns(self._snapshot(state))):
+            self._read(state, name, context, node, record=False)
+
+    def _method_available(self, owner: str, name: str) -> bool:
+        symbol = f"pandas.{owner}.{name}"
+        return not any(
+            symbol == changed or symbol.startswith(changed + ".") for changed in self.api_mutations
+        )
+
+    def _expr(self, node: ast.AST, context: _Context) -> _Value:
+        value = self._expr_value(node, context)
+        if not isinstance(node, ast.Name) or not value.expression:
+            value = replace(value, expression=self._code(context, node))
+        return value
+
+    def _expr_value(self, node: ast.AST, context: _Context) -> _Value:
+        if self._literal(node):
+            return _Value("literal", completeness="complete")
+        if isinstance(node, ast.Name):
+            return self._refresh(context.env.get(node.id, _Value()))
+        if isinstance(node, ast.Attribute):
+            receiver = self._expr(node.value, context)
+            value = self._attribute(receiver, node.attr)
+            if context.key.startswith("template:") and receiver.symbol.startswith("module:"):
+                return self._isolated(value)
+            return value
+        if isinstance(node, ast.Subscript):
+            receiver_node, name = self._column_target(node)
+            receiver = self._expr(receiver_node, context)
+            if receiver.frame is not None:
+                if name is None:
+                    if not (isinstance(node.value, ast.Attribute) and node.value.attr == "loc"):
+                        names = (
+                            (self._column_names(node.slice) if node.slice.elts else ())
+                            if isinstance(node.slice, ast.List)
+                            else None
+                        )
+                        if names is not None:
+                            return self._project(receiver.frame, names, context, node)
+                        mask = self._expr(node.slice, context)
+                        if mask.kind == "mask" and mask.index_key == receiver.frame.index_key:
+                            self._consume(mask, context, node, "filter")
+                            self._diagnose(
+                                context,
+                                node,
+                                "CT_ROW_CONTROL",
+                                "Row selection changes control/cardinality; mask columns are "
+                                "consumed but are not value dependencies of every output column.",
+                            )
+                            clone = self._clone(
+                                receiver.frame, context, node, "filter", {}, receiver.evidence
+                            )
+                            clone.index_key = clone.record.id
+                            self._materialize(clone, context, node)
+                            return self._frame_value(clone)
+                    self._diagnose(
+                        context,
+                        node,
+                        "CT_DYNAMIC_COLUMN",
+                        "Only a literal string column and full-row .loc are supported.",
+                    )
+                    return _Value(escaped=(receiver.frame.record.id,))
+                return self._read(receiver.frame, name, context, node)
+            if receiver.kind != "literal":
+                self._diagnose(
+                    context,
+                    node,
+                    "CT_UNRESOLVED_RECEIVER",
+                    "No resolved Pandas origin or DataFrame annotation for this receiver.",
+                )
+            return _Value(escaped=receiver.escaped)
+        if isinstance(node, ast.Compare):
+            values = [self._expr(node.left, context)] + [
+                self._expr(item, context) for item in node.comparators
+            ]
+            if (
+                all(
+                    isinstance(op, (ast.Eq, ast.NotEq, ast.Lt, ast.LtE, ast.Gt, ast.GtE))
+                    for op in node.ops
+                )
+                and all(value.kind in {"literal", "series"} for value in values)
+                and any(value.kind == "series" for value in values)
+            ):
+                return self._combined(values, kind="mask")
+            return _Value(escaped=self._escaped(values))
+        if isinstance(node, ast.JoinedStr):
+            values = []
+            for formatted in node.values:
+                if isinstance(formatted, ast.FormattedValue):
+                    values.append(self._expr(formatted.value, context))
+                    if formatted.format_spec is not None:
+                        values.append(self._expr(formatted.format_spec, context))
+            for value in values:
+                self._consume(value, context, node, "observe")
+            return replace(self._combined(values), kind="literal", index_key=None)
+        if isinstance(node, ast.BinOp) and isinstance(
+            node.op, (ast.Add, ast.Sub, ast.Mult, ast.Div, ast.FloorDiv, ast.Mod, ast.Pow)
+        ):
+            left, right = self._expr(node.left, context), self._expr(node.right, context)
+            dependencies = tuple(dict.fromkeys(left.dependencies + right.dependencies))
+            known = left.kind in {"literal", "series"} and right.kind in {"literal", "series"}
+            return _Value(
+                "series" if known else "unknown",
+                dependencies=dependencies,
+                evidence=_confidence(left.evidence, right.evidence) if known else "unresolved",
+                completeness=_completeness(left.completeness, right.completeness),
+                epochs=tuple(dict.fromkeys(left.epochs + right.epochs)),
+                history=tuple(dict.fromkeys(left.history + right.history)),
+            )
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.UAdd, ast.USub)):
+            return self._expr(node.operand, context)
+        if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.Invert):
+            value = self._expr(node.operand, context)
+            return value if value.kind == "mask" else _Value(escaped=self._escaped([value]))
+        if isinstance(node, ast.Call):
+            return self._call(node, context)
+        if isinstance(node, (ast.List, ast.Tuple, ast.Set, ast.Dict)):
+            values = [
+                self._expr(child, context)
+                for child in ast.iter_child_nodes(node)
+                if isinstance(child, ast.expr)
+            ]
+            for value in values:
+                self._consume(value, context, node, "container")
+            return _Value(escaped=self._escaped(values))
+        if isinstance(node, ast.Lambda):
+            return _Value()
+        self._diagnose(
+            context,
+            node,
+            "CT_UNSUPPORTED_EXPRESSION",
+            f"Expression {type(node).__name__} is outside the supported arithmetic subset.",
+        )
+        self._invalidate(list(context.env.values()), context, node)
+        return _Value()
+
+    def _attribute(self, receiver: _Value, name: str) -> _Value:
+        if receiver.frame is not None and name == "index":
+            return _Value(
+                "index",
+                index_key=receiver.frame.index_key,
+                completeness="complete",
+                escaped=(receiver.frame.record.id,),
+            )
+        if receiver.kind == "series" and name == "str":
+            return replace(receiver, kind="accessor")
+        if receiver.kind == "symbol":
+            symbol = f"{receiver.symbol}.{name}"
+            if any(
+                symbol == changed or symbol.startswith(changed + ".")
+                for changed in self.api_mutations
+            ):
+                return _Value()
+            if symbol.startswith("module:"):
+                return self._module_member(symbol.removeprefix("module:"))
+            return _Value("symbol", symbol=symbol)
+        return _Value(escaped=self._escaped([receiver]))
+
+    def _call(self, node: ast.Call, context: _Context) -> _Value:
+        if isinstance(node.func, ast.Attribute):
+            receiver = self._expr(node.func.value, context)
+            function = self._attribute(receiver, node.func.attr)
+            if receiver.frame is not None:
+                if node.func.attr == "assign" and self._method_available("DataFrame", "assign"):
+                    return self._assign(node, receiver.frame, context)
+                if node.func.attr == "rename" and self._method_available("DataFrame", "rename"):
+                    return self._rename(node, receiver.frame, context)
+                if node.func.attr == "dropna" and self._method_available("DataFrame", "dropna"):
+                    return self._dropna(node, receiver.frame, context)
+                if node.func.attr in {"to_parquet", "to_csv"} and self._method_available(
+                    "DataFrame", node.func.attr
+                ):
+                    return self._sink(node, receiver, context)
+            if receiver.kind == "series":
+                if node.func.attr == "apply" and self._method_available("Series", "apply"):
+                    return self._apply(node, receiver, context)
+                if (
+                    node.func.attr == "tolist"
+                    and not node.args
+                    and not node.keywords
+                    and (
+                        receiver.components is not None
+                        and self._method_available("Series", "tolist")
+                    )
+                ):
+                    return replace(receiver, kind="rows")
+            if receiver.kind == "accessor" and self._method_available("Series", "str"):
+                value = self._string_method(node, receiver, context)
+                if value is not None:
+                    return value
+        else:
+            receiver = _Value()
+            function = self._expr(node.func, context)
+        symbol = function.symbol
+        arguments = [self._expr(arg, context) for arg in node.args]
+        keywords = [(keyword.arg, self._expr(keyword.value, context)) for keyword in node.keywords]
+        values = arguments + [value for _, value in keywords]
+        if (
+            isinstance(node.func, ast.Name)
+            and node.func.id not in context.env
+            and node.func.id in {"print", "len"}
+            and not any(isinstance(arg, ast.Starred) for arg in node.args)
+            and not any(name is None for name, _ in keywords)
+        ):
+            valid = (node.func.id == "len" and len(arguments) == 1 and not keywords) or (
+                node.func.id == "print"
+                and all(
+                    name in {"sep", "end", "flush"} and value.kind == "literal"
+                    for name, value in keywords
+                )
+            )
+            if valid:
+                for value in values:
+                    self._consume(value, context, node, "observe")
+                return _Value(
+                    "literal", completeness="partial" if node.func.id == "len" else "complete"
+                )
+        if receiver.frame is not None or receiver.dependencies or receiver.escaped:
+            values.append(receiver)
+        if symbol in {"pandas.read_csv", "pandas.read_parquet", "pandas.DataFrame"}:
+            if symbol == "pandas.DataFrame":
+                rows_frame = self._rows_frame(node, context, arguments, keywords)
+                if rows_frame is not None:
+                    return rows_frame
+            return self._source(node, symbol, context, values)
+        if function.function is not None:
+            return self._invoke(function.function, node, context, arguments, keywords)
+        if function.escaped:
+            values.append(function)
+        for value in values:
+            self._consume(value, context, node, "opaque_call")
+        if any(value.frame is not None or value.dependencies or value.escaped for value in values):
+            self._diagnose(
+                context,
+                node,
+                "CT_OPAQUE_CALL",
+                "Call effects and return provenance are unresolved; affected state is invalidated.",
+            )
+        self._invalidate(values, context, node)
+        return _Value(escaped=self._escaped(values))
+
+    def _source(
+        self, node: ast.Call, symbol: str, context: _Context, values: list[_Value]
+    ) -> _Value:
+        invalid = any(isinstance(arg, ast.Starred) for arg in node.args) or any(
+            keyword.arg is None for keyword in node.keywords
+        )
+        if symbol == "pandas.read_csv":
+            invalid |= len(node.args) > 1 or any(
+                (
+                    kw.arg == "chunksize"
+                    and not (isinstance(kw.value, ast.Constant) and kw.value.value is None)
+                )
+                or (
+                    kw.arg == "iterator"
+                    and not (isinstance(kw.value, ast.Constant) and kw.value.value is False)
+                )
+                for kw in node.keywords
+            )
+        data: ast.AST | None = node.args[0] if len(node.args) == 1 else None
+        if symbol == "pandas.DataFrame":
+            for keyword in node.keywords:
+                if keyword.arg == "data" and not node.args:
+                    data = keyword.value
+            invalid |= (
+                len(node.args) > 1
+                or any(kw.arg != "data" for kw in node.keywords)
+                or not isinstance(data, ast.Dict)
+                or not self._literal(data)
+                or any(
+                    not isinstance(key, ast.Constant) or not isinstance(key.value, str)
+                    for key in data.keys
+                )
+            )
+        if invalid:
+            self._diagnose(
+                context,
+                node,
+                "CT_UNSUPPORTED_SOURCE",
+                "This Pandas constructor/reader signature is outside the supported subset.",
+            )
+            self._invalidate(values, context, node)
+            return _Value()
+        state = self._new_frame(context, node, symbol)
+        resolved = [value.expression for value in values if value.expression]
+        expression = self._code(context, node)
+        if resolved:
+            expression += "\nArguments: " + ", ".join(resolved)
+        state.history = (
+            self._event(
+                context,
+                node,
+                "source",
+                f"Create DataFrame with {symbol}",
+                frames=(state.record.id,),
+                expression=expression,
+                parents=context.parent_history,
+                evidence=state.record.evidence,
+                completeness="complete" if symbol == "pandas.DataFrame" else "partial",
+            ),
+        )
+        if isinstance(data, ast.Dict) and symbol == "pandas.DataFrame":
+            state.schema = set()
+            for key in data.keys:
+                assert isinstance(key, ast.Constant) and isinstance(key.value, str)
+                self._write(
+                    state,
+                    key.value,
+                    _Value("literal", completeness="complete"),
+                    context,
+                    key,
+                    "source",
+                )
+        return self._frame_value(state)
+
+    def _apply(self, node: ast.Call, receiver: _Value, context: _Context) -> _Value:
+        arguments = [self._expr(arg, context) for arg in node.args]
+        keywords = [self._expr(keyword.value, context) for keyword in node.keywords]
+        callback = arguments[0].function if len(arguments) == 1 and not node.keywords else None
+        symbols: dict[str, str] = {}
+        if callback is not None:
+            for name, binding in callback.module.env.items():
+                symbol = binding.symbol if binding.kind == "symbol" else "<unresolved>"
+                if any(
+                    symbol == changed or symbol.startswith(changed + ".")
+                    for changed in self.api_mutations
+                ):
+                    symbol = "<unresolved>"
+                symbols[name] = symbol
+        summary = summarize_callback(callback.node, symbols=symbols) if callback else None
+        if (
+            summary is None
+            or not summary.supported
+            or summary.may_mutate
+            or summary.components is None
+        ):
+            values = [receiver, *arguments, *keywords]
+            if callback is not None and not context.key.startswith("template:"):
+                values.extend(callback.module.env.values())
+            for value in values:
+                self._consume(value, context, node, "opaque_call")
+            self._diagnose(
+                context,
+                node,
+                "CT_UNSUPPORTED_APPLY",
+                "Series.apply requires a resolved scalar callback with supported, fixed-shape "
+                "returns and no unresolved mutation effects.",
+            )
+            self._invalidate(values, context, node)
+            return _Value(escaped=self._escaped(values))
+        assert callback is not None
+        self._consume(receiver, context, node, "apply_input")
+        callback_context = _Context(
+            callback.module,
+            callback.node.name,
+            f"{context.key}>apply:{callback.module.name}.{callback.node.name}",
+            {},
+            context.stack,
+        )
+        self._consume(receiver, callback_context, callback.node, "callback_input")
+        apply_event = self._event(
+            context,
+            node,
+            "apply",
+            f"Apply {callback.module.name}.{callback.node.name}",
+            frames=self._escaped([receiver]),
+            inputs=receiver.dependencies,
+            parents=self._parents(receiver),
+            evidence="inferred",
+            completeness=receiver.completeness,
+        )
+        step_events: dict[str, str] = {}
+        for step in summary.steps:
+            marker = ast.Name(id="callback_step", ctx=ast.Load())
+            marker.lineno, marker.col_offset = step.line, step.column
+            marker.end_lineno, marker.end_col_offset = step.end_line, step.end_column
+            step_events[step.id] = self._event(
+                callback_context,
+                marker,
+                {
+                    "value": "callback_step",
+                    "control": "callback_control",
+                    "configuration": "callback_configuration",
+                    "context": "callback_context",
+                }[step.role],
+                step.label,
+                frames=self._escaped([receiver]),
+                inputs=receiver.dependencies if step.depends_on_input else (),
+                parents=tuple(step_events[parent] for parent in step.parents) or (apply_event,),
+                expression=step.expression,
+                evidence="inferred",
+                completeness=receiver.completeness,
+            )
+        self._diagnose(
+            context,
+            node,
+            "CT_CALLBACK_INFERRED",
+            f"Callback {callback.module.name}.{callback.node.name} resolved statically; "
+            "scalar API behavior is inferred and runtime execution is not validated.",
+        )
+        components = tuple(
+            _Value(
+                "series",
+                dependencies=receiver.dependencies if part.depends_on_input else (),
+                evidence=_confidence(receiver.evidence, part.evidence),
+                completeness=_completeness(receiver.completeness, part.completeness),
+                epochs=receiver.epochs,
+                index_key=receiver.index_key,
+                producer="apply",
+                expression=f"{self._code(context, node)} [return component {index + 1}]",
+                history=tuple(step_events[item] for item in part.steps) or (apply_event,),
+            )
+            for index, part in enumerate(summary.components)
+        )
+        result = self._combined(list(components))
+        return replace(result, components=components, producer="apply")
+
+    def _string_method(self, node: ast.Call, receiver: _Value, context: _Context) -> _Value | None:
+        assert isinstance(node.func, ast.Attribute)
+        method = node.func.attr
+        if not self._method_available("Series.str", method):
+            return None
+        no_args = {"strip", "lstrip", "rstrip", "lower", "upper", "casefold", "len"}
+        if method not in no_args | {"contains", "startswith", "endswith", "replace"}:
+            return None
+        if not all(self._literal(arg) for arg in node.args) or not all(
+            keyword.arg is not None and self._literal(keyword.value) for keyword in node.keywords
+        ):
+            return None
+        if method in no_args and (node.args or node.keywords):
+            return None
+        self._consume(receiver, context, node, "string_transform")
+        event = self._event(
+            context,
+            node,
+            "string_transform",
+            f"Series.str.{method}",
+            frames=self._escaped([receiver]),
+            inputs=receiver.dependencies,
+            parents=self._parents(receiver),
+            evidence=receiver.evidence,
+            completeness=receiver.completeness,
+        )
+        return replace(
+            receiver,
+            kind="mask" if method in {"contains", "startswith", "endswith"} else "series",
+            components=None,
+            producer="derive",
+            history=(event,),
+        )
+
+    def _rows_frame(
+        self,
+        node: ast.Call,
+        context: _Context,
+        arguments: list[_Value],
+        keywords: list[tuple[str | None, _Value]],
+    ) -> _Value | None:
+        options = dict(keywords)
+        data = arguments[0] if len(arguments) == 1 else options.get("data", _Value())
+        if data.kind != "rows":
+            return None
+        index = options.get("index", _Value())
+        valid = (
+            len(arguments) <= 1
+            and not (arguments and "data" in options)
+            and all(name in {"data", "index"} for name, _ in keywords)
+            and data.components is not None
+            and index.kind == "index"
+            and data.index_key is not None
+            and data.index_key == index.index_key
+        )
+        if not valid:
+            self._diagnose(
+                context,
+                node,
+                "CT_UNRESOLVED_ALIGNMENT",
+                "Row-result DataFrame needs fixed width and an explicit matching source index.",
+            )
+            return _Value(escaped=self._escaped([data, index]))
+        state = self._new_frame(context, node, "pandas.DataFrame.rows", data.evidence)
+        state.positional = data.components
+        state.schema = set()
+        assert data.index_key is not None
+        state.index_key = data.index_key
+        return self._frame_value(state)
+
+    def _sink(self, node: ast.Call, receiver: _Value, context: _Context) -> _Value:
+        assert receiver.frame is not None
+        values = [self._expr(arg, context) for arg in node.args]
+        values.extend(self._expr(keyword.value, context) for keyword in node.keywords)
+        valid = len(node.args) <= 1 and all(
+            keyword.arg is not None and self._literal(keyword.value) for keyword in node.keywords
+        )
+        self._materialize(receiver.frame, context, node)
+        self._consume(receiver, context, node, "sink" if valid else "opaque_call")
+        if valid:
+            destinations = [value.expression for value in values if value.expression]
+            self._event(
+                context,
+                node,
+                "sink",
+                "Export DataFrame" + (" to " + destinations[0] if destinations else ""),
+                frames=(receiver.frame.record.id,),
+                inputs=tuple(receiver.frame.current.values()),
+                parents=receiver.frame.history,
+                expression=self._code(context, node)
+                + ("\nArguments: " + ", ".join(destinations) if destinations else ""),
+                evidence=receiver.evidence,
+                completeness="partial" if receiver.frame.schema is None else "complete",
+            )
+            return _Value("literal", completeness="complete")
+        values.append(receiver)
+        if not context.key.startswith("template:"):
+            for value in list(values):
+                if value.function is not None:
+                    values.extend(value.function.module.env.values())
+        self._diagnose(
+            context,
+            node,
+            "CT_UNSUPPORTED_SINK",
+            "Export needs literal keyword options; dynamic options may have unknown effects.",
+        )
+        self._invalidate(values, context, node)
+        return _Value(escaped=self._escaped(values))
+
+    def _project(
+        self, state: _State, names: tuple[str, ...], context: _Context, node: ast.AST
+    ) -> _Value:
+        if any(
+            name in state.removed or (state.schema is not None and name not in state.schema)
+            for name in names
+        ):
+            self._diagnose(
+                context, node, "CT_MISSING_COLUMN", "Projection contains a missing column."
+            )
+            return _Value()
+        clone = self._clone(state, context, node, "projection", {}, state.record.evidence)
+        clone.schema = set(names)
+        # Record the structural selection even when no retained column creates
+        # a pass event. An empty projection has a meaningful column fate.
+        projection = self._event(
+            context,
+            node,
+            "projection",
+            "Project literal columns",
+            frames=(state.record.id, clone.record.id),
+            parents=state.history,
+            evidence=state.record.evidence,
+            completeness="complete",
+        )
+        clone.history = (projection,)
+        for name in names:
+            self._read(clone, name, context, node, record=False)
+        return self._frame_value(clone)
+
+    def _dropna(self, node: ast.Call, state: _State, context: _Context) -> _Value:
+        valid = not node.args
+        subset: tuple[str, ...] | None = None
+        inplace = False
+        for keyword in node.keywords:
+            if keyword.arg == "subset":
+                subset = self._column_names(keyword.value)
+                valid &= subset is not None
+            elif keyword.arg == "inplace" and isinstance(keyword.value, ast.Constant):
+                valid &= type(keyword.value.value) is bool
+                inplace = keyword.value.value is True
+            elif keyword.arg == "axis" and isinstance(keyword.value, ast.Constant):
+                valid &= keyword.value.value in {0, "index"}
+            elif keyword.arg == "how" and isinstance(keyword.value, ast.Constant):
+                valid &= keyword.value.value in {"any", "all"}
+            else:
+                valid = False
+        if not valid:
+            for arg in node.args:
+                self._expr(arg, context)
+            for keyword in node.keywords:
+                self._expr(keyword.value, context)
+            self._diagnose(
+                context,
+                node,
+                "CT_UNSUPPORTED_DROPNA",
+                "Only row dropna with literal options is supported.",
+            )
+            self._invalidate([self._frame_value(state)], context, node)
+            return _Value()
+        for name in subset or sorted(self._known_columns(self._snapshot(state))):
+            self._consume(
+                self._read(state, name, context, node, record=False), context, node, "filter"
+            )
+        self._diagnose(
+            context,
+            node,
+            "CT_ROW_CONTROL",
+            "Dropna changes row control/cardinality; subset columns are recorded as filter "
+            "consumptions without all-to-all value dependencies.",
+        )
+        if inplace:
+            state.index_key = _identifier("index", state.index_key, self._location(context, node))
+            return _Value("literal", completeness="complete")
+        clone = self._clone(state, context, node, "dropna", {}, state.record.evidence)
+        clone.index_key = clone.record.id
+        self._materialize(clone, context, node)
+        return self._frame_value(clone)
+
+    def _clone(
+        self,
+        state: _State,
+        context: _Context,
+        node: ast.AST,
+        kind: str,
+        names: dict[str, str],
+        evidence: Confidence,
+    ) -> _State:
+        clone = self._new_frame(context, node, kind, _confidence(state.record.evidence, evidence))
+        clone.schema = (
+            None
+            if state.schema is None
+            else {
+                next((new for new, old in names.items() if old == name), name)
+                for name in state.schema
+            }
+        )
+        clone.fallback = _Copy(self._snapshot(state), names, context, node, clone.record.evidence)
+        clone.history = state.history
+        clone.index_key = state.index_key
+        clone.removed = (state.removed | set(names.values())) - names.keys()
+        return clone
+
+    def _known_columns(self, snapshot: _Snapshot) -> set[str]:
+        known = set(snapshot.current)
+        if snapshot.fallback is not None:
+            names = snapshot.fallback.names
+            known.update(
+                next((new for new, old in names.items() if old == name), name)
+                for name in self._known_columns(snapshot.fallback.source)
+            )
+        known -= snapshot.removed
+        return known if snapshot.schema is None else known & snapshot.schema
+
+    def _rename(self, node: ast.Call, state: _State, context: _Context) -> _Value:
+        mapping: dict[str, str] = {}
+        valid = not node.args
+        found = False
+        inplace = False
+        for keyword in node.keywords:
+            if keyword.arg == "columns" and isinstance(keyword.value, ast.Dict):
+                found = True
+                for key, value in zip(keyword.value.keys, keyword.value.values, strict=True):
+                    if (
+                        isinstance(key, ast.Constant)
+                        and isinstance(key.value, str)
+                        and isinstance(value, ast.Constant)
+                        and isinstance(value.value, str)
+                    ):
+                        mapping[key.value] = value.value
+                    else:
+                        valid = False
+            elif keyword.arg == "inplace" and isinstance(keyword.value, ast.Constant):
+                valid &= type(keyword.value.value) is bool
+                inplace = keyword.value.value is True
+            else:
+                valid = False
+        valid &= found and len(set(mapping.values())) == len(mapping)
+        known = self._known_columns(self._snapshot(state))
+        valid &= not any(new in known - mapping.keys() for new in mapping.values())
+        valid &= not any(old in state.removed for old in mapping)
+        if state.schema is not None:
+            valid &= all(name in state.schema for name in mapping)
+            valid &= not any(new in state.schema - mapping.keys() for new in mapping.values())
+        if not valid:
+            for arg in node.args:
+                self._expr(arg, context)
+            for keyword in node.keywords:
+                self._expr(keyword.value, context)
+            self._diagnose(
+                context,
+                node,
+                "CT_UNSUPPORTED_RENAME",
+                "Rename needs an injective literal columns mapping, no known schema collision, "
+                "and a literal boolean inplace option.",
+            )
+            if any(keyword.arg == "inplace" for keyword in node.keywords):
+                self._invalidate([self._frame_value(state)], context, node)
+            return _Value()
+        evidence: Confidence = "confirmed" if state.schema is not None else "inferred"
+        if evidence == "inferred":
+            self._diagnose(
+                context,
+                node,
+                "CT_RENAME_SCHEMA_ASSUMPTION",
+                "Rename assumes source columns exist and destination labels do not collide; "
+                "the external schema is unknown.",
+            )
+        if inplace:
+            before = self._snapshot(state)
+            values: dict[str, _Value] = {}
+            for old, new in mapping.items():
+                source = self._lookup_snapshot(before, old, context, node)
+                if source is not None:
+                    column = self.columns[source]
+                    values[new] = _Value(
+                        "series",
+                        dependencies=(source,),
+                        evidence=_confidence(evidence, column.evidence),
+                        completeness=column.completeness,
+                    )
+            for old in mapping:
+                state.current.pop(old, None)
+            state.removed = (state.removed | set(mapping)) - set(mapping.values())
+            if state.schema is not None:
+                state.schema = {mapping.get(name, name) for name in state.schema}
+            for new, column_value in values.items():
+                self._write(state, new, column_value, context, node, "rename")
+            return _Value("literal", completeness="complete")
+        clone = self._clone(
+            state, context, node, "rename", {new: old for old, new in mapping.items()}, evidence
+        )
+        for name in mapping.values():
+            self._read(clone, name, context, node, record=False)
+        return self._frame_value(clone)
+
+    def _assign(self, node: ast.Call, state: _State, context: _Context) -> _Value:
+        if node.args or any(keyword.arg is None for keyword in node.keywords):
+            self._diagnose(
+                context,
+                node,
+                "CT_UNSUPPORTED_ASSIGN",
+                "Assign requires explicit keyword arguments.",
+            )
+            self._invalidate([self._frame_value(state)], context, node)
+            return _Value()
+        eager: dict[str, _Value] = {}
+        for keyword in node.keywords:
+            assert keyword.arg is not None
+            if not isinstance(keyword.value, ast.Lambda):
+                eager[keyword.arg] = self._expr(keyword.value, context)
+        clone = self._clone(state, context, node, "assign", {}, state.record.evidence)
+        for keyword in node.keywords:
+            assert keyword.arg is not None
+            if isinstance(keyword.value, ast.Lambda):
+                function = keyword.value
+                args = function.args
+                if (
+                    len(args.posonlyargs + args.args) != 1
+                    or args.kwonlyargs
+                    or args.vararg
+                    or args.kwarg
+                    or args.defaults
+                ):
+                    self._diagnose(
+                        context,
+                        function,
+                        "CT_UNSUPPORTED_ASSIGN",
+                        "Assign lambdas need one positional parameter and no defaults.",
+                    )
+                    value = _Value()
+                else:
+                    env = dict(context.env)
+                    env[(args.posonlyargs + args.args)[0].arg] = self._frame_value(clone)
+                    nested = _Context(
+                        context.module, context.scope, context.key, env, context.stack
+                    )
+                    value = self._expr(function.body, nested)
+            else:
+                value = eager[keyword.arg]
+                if value.kind not in {"literal", "series"}:
+                    self._diagnose(
+                        context,
+                        keyword.value,
+                        "CT_UNSUPPORTED_ASSIGN",
+                        "An unresolved assign value may be callable; its effects on the copy "
+                        "are not modeled.",
+                    )
+                    self._invalidate([self._frame_value(clone)], context, keyword.value)
+            self._write(clone, keyword.arg, value, context, keyword.value)
+        return self._frame_value(clone)
+
+    def _module_member(self, dotted: str, *, prefer_attribute: bool = True) -> _Value:
+        if self._ambiguous_module(dotted):
+            return _Value()
+        module_name, _, member = dotted.rpartition(".")
+        parent = self.modules.get(module_name)
+        if parent is not None:
+            self._module(parent)
+            if prefer_attribute and member in parent.env:
+                return parent.env[member]
+        if dotted in self.modules:
+            self._module(self.modules[dotted])
+            value = _Value("symbol", symbol=f"module:{dotted}")
+            if parent is not None:
+                parent.env[member] = value
+            return value
+        if parent is not None:
+            return parent.env.get(member, _Value())
+        return _Value("symbol", symbol=f"module:{dotted}")
+
+    def _ambiguous_module(self, name: str) -> bool:
+        return any(name == module or name.startswith(module + ".") for module in self.ambiguous)
+
+    def _import(self, node: ast.Import | ast.ImportFrom, context: _Context) -> None:
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                name = alias.asname or alias.name.split(".")[0]
+                if self._ambiguous_module(alias.name):
+                    context.env[name] = _Value()
+                    continue
+                if alias.name in self.modules or any(
+                    key.startswith(alias.name + ".") for key in self.modules
+                ):
+                    self._module_member(alias.name, prefer_attribute=False)
+                    module_name = alias.name if alias.asname else alias.name.split(".")[0]
+                    context.env[name] = _Value("symbol", symbol=f"module:{module_name}")
+                else:
+                    context.env[name] = _Value("symbol", symbol=alias.name)
+            return
+        module_name = node.module or ""
+        if node.level:
+            package = context.module.name.split(".")
+            if not context.module.path.endswith("/__init__.py"):
+                package = package[:-1]
+            if node.level > len(package):
+                module_name = ""
+            else:
+                module_name = ".".join(
+                    package[: len(package) - node.level + 1]
+                    + (module_name.split(".") if module_name else [])
+                )
+        for alias in node.names:
+            if alias.name == "*":
+                self._diagnose(
+                    context, node, "CT_STAR_IMPORT", "Wildcard imports invalidate name resolution."
+                )
+                self._invalidate(list(context.env.values()), context, node)
+                context.env.clear()
+                continue
+            if self._ambiguous_module(module_name):
+                context.env[alias.asname or alias.name] = _Value()
+                continue
+            if module_name in self.modules or any(
+                key.startswith(module_name + ".") for key in self.modules
+            ):
+                value = self._module_member(f"{module_name}.{alias.name}")
+            else:
+                value = _Value("symbol", symbol=f"{module_name}.{alias.name}")
+                if value.symbol in self.api_mutations:
+                    value = _Value()
+            if context.key.startswith("template:"):
+                value = self._isolated(value)
+            context.env[alias.asname or alias.name] = value
+
+    def _bind(self, target: ast.AST, value: _Value, context: _Context) -> None:
+        if isinstance(target, ast.Name):
+            context.env[target.id] = value
+            if value.frame is not None:
+                frame = value.frame
+                event = self._event(
+                    context,
+                    target,
+                    "bind",
+                    f"{target.id} <- {value.expression or frame.record.origin}",
+                    frames=(frame.record.id,),
+                    parents=tuple(dict.fromkeys(frame.history + value.history)),
+                    expression=f"{target.id} = {value.expression}"
+                    if value.expression
+                    else target.id,
+                    evidence=value.evidence,
+                    completeness=value.completeness,
+                )
+                frame.history = (event,)
+                context.env[target.id] = replace(value, history=(event,))
+            return
+        if isinstance(target, ast.Subscript):
+            receiver_node, name = self._column_target(target)
+            receiver = self._expr(receiver_node, context)
+            if receiver.frame is not None:
+                if name is not None:
+                    self._write(receiver.frame, name, value, context, target)
+                else:
+                    names = (
+                        self._column_names(target.slice)
+                        if isinstance(target.slice, ast.List)
+                        else None
+                    )
+                    if names is not None:
+                        source = value.frame
+                        parts = source.positional if source is not None else None
+                        if (
+                            parts is not None
+                            and len(parts) == len(names)
+                            and source is not None
+                            and source.index_key == receiver.frame.index_key
+                        ):
+                            for column_name, part in zip(names, parts, strict=True):
+                                self._write(receiver.frame, column_name, part, context, target)
+                            return
+                        self._diagnose(
+                            context,
+                            target,
+                            "CT_UNRESOLVED_MULTI_ASSIGN",
+                            "Multi-column assignment needs matching tuple width and row index; "
+                            "no positional dependencies are assumed.",
+                        )
+                        self._invalidate([receiver], context, target)
+                        return
+                    self._diagnose(
+                        context,
+                        target,
+                        "CT_DYNAMIC_COLUMN",
+                        "A dynamic or partial column write invalidates the DataFrame state.",
+                    )
+                    self._invalidate([receiver], context, target)
+            elif receiver.kind != "literal":
+                self._diagnose(
+                    context,
+                    target,
+                    "CT_UNRESOLVED_RECEIVER",
+                    "Cannot bind a column write to a resolved DataFrame.",
+                )
+                self._invalidate([receiver], context, target)
+            return
+        if isinstance(target, ast.Attribute):
+            receiver = self._expr(target.value, context)
+            symbol = self._symbol(target, context)
+            if symbol:
+                self.api_mutations.add(symbol)
+            if receiver.frame is not None or receiver.dependencies or symbol.startswith("pandas"):
+                self._diagnose(
+                    context,
+                    target,
+                    "CT_ATTRIBUTE_MUTATION",
+                    "Attribute mutation is not modeled and invalidates affected evidence.",
+                )
+                self._invalidate([receiver], context, target)
+            return
+        self._diagnose(
+            context, target, "CT_UNSUPPORTED_TARGET", "Unpacking/chained targets are not modeled."
+        )
+        self._invalidate([value] + list(context.env.values()), context, target)
+        for child in ast.walk(target):
+            if isinstance(child, ast.Name):
+                context.env[child.id] = _Value()
+
+    @staticmethod
+    def _bound_names(node: ast.AST) -> set[str]:
+        names: set[str] = set()
+
+        class Visitor(ast.NodeVisitor):
+            def visit_Name(self, child: ast.Name) -> None:
+                if isinstance(child.ctx, (ast.Store, ast.Del)):
+                    names.add(child.id)
+
+            def visit_FunctionDef(self, child: ast.FunctionDef) -> None:
+                names.add(child.name)
+
+            def visit_AsyncFunctionDef(self, child: ast.AsyncFunctionDef) -> None:
+                names.add(child.name)
+
+            def visit_ClassDef(self, child: ast.ClassDef) -> None:
+                names.add(child.name)
+
+            def visit_Lambda(self, child: ast.Lambda) -> None:
+                pass
+
+            def visit_Import(self, child: ast.Import) -> None:
+                names.update(alias.asname or alias.name.split(".")[0] for alias in child.names)
+
+            def visit_ImportFrom(self, child: ast.ImportFrom) -> None:
+                names.update(alias.asname or alias.name for alias in child.names)
+
+            def visit_ExceptHandler(self, child: ast.ExceptHandler) -> None:
+                if child.name:
+                    names.add(child.name)
+                self.generic_visit(child)
+
+            def visit_MatchAs(self, child: ast.MatchAs) -> None:
+                if child.name:
+                    names.add(child.name)
+                self.generic_visit(child)
+
+            def visit_MatchStar(self, child: ast.MatchStar) -> None:
+                if child.name:
+                    names.add(child.name)
+
+            def visit_MatchMapping(self, child: ast.MatchMapping) -> None:
+                if child.rest:
+                    names.add(child.rest)
+                self.generic_visit(child)
+
+        visitor = Visitor()
+        if isinstance(node, ast.FunctionDef):
+            for statement in node.body:
+                visitor.visit(statement)
+        else:
+            visitor.visit(node)
+        return names
+
+    def _statements(self, statements: list[ast.stmt], context: _Context) -> _Value:
+        for node in statements:
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                self._import(node, context)
+            elif isinstance(node, ast.Assign):
+                value = self._expr(node.value, context)
+                for target in node.targets:
+                    self._bind(target, value, context)
+            elif isinstance(node, ast.AnnAssign):
+                if node.value is not None:
+                    self._bind(node.target, self._expr(node.value, context), context)
+            elif isinstance(node, ast.Expr):
+                self._expr(node.value, context)
+            elif isinstance(node, ast.FunctionDef):
+                for decorator in node.decorator_list:
+                    decoration = self._expr(decorator, context)
+                    self._invalidate([decoration], context, decorator)
+                    if decoration.function is not None and not context.key.startswith("template:"):
+                        self._diagnose(
+                            context,
+                            decorator,
+                            "CT_DECORATOR_EFFECTS",
+                            "Applying the resolved decorator may mutate module state; its globals "
+                            "are invalidated rather than assuming a pure decoration.",
+                        )
+                        self._invalidate(
+                            list(decoration.function.module.env.values()), context, decorator
+                        )
+                arguments = node.args.posonlyargs + node.args.args
+                default_nodes = list(
+                    zip(arguments[-len(node.args.defaults) :], node.args.defaults, strict=False)
+                )
+                defaults = {arg.arg: self._expr(default, context) for arg, default in default_nodes}
+                defaults.update(
+                    {
+                        arg.arg: self._expr(default, context)
+                        for arg, default in zip(
+                            node.args.kwonlyargs, node.args.kw_defaults, strict=True
+                        )
+                        if default is not None
+                    }
+                )
+                annotations = [
+                    argument.annotation for argument in arguments + node.args.kwonlyargs
+                ] + [node.returns]
+                if node.args.vararg:
+                    annotations.append(node.args.vararg.annotation)
+                if node.args.kwarg:
+                    annotations.append(node.args.kwarg.annotation)
+                for annotation in annotations:
+                    if annotation is not None and not isinstance(
+                        annotation, (ast.Name, ast.Attribute, ast.Constant)
+                    ):
+                        # Annotation evaluation differs across Python versions
+                        # and future imports. Never execute it, and do not let
+                        # possible effects preserve confirmed object history.
+                        self._diagnose(
+                            context,
+                            annotation,
+                            "CT_UNSUPPORTED_ANNOTATION",
+                            "Dynamic annotation effects are unknown; tracked state is invalidated.",
+                        )
+                        self._invalidate(list(context.env.values()), context, annotation)
+                if node.decorator_list or context.scope != "<module>":
+                    bound = self._bound_names(node) | {
+                        arg.arg for arg in arguments + node.args.kwonlyargs
+                    }
+                    captures = [
+                        context.env[child.id]
+                        for child in ast.walk(node)
+                        if isinstance(child, ast.Name)
+                        and isinstance(child.ctx, ast.Load)
+                        and child.id not in bound
+                        and child.id in context.env
+                    ]
+                    context.env[node.name] = _Value(escaped=self._escaped(captures))
+                    self._diagnose(
+                        context,
+                        node,
+                        "CT_UNSUPPORTED_FUNCTION",
+                        "Nested/decorated function body is unresolved; defining it does not "
+                        "execute its body. Defaults and decorators are analyzed separately.",
+                    )
+                    continue
+                frame_parameters = {
+                    argument.arg
+                    for argument in arguments + node.args.kwonlyargs
+                    if self._dataframe_annotation(argument.annotation, context)
+                }
+                function = _Function(context.module, node, defaults, frame_parameters)
+                self.functions.append(function)
+                context.env[node.name] = _Value("function", function=function)
+            elif isinstance(node, ast.Return):
+                value = self._expr(node.value, context) if node.value else _Value()
+                event = self._consume(value, context, node, "return")
+                if event is not None and value.frame is not None:
+                    value.frame.history = (event,)
+                    value = replace(value, history=(event,))
+                return value
+            elif isinstance(node, (ast.Pass, ast.Assert)):
+                if isinstance(node, ast.Assert):
+                    self._expr(node.test, context)
+                    self._diagnose(
+                        context,
+                        node,
+                        "CT_UNSUPPORTED_CONTROL_FLOW",
+                        "Assertions may terminate execution; reachability is not guaranteed.",
+                    )
+            else:
+                self._diagnose(
+                    context,
+                    node,
+                    "CT_UNSUPPORTED_CONTROL_FLOW",
+                    f"{type(node).__name__} is outside linear analysis; "
+                    "tracked state is invalidated.",
+                )
+                self._invalidate(list(context.env.values()), context, node)
+                self._invalidate_api_writes(node, context)
+                for name in self._bound_names(node):
+                    context.env[name] = _Value()
+        return _Value()
+
+    def _invalidate_api_writes(self, node: ast.AST, context: _Context) -> None:
+        for child in ast.walk(node):
+            if isinstance(child, ast.Attribute) and isinstance(child.ctx, (ast.Store, ast.Del)):
+                symbol = self._symbol(child, context)
+                if symbol:
+                    self.api_mutations.add(symbol)
+
+    def _invoke(
+        self,
+        function: _Function,
+        call: ast.Call,
+        caller: _Context,
+        positional: list[_Value],
+        keywords: list[tuple[str | None, _Value]],
+        *,
+        template: bool = False,
+    ) -> _Value:
+        node = function.node
+        symbolic = template or caller.key.startswith("template:")
+        identity = (function.module.name, node.name)
+        invalid = bool(node.args.vararg or node.args.kwarg)
+        invalid |= identity in caller.stack or len(caller.stack) >= self.MAX_DEPTH
+        invalid |= self.call_count >= self.MAX_CALLS
+        invalid |= any(isinstance(arg, ast.Starred) for arg in call.args)
+        invalid |= any(name is None for name, _ in keywords)
+        invalid |= any(
+            isinstance(child, (ast.Global, ast.Nonlocal, ast.Yield, ast.YieldFrom))
+            for child in ast.walk(node)
+        )
+        arguments = node.args.posonlyargs + node.args.args
+        names = [arg.arg for arg in arguments]
+        values = dict(function.defaults)
+        if symbolic:
+            values = {name: self._isolated(value) for name, value in values.items()}
+        invalid |= len(positional) > len(arguments)
+        assigned: set[str] = set()
+        for name, value in zip(names, positional, strict=False):
+            values[name] = value
+            assigned.add(name)
+        for keyword_name, value in keywords:
+            if keyword_name is None:
+                continue
+            invalid |= keyword_name in assigned or keyword_name in {
+                arg.arg for arg in node.args.posonlyargs
+            }
+            invalid |= keyword_name not in names + [arg.arg for arg in node.args.kwonlyargs]
+            values[keyword_name] = value
+            assigned.add(keyword_name)
+        invalid |= any(arg.arg not in values for arg in arguments + node.args.kwonlyargs)
+        # Early returns cannot be flattened into a single execution path.
+        invalid |= any(isinstance(statement, ast.Return) for statement in node.body[:-1])
+        if invalid:
+            self._diagnose(
+                caller,
+                call,
+                "CT_UNRESOLVED_CALL",
+                "Call signature, recursion, expansion budget, or function body is unsupported.",
+            )
+            inputs = positional + list(values.values())
+            if not symbolic:
+                # An unsupported body can mutate defaults or module objects
+                # without receiving them as explicit call arguments.
+                inputs.extend(function.module.env.values())
+            for value in inputs:
+                self._consume(value, caller, call, "opaque_call")
+            self._invalidate(inputs, caller, call)
+            effects_env = dict(function.module.env)
+            for name in self._bound_names(node):
+                effects_env[name] = _Value()
+            effects_env.update(values)
+            effects_context = _Context(
+                function.module, node.name, caller.key, effects_env, caller.stack
+            )
+            self._invalidate_api_writes(node, effects_context)
+            if not symbolic:
+                for child in ast.walk(node):
+                    if isinstance(child, ast.Global):
+                        for name in child.names:
+                            value = function.module.env.get(name, _Value())
+                            self._invalidate([value])
+                            function.module.env[name] = _Value()
+            return _Value()
+        function.called = True
+        self.call_count += 1
+        env = dict(function.module.env)
+        if symbolic:
+            env = {name: self._isolated(value) for name, value in env.items()}
+        for name in self._bound_names(node):
+            env[name] = _Value()
+        env.update(values)
+        location = self._location(caller, call)
+        key = (
+            f"template:{function.module.name}.{node.name}"
+            if template
+            else f"{caller.key}>{function.module.name}.{node.name}@"
+            f"{location.path}:{location.line}:{location.column}"
+        )
+        supplied = list(values.values())
+        call_event = self._event(
+            caller,
+            call,
+            "call",
+            (
+                f"Analyze function {function.module.name}.{node.name}"
+                if template
+                else f"Call {function.module.name}.{node.name}"
+            ),
+            frames=self._escaped(supplied),
+            inputs=tuple(dict.fromkeys(item for value in supplied for item in value.dependencies)),
+            parents=tuple(
+                dict.fromkeys(
+                    caller.parent_history
+                    + tuple(item for value in supplied for item in self._parents(value))
+                )
+            ),
+            expression=(
+                "Symbolic function analysis; no resolved caller"
+                if template
+                else self._code(caller, call)
+            )
+            + "\nParameters: "
+            + ", ".join(f"{name} <- {value.expression or name}" for name, value in values.items()),
+            evidence="inferred" if symbolic else "confirmed",
+        )
+        context = _Context(
+            function.module, node.name, key, env, caller.stack + (identity,), (call_event,)
+        )
+        for value in supplied:
+            if value.frame is not None:
+                value.frame.history = tuple(dict.fromkeys(value.frame.history + (call_event,)))
+        for argument in (*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs):
+            value = values[argument.arg]
+            if value.frame is not None:
+                # Preserve the proven parameter binding in the callee context;
+                # identical parameter names in unrelated calls stay separate.
+                target = ast.copy_location(ast.Name(id=argument.arg, ctx=ast.Store()), argument)
+                self._bind(target, value, context)
+        for value in positional + [value for _, value in keywords]:
+            self._consume(value, caller, call, "argument")
+        result = self._statements(node.body, context)
+        if result.frame is not None:
+            return result
+        return _Value(escaped=self._escaped([result]))
+
+    def _module(self, module: _Module) -> None:
+        if module.status != "new":
+            return
+        module.status = "visiting"
+        context = _Context(module, "<module>", f"module:{module.name}", module.env)
+        try:
+            self._statements(module.tree.body, context)
+        except RecursionError:
+            self._diagnose(
+                context, module.tree, "CT_ANALYSIS_LIMIT", "AST interpretation depth was exceeded."
+            )
+            self._invalidate(list(context.env.values()))
+        module.status = "done"
+
+    def run(self) -> None:
+        for module in self.modules.values():
+            self._module(module)
+        for function in list(self.functions):
+            if function.called:
+                continue
+            module = function.module
+            node = function.node
+            context = _Context(module, node.name, f"template:{module.name}.{node.name}", module.env)
+            values: list[_Value] = []
+            keywords: list[tuple[str | None, _Value]] = []
+            for argument in node.args.posonlyargs + node.args.args + node.args.kwonlyargs:
+                if argument.arg in function.frame_parameters:
+                    state = self._new_frame(
+                        context, argument, f"parameter:{argument.arg}", "inferred"
+                    )
+                    value = self._frame_value(state)
+                else:
+                    value = self._isolated(function.defaults.get(argument.arg, _Value()))
+                if argument in node.args.kwonlyargs:
+                    keywords.append((argument.arg, value))
+                else:
+                    values.append(value)
+            call = ast.Call(func=ast.Name(id=node.name), args=[], keywords=[])
+            ast.copy_location(call, node)
+            mutations = set(self.api_mutations)
+            try:
+                self._invoke(function, call, context, values, keywords, template=True)
+            except RecursionError:
+                self._diagnose(
+                    context, node, "CT_ANALYSIS_LIMIT", "Function AST traversal depth was exceeded."
+                )
+                self._invalidate(values + [value for _, value in keywords])
+            finally:
+                self.api_mutations = mutations
+
+    @staticmethod
+    def _isolated(value: _Value) -> _Value:
+        if (
+            value.frame is not None
+            or value.dependencies
+            or value.escaped
+            or value.epochs
+            or value.components is not None
+            or value.index_key is not None
+        ):
+            return _Value()
+        return value
+
+    def _dataframe_annotation(self, annotation: ast.AST | None, context: _Context) -> bool:
+        if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
+            try:
+                annotation = ast.parse(annotation.value, mode="eval").body
+            except (SyntaxError, RecursionError):
+                return False
+        return annotation is not None and self._symbol(annotation, context) == "pandas.DataFrame"
+
+
+def analyze_project(path: str | Path, *, config: ScanConfig | None = None) -> LineageReport:
+    """Build static lineage for resolved, linear Pandas code without executing it.
+
+    ``scan_project`` remains available for the broader occurrence inventory. This
+    report contains graph facts only where the lineage interpreter has evidence.
+    """
+    root = Path(path).resolve()
+    discovery = scan_project(root, config=config)
+    modules: dict[str, _Module] = {}
+    ambiguous: set[str] = set()
+    diagnostics = [
+        diagnostic
+        for diagnostic in discovery.diagnostics
+        if diagnostic.code
+        in {
+            "CT_DISCOVERY_ERROR",
+            "CT_READ_ERROR",
+            "CT_ENCODING_ERROR",
+            "CT_SYNTAX_ERROR",
+            "CT_ANALYSIS_LIMIT",
+        }
+    ]
+    limited_files = {item.location.path for item in diagnostics if item.code == "CT_ANALYSIS_LIMIT"}
+    for file in discovery.files:
+        if file.status != "parsed" or file.path in limited_files:
+            continue
+        try:
+            raw = (root / file.path).read_bytes()
+            if hashlib.sha256(raw).hexdigest() != file.sha256:
+                raise ValueError("Source changed during analysis; rescan a stable project.")
+            encoding, _ = tokenize.detect_encoding(io.BytesIO(raw).readline)
+            source = raw.decode(encoding).replace("\r\n", "\n").replace("\r", "\n")
+            tree = ast.parse(source, filename=file.path)
+        except (OSError, UnicodeError, LookupError, SyntaxError, RecursionError, ValueError) as exc:
+            diagnostics.append(
+                Diagnostic("CT_READ_ERROR", "error", str(exc), Location(file.path, 1, 0))
+            )
+            continue
+        if file.module in modules or file.module in ambiguous:
+            diagnostics.append(
+                Diagnostic(
+                    "CT_AMBIGUOUS_MODULE",
+                    "error",
+                    "Multiple files resolve to this module name.",
+                    Location(file.path, 1, 0),
+                )
+            )
+            ambiguous.add(file.module)
+            modules.pop(file.module, None)
+            continue
+        modules[file.module] = _Module(file.module, file.path, source, tree)
+    modules = {
+        name: module
+        for name, module in modules.items()
+        if not any(name.startswith(prefix + ".") for prefix in ambiguous)
+    }
+    analyzer = _Analyzer(modules, ambiguous)
+    analyzer.run()
+    diagnostics.extend(analyzer.diagnostics)
+    return LineageReport(
+        files=discovery.files,
+        functions=discovery.functions,
+        dataframes=tuple(analyzer.frames),
+        columns=tuple(analyzer.columns.values()),
+        operations=tuple(analyzer.operations),
+        edges=tuple(analyzer.edges),
+        consumptions=tuple(analyzer.consumptions),
+        history=tuple(analyzer.history),
+        diagnostics=tuple(
+            sorted(
+                diagnostics,
+                key=lambda diagnostic: (
+                    diagnostic.location.path,
+                    diagnostic.location.line,
+                    diagnostic.location.column,
+                    diagnostic.code,
+                    diagnostic.message,
+                ),
+            )
+        ),
+        exclude=discovery.exclude,
+    )