pebra 0.1.0__py3-none-any.whl

pebra/__main__.py

@@ -0,0 +1,10 @@
+"""Enable ``python -m pebra``."""
+
+from __future__ import annotations
+
+import sys
+
+from pebra.cli.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pebra/adapters/_ast_utils.py

@@ -0,0 +1,265 @@
+"""Shared AST import resolver for the architecture map (AD-22) and the blast-radius walker (AD-12).
+
+Keeping one resolver means both graphs count edges identically — including relative imports, which a
+naive resolver drops (systematically under-counting in-degree for package-relative codebases). Each
+edge is classified by kind so the blast walker can attach edge-confidence weights.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+# Directories never scanned for the import graph (vcs, envs, caches, build artifacts).
+SKIP_DIRS = {
+    ".pebra", ".venv", ".git", "__pycache__", ".nox", "node_modules", "dist", "build",
+}
+
+# Entrypoint filenames (single shared definition so both walkers agree). __init__.py counts: it runs
+# at import time and re-exports, so changing it is entry-point-like.
+_ENTRYPOINT_NAMES = {"__init__.py", "__main__.py", "main.py"}
+
+
+def is_entrypoint(posix_path: str) -> bool:
+    base = posix_path.rsplit("/", 1)[-1]
+    return base in _ENTRYPOINT_NAMES or base.startswith("handle")
+
+# Edge-confidence weights (Architecture §5 clean-room): how much to trust each import kind as a
+# real dependency edge. Used by the blast walker; not calibrated probabilities.
+EDGE_CONFIDENCE = {"static": 0.85, "relative": 0.75, "wildcard": 0.35, "dynamic": 0.15, "unknown": 0.10}
+
+
+def python_files(root: Path) -> list[str]:
+    """Sorted posix rel-paths of repo Python files, excluding SKIP_DIRS. Shared by both walkers.
+
+    Uses os.walk with ``followlinks=False`` and prunes skipped dirs in-place — this avoids following
+    symlink loops (which rglob can) and skips entire excluded trees instead of filtering per file.
+
+    ``.pyi`` stubs are included so stub-only modules still resolve — but a stub is dropped when its
+    real ``.py`` sibling is present in the same directory (the module shadows its stub), so a module
+    is represented exactly once and its imports aren't double-counted.
+    """
+    out: list[str] = []
+    root_str = str(root)
+    for dirpath, dirnames, filenames in os.walk(root_str, followlinks=False):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        names = set(filenames)
+        for name in filenames:
+            if name.endswith(".py") or (name.endswith(".pyi") and name[:-1] not in names):
+                out.append(Path(dirpath, name).relative_to(root).as_posix())
+    return sorted(out)
+
+
+@dataclass(frozen=True)
+class ImportEdge:
+    kind: str  # static | relative | wildcard | dynamic | external
+    target: str | None  # resolved repo file (posix rel path) or None if outside the repo / unknown
+    name: str | None = None  # the import target as written (e.g. "billing.legacy", ".sub.x"); for
+    # dynamic imports the string-literal argument, or None when it isn't a literal. Used by 3d model
+    # guidance to name WHAT couldn't be resolved; not part of edge identity.
+
+
+def _top_level_names(fileset: set[str]) -> set[str]:
+    """Top-level importable names present in the repo: a package directory's name, or a root-level
+    module's stem. Used to tell an unresolved absolute import that points INTO the repo (a real
+    resolution failure, kind 'static') from one pointing at a stdlib/third-party package (kind
+    'external' — expected to be unresolved and not a sign of an incomplete graph)."""
+    names: set[str] = set()
+    for f in fileset:
+        head, sep, _ = f.partition("/")
+        names.add(head if sep else head.rsplit(".", 1)[0])  # dir name, or root module stem
+    return names
+
+
+def _abs_unresolved_kind(parts: list[str], top_level_names: set[str]) -> str:
+    """Classify an absolute import that did NOT resolve: 'static' (internal failure) if its top-level
+    name belongs to the repo, else 'external' (a library we never expected to resolve)."""
+    return "static" if parts and parts[0] in top_level_names else "external"
+
+
+def _resolve(parts: list[str], fileset: set[str]) -> str | None:
+    # Resolution order: real module, then package, then their .pyi stubs. The .py forms are tried
+    # first so a real module always wins over a stub of the same name. PEP-420 namespace packages
+    # (a bare package dir with no __init__) have no single file target and stay unresolved — the
+    # conservative false-negative direction; their submodules still resolve at the leaf.
+    base = "/".join(parts)
+    for candidate in (f"{base}.py", f"{base}/__init__.py", f"{base}.pyi", f"{base}/__init__.pyi"):
+        if candidate in fileset:
+            return candidate
+    return None
+
+
+def _relative_anchor(file_relpath: str, level: int) -> list[str] | None:
+    """Package parts the relative import is anchored at (level 1 = current package).
+
+    Returns ``None`` when the import reaches above the repo root (more leading dots than there are
+    enclosing packages) — that's unresolvable, distinct from the empty-anchor top-level case where a
+    level-1 relative import legitimately anchors at the repo root.
+    """
+    pkg = file_relpath.split("/")[:-1]  # drop the filename
+    drop = level - 1
+    if drop > len(pkg):
+        return None
+    return pkg[: len(pkg) - drop]
+
+
+def _is_dynamic_call(node: ast.AST) -> bool:
+    if not isinstance(node, ast.Call):
+        return False
+    func = node.func
+    if isinstance(func, ast.Attribute) and func.attr == "import_module":
+        return True
+    return isinstance(func, ast.Name) and func.id == "__import__"
+
+
+def _dynamic_name(node: ast.Call) -> str | None:
+    """The string-literal module passed to importlib.import_module(...) / __import__(...), if any."""
+    if node.args and isinstance(node.args[0], ast.Constant) and isinstance(node.args[0].value, str):
+        return node.args[0].value
+    return None
+
+
+def _from_name(level: int, module: str | None, leaf: str) -> str:
+    """Readable source spec for a `from ... import leaf` (e.g. 'pkg.core', '.sub.x', 'legacy.*')."""
+    return "." * level + ".".join(p for p in (module, leaf) if p)
+
+
+# Specific decorator leaves that mark a framework/test entrypoint even when used bare (@command,
+# @tool, @app.route). These names are distinctive enough that a bare match is safe.
+_ENTRYPOINT_DECORATOR_LEAVES = frozenset({
+    "route", "command", "group", "callback", "tool", "resource", "prompt", "fixture",
+})
+# HTTP-method leaves are common method names, so they only count when QUALIFIED (@router.get, not a
+# bare @get) — this avoids false-positive entrypoints in non-web code that happens to use such names.
+_HTTP_VERB_LEAVES = frozenset({
+    "get", "post", "put", "delete", "patch", "head", "options", "websocket",
+})
+
+
+def _decorator_path(dec: ast.expr) -> list[str]:
+    """Dotted parts of a decorator expression: @app.route('/x') -> ['app', 'route']."""
+    node: ast.AST = dec.func if isinstance(dec, ast.Call) else dec
+    parts: list[str] = []
+    while isinstance(node, ast.Attribute):
+        parts.append(node.attr)
+        node = node.value
+    if isinstance(node, ast.Name):
+        parts.append(node.id)
+    parts.reverse()
+    return parts
+
+
+def _is_entrypoint_decorator(dec: ast.expr) -> bool:
+    path = _decorator_path(dec)
+    if not path:
+        return False
+    leaf = path[-1]
+    if leaf in _ENTRYPOINT_DECORATOR_LEAVES:
+        return True
+    if leaf in _HTTP_VERB_LEAVES and len(path) >= 2:  # @router.get yes, bare @get no
+        return True
+    return "pytest" in path
+
+
+def _tree_is_entrypoint(tree: ast.AST) -> bool:
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.name.startswith("test_"):  # pytest-style test entrypoint
+                return True
+            if any(_is_entrypoint_decorator(d) for d in node.decorator_list):
+                return True
+        elif isinstance(node, ast.ClassDef):
+            if any(_is_entrypoint_decorator(d) for d in node.decorator_list):
+                return True
+    return False
+
+
+def source_is_entrypoint(source: str) -> bool:
+    """Does this source define a framework/test entrypoint (decorator- or test-name-based)?
+    Decorator/name detection only — filename-based entrypoints are handled by ``is_entrypoint``."""
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        return False
+    return _tree_is_entrypoint(tree)
+
+
+def parse_facts(
+    file_relpath: str, source: str, fileset: set[str], top_level_names: set[str]
+) -> tuple[list[ImportEdge], bool, bool]:
+    """One parse per file -> (import edges, is_entrypoint, parse_error).
+
+    Entrypoint = filename-based OR a framework/test decorator. Used by the cache build so each file
+    is parsed exactly once. ``parse_error`` lets the blast evidence distinguish "clean zero edges"
+    from "the changed file could not be inspected."
+    """
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        return [], is_entrypoint(file_relpath), True  # fall back to the filename signal
+    edges = _edges_from_tree(tree, file_relpath, fileset, top_level_names)
+    return edges, is_entrypoint(file_relpath) or _tree_is_entrypoint(tree), False
+
+
+def iter_import_edges(
+    file_relpath: str, source: str, fileset: set[str], top_level_names: set[str] | None = None
+) -> list[ImportEdge]:
+    try:
+        tree = ast.parse(source)
+    except (SyntaxError, ValueError):
+        # unparseable file (syntax error, or null bytes -> ValueError on older Pythons): contribute
+        # no edges, like any other file we can't read. One bad file never fails the whole graph build.
+        return []
+
+    # repo top-level names, for classifying unresolved absolute imports as internal vs external.
+    # Computed once per build by the caller; derived here when called standalone (e.g. unit tests).
+    tl = top_level_names if top_level_names is not None else _top_level_names(fileset)
+    return _edges_from_tree(tree, file_relpath, fileset, tl)
+
+
+def _edges_from_tree(
+    tree: ast.AST, file_relpath: str, fileset: set[str], tl: set[str]
+) -> list[ImportEdge]:
+    edges: list[ImportEdge] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                parts = alias.name.split(".")
+                target = _resolve(parts, fileset)
+                kind = "static" if target is not None else _abs_unresolved_kind(parts, tl)
+                edges.append(ImportEdge(kind, target, name=alias.name))
+        elif isinstance(node, ast.ImportFrom):
+            wildcard = any(a.name == "*" for a in node.names)
+            kind = "wildcard" if wildcard else ("relative" if node.level > 0 else "static")
+            if node.level > 0:
+                anchor = _relative_anchor(file_relpath, node.level)
+                if anchor is None:
+                    # the relative import escapes the repo root: unresolvable, but still a real
+                    # (relative) edge attempt — record it with no target rather than mis-resolving.
+                    leaf = "*" if wildcard else (node.names[0].name if node.names else "")
+                    edges.append(ImportEdge(kind, None, name=_from_name(node.level, node.module, leaf)))
+                    continue
+            else:
+                anchor = []
+            base = anchor + (node.module.split(".") if node.module else [])
+            if wildcard:
+                name = _from_name(node.level, node.module, "*")
+                edges.append(ImportEdge(kind, _resolve(base, fileset) if base else None, name=name))
+            else:
+                # each imported name may itself be a submodule (`from pkg import core` -> pkg/core.py);
+                # try that first, then fall back to the module/package where the name is defined.
+                for alias in node.names:
+                    target = _resolve(base + [alias.name], fileset)
+                    if target is None and base:
+                        target = _resolve(base, fileset)
+                    name = _from_name(node.level, node.module, alias.name)
+                    if target is None and node.level == 0:
+                        # unresolved absolute from-import: internal failure vs external library
+                        edges.append(ImportEdge(_abs_unresolved_kind(base, tl), None, name=name))
+                    else:
+                        edges.append(ImportEdge(kind, target, name=name))
+        elif _is_dynamic_call(node):
+            edges.append(ImportEdge("dynamic", None, name=_dynamic_name(node)))
+    return edges

pebra/adapters/_paths.py

@@ -0,0 +1,41 @@
+"""Repo-relative path safety for adapters that READ caller-supplied file paths (RCA, bandit).
+
+``expected_files`` come from the request/action and could (now, or via a future model/MCP surface)
+contain absolute paths or ``..`` traversal. Any adapter that opens those paths must validate them
+BEFORE reading/copying, so analysis can never touch files outside the repo. Invalid paths are dropped
+(the caller degrades to projected / an evidence gap), never raised.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path, PureWindowsPath
+
+
+def is_safe_relative(repo_root: str, rel: str) -> bool:
+    """The single canonical repo-relative path-safety predicate.
+
+    True iff ``rel`` is a safe repo-relative path under ``repo_root``: rejects the empty path, absolute
+    paths, a drive or ``:``/NTFS-ADS component, any ``..`` component, and paths that resolve (e.g. via a
+    symlink) outside ``repo_root``. Every adapter that reads/writes caller-supplied paths derives from
+    this one predicate so an escape-class fix lands in exactly one place.
+    """
+    if not rel or PureWindowsPath(rel).drive or ":" in rel:
+        return False
+    p = Path(rel)
+    if p.is_absolute() or ".." in p.parts:
+        return False
+    root = Path(repo_root).resolve()
+    try:
+        (root / p).resolve().relative_to(root)
+    except ValueError:
+        return False  # resolves outside the repo (e.g. drive-relative or a symlink escape)
+    return True
+
+
+def safe_relative_files(repo_root: str, files: list[str]) -> list[str]:
+    """Return the subset of ``files`` that are safe repo-relative paths under ``repo_root``.
+
+    The filtering form of ``is_safe_relative``. Order is preserved; the original path strings are
+    returned; invalid paths are dropped (the caller degrades to projected / an evidence gap).
+    """
+    return [rel for rel in files if is_safe_relative(repo_root, rel)]

pebra/adapters/architecture_map.py

@@ -0,0 +1,91 @@
+"""architecture_map (AD-22) — PEBRA's self-built repo structure map (ArchitectureKnowledgeProvider).
+
+Derives structural signals (god-node/anchor, domains, bridge centrality) + a freshness verdict from
+the shared, content-hash-cached import graph (``import_graph_cache``). Freshness is git-agnostic:
+FRESH/REBUILT when the content-hashed graph is up to date, STALE when its (re)build failed, UNKNOWN
+when there is no graph to build (empty/missing repo). current_head is kept only as provenance.
+"""
+
+from __future__ import annotations
+
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Any
+
+from pebra.adapters.import_graph_cache import get_import_graph
+from pebra.core.constants import STAGE_MAP, GraphFreshness
+from pebra.core.models import ArchitectureEvidence
+from pebra.ports.config_port import CriticalityGlob
+
+
+def _domain(posix_path: str) -> str:
+    return posix_path.split("/", 1)[0] if "/" in posix_path else "."
+
+
+class ArchitectureMapAdapter:
+    def __init__(
+        self,
+        criticality_globs: list[CriticalityGlob] | None = None,
+        graph_provider: object | None = None,
+    ) -> None:
+        self._globs = list(criticality_globs or [])
+        self._graph = graph_provider  # optional build-once memo (Slice 5c); else direct get_import_graph
+
+    # --- public port method ---
+
+    def gather_architecture(
+        self, repo_root: str, affected_files: list[str], current_head: str | None
+    ) -> ArchitectureEvidence:
+        root = Path(repo_root)
+        if not root.is_dir():
+            return ArchitectureEvidence(domain_criticality_hint=self._hint(affected_files))
+        # One shared, content-hash-cached import graph (no separate scan). current_head is provenance
+        # only — freshness is decided by per-file content hashes, not HEAD.
+        payload, freshness = self._graph.get(root) if self._graph is not None else get_import_graph(root)
+        if freshness is GraphFreshness.UNKNOWN:  # empty repo / nothing to map
+            return ArchitectureEvidence(domain_criticality_hint=self._hint(affected_files))
+        return self._evidence(payload, affected_files, freshness, current_head)
+
+    # --- evidence assembly ---
+
+    def _evidence(
+        self,
+        m: dict[str, Any],
+        affected_files: list[str],
+        freshness: GraphFreshness,
+        graph_commit: str | None,
+    ) -> ArchitectureEvidence:
+        anchors = set(m.get("anchors", []))
+        god_node_scores: dict[str, float] = m.get("god_node_scores", {})
+        out_degree: dict[str, int] = m.get("out_degree", {})
+        cycle_files = set(m.get("cycle_files", []))
+        entrypoints = set(m.get("entrypoints", []))  # decorator/filename entrypoints (3e)
+        matched_anchors = [f for f in affected_files if f in anchors]
+        # 3f: structural signals are repo-relative percentiles + an in-degree floor (computed in the
+        # cache). god_node_score = max fan-in percentile of the edited files; fan_out = their coupling.
+        god = max((god_node_scores.get(f, 0.0) for f in affected_files), default=0.0)
+        fan_out = max((out_degree.get(f, 0) for f in affected_files), default=0)
+        total_edges = m.get("total_edges", 0)
+        bridge = (m.get("cross_domain_edges", 0) / total_edges) if total_edges else 0.0
+        return ArchitectureEvidence(
+            graph_commit=graph_commit,
+            graph_freshness=freshness,
+            matched_anchors=matched_anchors,
+            matched_domains=sorted({_domain(f) for f in affected_files}),
+            architecture_anchor_score=(len(matched_anchors) / len(anchors)) if anchors else 0.0,
+            god_node_score=god,
+            bridge_centrality=bridge,
+            domain_entrypoint=any(f in entrypoints for f in affected_files),
+            fan_out=fan_out,
+            cycle_participation=any(f in cycle_files for f in affected_files),
+            domain_criticality_hint=self._hint(affected_files),
+            source_files=list(affected_files),
+        )
+
+    def _hint(self, affected_files: list[str]) -> str | None:
+        best: str | None = None
+        for g in self._globs:
+            if any(fnmatch(f, g.pattern) for f in affected_files):
+                if best is None or STAGE_MAP.get(g.stage, 0.0) > STAGE_MAP.get(best, 0.0):
+                    best = g.stage
+        return best

pebra/adapters/ast_diff_adapter.py

@@ -0,0 +1,256 @@
+"""ast_diff_adapter (SymbolDiffProvider, AD-27) — owns Python symbol-diff I/O.
+
+When seeded with a request ``symbol_diff`` evidence slice (a plain dict), it returns that directly.
+Otherwise it computes Python AST-based symbol diff rows for verify/reclassification paths and falls
+back conservatively when source is unavailable or unparseable. It deliberately does NOT hold the whole
+AssessmentRequest — only its own evidence slice, like any adapter config.
+"""
+
+from __future__ import annotations
+
+import ast
+import difflib
+from dataclasses import replace
+from typing import Any
+
+from pebra.adapters.patch_header_adapter import parse_patch_headers
+from pebra.core.models import CandidateAction, SymbolDiffEvidence
+
+_ALLOWED = set(SymbolDiffEvidence.__dataclass_fields__)
+
+# File-op dominance when a patch touches several files: DELETE (symbol loss) > MOVE/RENAME (path
+# migration) > CREATE (no callers). Drives the single file_operation_kind axis.
+_FILE_OP_SEVERITY = {"CREATE": 1, "RENAME": 2, "MOVE": 2, "DELETE": 3}
+
+# Body-only source similarity below this ratio (signature unchanged, body wholly rewritten) flags a
+# suspected identity replacement. Empirically calibrated: a total rewrite scores ~0.45 body-only while
+# a legitimate variable-rename refactor scores ~0.68, so 0.5 separates them. Conservative by design —
+# it may flag very aggressive refactors (extra CONTRACT review), never the reverse. Compares BODY only
+# because the shared `def`/signature line inflates full-source similarity above any useful threshold.
+# Known limitation: for very short bodies (~≤3 lines) shared tokens (return, arg names) keep the ratio
+# above 0.5 even for a total semantic swap, so identity-replacement detection is only effective for
+# functions with 4+ body lines. That is the accepted conservative (false-negative) direction.
+_IDENTITY_REPLACEMENT_THRESHOLD: float = 0.5
+
+
+def _functions(source: str) -> dict[str, ast.AST]:
+    """Map qualified function/method name -> def node. Raises SyntaxError on unparseable source."""
+    tree = ast.parse(source)
+    funcs: dict[str, ast.AST] = {}
+
+    class _V(ast.NodeVisitor):
+        def __init__(self) -> None:
+            self.stack: list[str] = []
+
+        def visit_ClassDef(self, node: ast.ClassDef) -> None:
+            self.stack.append(node.name)
+            self.generic_visit(node)
+            self.stack.pop()
+
+        def _add(self, node: ast.AST, name: str) -> None:
+            qual = ".".join([*self.stack, name])
+            funcs[qual] = node
+
+        def visit_FunctionDef(self, node: ast.FunctionDef) -> None:
+            self._add(node, node.name)
+            self.stack.append(node.name)
+            self.generic_visit(node)
+            self.stack.pop()
+
+        visit_AsyncFunctionDef = visit_FunctionDef  # type: ignore[assignment]
+
+    _V().visit(tree)
+    return funcs
+
+
+_CONTROL_FLOW = (ast.If, ast.For, ast.While, ast.Try, ast.With, ast.AsyncFor, ast.AsyncWith)
+
+
+def _control_flow_count(node: ast.AST) -> int:
+    return sum(isinstance(n, _CONTROL_FLOW) for n in ast.walk(node))
+
+
+def _visibility(qual: str) -> str:
+    leaf = qual.split(".")[-1]
+    return "private" if leaf.startswith("_") else "internal"
+
+
+def _strip_docstring(body: list[ast.stmt]) -> list[ast.stmt]:
+    """Drop a leading docstring statement so it doesn't count as a semantic body change (AD-27:
+    ordinary docstrings are cosmetic)."""
+    if (
+        body
+        and isinstance(body[0], ast.Expr)
+        and isinstance(body[0].value, ast.Constant)
+        and isinstance(body[0].value.value, str)
+    ):
+        return body[1:]
+    return body
+
+
+def _normalized_module_dump(src: str) -> str:
+    """ast.dump of the whole module with docstrings stripped (module + every def/class). Used to
+    detect module/class-level semantic changes (constants, imports, class bases, decorators) that the
+    per-function diff doesn't capture, while ignoring docstring/comment/whitespace-only edits."""
+    tree = ast.parse(src)
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            node.body = _strip_docstring(node.body)
+    return ast.dump(tree)
+
+
+def _has_semantic_module_content(src: str | None) -> bool:
+    if src is None:
+        return False
+    tree = ast.parse(src)
+    tree.body = _strip_docstring(tree.body)
+    return bool(tree.body)
+
+
+def parses(src: str | None) -> bool:
+    """True if the source parses (or is absent). Lets the verifier tell 'cosmetic, no semantic
+    change' (parses, no rows -> COSMETIC) from 'couldn't parse' (-> UNKNOWN)."""
+    if src is None:
+        return True
+    try:
+        ast.parse(src)
+    except SyntaxError:
+        return False
+    return True
+
+
+def _body_source(src: str | None, statements: list[ast.stmt]) -> str:
+    """Concatenated source of a function's body statements (docstring already stripped by caller)."""
+    if not src:
+        return ""
+    parts = [ast.get_source_segment(src, stmt) for stmt in statements]
+    return "\n".join(p for p in parts if p)
+
+
+def _row(symbol_id: str, qual: str, *, signature_changed: bool, body_changed: bool,
+         control_flow_changed: bool, identity_replacement_suspected: bool = False) -> dict[str, Any]:
+    return {
+        "symbol_id": symbol_id,
+        "visibility": _visibility(qual),
+        "signature_changed": signature_changed,
+        "return_shape_changed": False,
+        "body_changed": body_changed,
+        "control_flow_changed": control_flow_changed,
+        "identity_replacement_suspected": identity_replacement_suspected,
+        "external_side_effect_changed": False,
+        "db_write_changed": False,
+        "payment_api_changed": False,
+        "migration_changed": False,
+        "directive_comment_changed": False,
+        "test_only": False,
+        "callers_percentile": 0.0,
+        "transitive_reaches_consequence_symbol": False,
+    }
+
+
+def compute_symbol_diff_rows(
+    before_src: str | None, after_src: str | None, file_path: str
+) -> list[dict[str, Any]]:
+    """Diff two versions of a Python file into per-symbol SymbolDiff rows (for change_classifier).
+
+    Conservative on failure: a syntax error in either version yields no rows (the verifier then
+    treats the file as unclassifiable rather than crashing). Visibility never escalates a plain body
+    edit to CONTRACT — that requires a real signature change.
+    """
+    try:
+        before = _functions(before_src) if before_src else {}
+        after = _functions(after_src) if after_src else {}
+    except SyntaxError:
+        return []
+
+    # NOTE: the Phase-1 body-similarity heuristic (identity_replacement_suspected) IS active and
+    # catches most "same name, wholly different function" cases. What remains deferred is robust
+    # symbol identity / rename tracking: symbols are still matched by qualified name, so a
+    # nested/closure function replaced by a different function of the same qualified name is matched
+    # as "modified" — a narrow residual false-negative. Full identity tracking is a later enrichment.
+    rows: list[dict[str, Any]] = []
+    for qual in sorted(set(before) | set(after)):
+        b = before.get(qual)
+        a = after.get(qual)
+        symbol_id = f"{file_path}::{qual}"
+        if b is not None and a is not None:
+            # signature = parameters AND return annotation (ast args node excludes `returns`)
+            _none = ast.Constant(value=None)
+            sig_changed = ast.dump(b.args) != ast.dump(a.args) or (  # type: ignore[attr-defined]
+                ast.dump(b.returns or _none) != ast.dump(a.returns or _none)  # type: ignore[attr-defined]
+            )
+            # compare bodies with the leading docstring stripped — a docstring-only edit is cosmetic
+            b_stmts = _strip_docstring(b.body)  # type: ignore[attr-defined]
+            a_stmts = _strip_docstring(a.body)  # type: ignore[attr-defined]
+            body_changed = ast.dump(ast.Module(body=b_stmts, type_ignores=[])) != ast.dump(
+                ast.Module(body=a_stmts, type_ignores=[])
+            )
+            cf_changed = _control_flow_count(b) != _control_flow_count(a)
+            # M4: same name + same signature + body wholly rewritten = suspected identity replacement
+            identity_suspected = False
+            if not sig_changed and body_changed:
+                b_body, a_body = _body_source(before_src, b_stmts), _body_source(after_src, a_stmts)
+                if b_body and a_body:
+                    ratio = difflib.SequenceMatcher(None, b_body, a_body).ratio()
+                    identity_suspected = ratio < _IDENTITY_REPLACEMENT_THRESHOLD
+            if sig_changed or body_changed or cf_changed:
+                rows.append(_row(symbol_id, qual, signature_changed=sig_changed,
+                                 body_changed=body_changed, control_flow_changed=cf_changed,
+                                 identity_replacement_suspected=identity_suspected))
+        else:
+            # added or removed symbol: treat as a body change
+            rows.append(_row(symbol_id, qual, signature_changed=False, body_changed=True,
+                             control_flow_changed=False))
+
+    # Module/class-level semantic fallback: if no function row captured the change but the normalized
+    # module AST (docstrings stripped) differs, the edit was outside function bodies — a module
+    # constant, import, class attribute/base, decorator, or one-sided module add/delete. Emit a
+    # module-scope BEHAVIORAL row so it is not mistaken for cosmetic. A docstring/comment/whitespace
+    # only edit leaves the normalized content empty/equal.
+    if not rows:
+        module_changed = False
+        if before_src and after_src:
+            module_changed = _normalized_module_dump(before_src) != _normalized_module_dump(after_src)
+        elif before_src or after_src:
+            module_changed = _has_semantic_module_content(before_src or after_src)
+        if module_changed:
+            rows.append(_row(f"{file_path}::__module__", "__module__", signature_changed=False,
+                             body_changed=True, control_flow_changed=False))
+    return rows
+
+
+class AstDiffAdapter:
+    def __init__(self, symbol_diff_evidence: dict[str, Any] | None = None) -> None:
+        self._evidence = symbol_diff_evidence
+
+    def symbol_diff(self, action: CandidateAction, repo_root: str) -> SymbolDiffEvidence:
+        if self._evidence:
+            base = SymbolDiffEvidence(
+                **{k: v for k, v in self._evidence.items() if k in _ALLOWED}
+            )
+        else:
+            base = SymbolDiffEvidence(
+                parsed_patch_available=False,
+                changed_symbols=list(action.affected_symbols),
+                max_change_kind="UNKNOWN",
+                fallback_reason="no symbol diff supplied; Phase-0 cold-start file/path-level risk",
+            )
+        return _detect_file_operation(base, action)
+
+
+def _detect_file_operation(
+    base: SymbolDiffEvidence, action: CandidateAction
+) -> SymbolDiffEvidence:
+    """Set the FileOperationKind axis from patch headers. Independent of max_change_kind (symbol
+    semantics): a deleted file and a contract change are recorded separately. Supplied evidence that
+    already set a non-NONE op is preserved."""
+    if base.file_operation_kind != "NONE" or not action.proposed_patch:
+        return base
+    ops = parse_patch_headers(action.proposed_patch)
+    if not ops:
+        return base
+    dominant = max(ops, key=lambda o: _FILE_OP_SEVERITY.get(o.kind, 0))
+    paths = tuple(
+        p for o in ops if o.kind == dominant.kind and (p := (o.old_path or o.new_path)) is not None
+    )
+    return replace(base, file_operation_kind=dominant.kind, file_operation_paths=paths)