sourcecode 2.5.20__py3-none-any.whl → 2.6.0__py3-none-any.whl

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.5.20"
+__version__ = "2.6.0"

sourcecode/architectural_baseline.py

@@ -0,0 +1,408 @@
+"""architectural_baseline.py — D5 Architectural knowledge persistence.
+
+Engineering Decision Support, Part B / D5. Turns ASK from a stateless per-run tool
+into one that REMEMBERS a repository's architecture over time. Generalizes the perf
+harness's frozen-schema + same-baseline-diff discipline (`perf-baseline-v1`,
+`docs/perf/baselines/<ver>/`) from timing to architectural metrics: a committed,
+versioned `architectural-baseline-v1` artifact per ref that persists the measured
+structural fingerprint (totals + fan-in hotspots + the full endpoint surface and
+fan-in map needed to diff faithfully).
+
+Three capabilities, one schema:
+  * capture — freeze the current CIR's measured metrics into a baseline artifact.
+  * diff    — diff the live working tree against a stored baseline (this is D1's
+              `diff_metrics` with the base snapshot loaded from disk instead of a
+              second checkout — "D1 auto-diffs against the stored baseline").
+  * trend   — a multi-ref series over N stored baselines (totals over time + per
+              hotspot fan-in trajectory).
+
+Moat line: every field is MEASURED and derived from the CIR alone (via D1's
+`extract_metrics`). Persistence adds no inference, no verdict, no ROI — it stores and
+replays measured facts. Trend reports movement; it never labels a trajectory
+"improving"/"degrading" (that reading is the engineer's).
+
+Determinism & comparability (carried from the perf harness): the metric content of a
+baseline is a pure function of the CIR — same repo state → identical totals/hotspots/
+surface (only `captured_at`/`commit`/env vary). An env fingerprint is recorded so a
+consumer can refuse to compare baselines captured on incomparable hosts, exactly as
+the perf baselines do.
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sourcecode import __version__ as TOOL_VERSION
+from sourcecode.architectural_delta import ArchMetrics, diff_metrics, extract_metrics
+from sourcecode.perf import collect_env
+
+if TYPE_CHECKING:
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+
+# Frozen schema tags — versioned like perf-baseline-v1 / architectural-delta-v1.
+ARCH_BASELINE_SCHEMA: str = "architectural-baseline-v1"
+ARCH_TREND_SCHEMA: str = "architectural-trend-v1"
+# Emitted by `diff_baseline` when the two snapshots are not comparable and the
+# caller did NOT opt into an override — a refusal, not a delta.
+ARCH_NOT_COMPARABLE_SCHEMA: str = "architectural-not-comparable-v1"
+
+# Comparability verdicts.
+COMPARABLE: str = "COMPARABLE"
+NOT_COMPARABLE: str = "NOT_COMPARABLE"
+# `diff_baseline(..., allow_incomparable=True)` still emits a delta but stamps this
+# so the output can never be mistaken for a clean comparison.
+OVERRIDDEN: str = "OVERRIDDEN"
+
+# The axes that make two architectural baselines comparable. Architectural metrics
+# are a PURE FUNCTION OF SOURCE — they do not depend on CPU, cores, or host — so the
+# comparability contract is SEMANTIC, not hardware. Gating on hostname/cpu (as the
+# perf harness must, because timing IS hardware-sensitive) would be theater here and
+# would falsely refuse a valid cross-host architectural diff. What genuinely makes a
+# delta misleading is a change in the measurement itself: the baseline schema, the
+# analysis (tool) version that extracted the metrics, or the underlying IR schema.
+# A difference in any of these means a symbol/endpoint/fan-in delta could reflect the
+# extractor changing rather than the code changing — so ASK refuses.
+_COMPARABILITY_AXES: tuple[tuple[str, str], ...] = (
+    ("schema", "baseline schema"),
+    ("tool_version", "analysis (tool) version"),
+    ("ir_schema_version", "IR schema"),
+)
+
+# How many top fan-in symbols to record as named hotspots. The FULL fan-in map is
+# stored separately for faithful diffs; hotspots are the human-facing projection.
+_HOTSPOT_N: int = 20
+
+
+def _utc_now() -> str:
+    # Microsecond precision (DR-2): whole-second timestamps collided whenever two
+    # baselines were captured in the same second (common in CI / rapid capture), and
+    # the trend sort then tie-broke on the commit STRING — which carries no temporal
+    # order — scrambling the series. Sub-second resolution makes real captures
+    # distinct; lexicographic ISO order stays chronological.
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def git_commit(repo: Path) -> str | None:
+    """Best-effort short commit of `repo`'s HEAD, or None when not a git repo."""
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(repo), "rev-parse", "--short", "HEAD"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    commit = out.stdout.strip()
+    return commit or None
+
+
+def _hotspots(fan_in: dict[str, int], top_n: int) -> list[dict]:
+    """Top-N symbols by fan-in (desc), then FQN asc. Zero-fan-in symbols excluded."""
+    ranked = sorted(
+        ((s, c) for s, c in fan_in.items() if c > 0),
+        key=lambda kv: (-kv[1], kv[0]),
+    )
+    return [{"symbol": s, "fan_in": c} for s, c in ranked[:top_n]]
+
+
+def build_baseline(
+    cir: "CanonicalRepositoryIR",
+    *,
+    ref: str | None = None,
+    commit: str | None = None,
+    hotspot_n: int = _HOTSPOT_N,
+    captured_at: str | None = None,
+    env: dict | None = None,
+    tool_version: str | None = None,
+) -> dict:
+    """Freeze a CIR's measured architectural metrics into a baseline artifact.
+
+    Stores the full endpoint surface and fan-in map (not just hotspots) so a later
+    `diff_baseline` reproduces exactly what a two-checkout D1 delta would report.
+    Records the analysis provenance (`tool_version`, `ir_schema_version`) that the
+    comparability contract gates on — a delta is only trustworthy between baselines
+    that share them."""
+    m = extract_metrics(cir)
+    endpoints = sorted([meth, path] for (meth, path) in m.endpoints)
+    fan_in = dict(sorted(m.fan_in.items()))
+    cycles = sorted((sorted(c) for c in m.cycles), key=lambda mm: (len(mm), mm))
+    return {
+        "schema": ARCH_BASELINE_SCHEMA,
+        "tool_version": tool_version if tool_version is not None else TOOL_VERSION,
+        "ir_schema_version": str(getattr(cir, "schema_version", "")),
+        "ref": ref,
+        "commit": commit,
+        "captured_at": captured_at or _utc_now(),
+        "cir_hash": m.cir_hash,
+        "totals": {
+            "files": m.file_count,
+            "symbols": m.symbol_count,
+            "endpoints": m.endpoint_count,
+            "dependency_edges": m.dependency_edge_count,
+            "import_cycles": len(m.cycles),
+        },
+        "hotspots": _hotspots(m.fan_in, hotspot_n),
+        "endpoint_surface": endpoints,
+        "fan_in": fan_in,
+        "import_cycles": cycles,
+        "env": env if env is not None else collect_env(),
+        "provenance": (
+            "architectural_baseline (D5): a measured structural fingerprint of one "
+            "CIR, persisted per ref. Metric content is a pure function of the repo "
+            "state. No verdict, no ROI — stores and replays measured facts."
+        ),
+    }
+
+
+def _analysis_meta(source: dict) -> dict:
+    """Extract the comparability axes from a baseline (or a synthesized head meta)."""
+    return {axis: source.get(axis) for axis, _ in _COMPARABILITY_AXES}
+
+
+def _head_meta(head_cir: "CanonicalRepositoryIR") -> dict:
+    """The comparability meta for a live head CIR: current tool + its IR schema."""
+    return {
+        "schema": ARCH_BASELINE_SCHEMA,
+        "tool_version": TOOL_VERSION,
+        "ir_schema_version": str(getattr(head_cir, "schema_version", "")),
+    }
+
+
+def comparability(base: dict, head: dict) -> dict:
+    """Verdict on whether two snapshots' metrics are comparable.
+
+    Gates on the SEMANTIC axes only (schema / tool version / IR schema) — see
+    `_COMPARABILITY_AXES` for why hardware is deliberately excluded. Any mismatch
+    yields NOT_COMPARABLE with an itemized reason per differing axis."""
+    reasons: list[dict] = []
+    for axis, label in _COMPARABILITY_AXES:
+        bv, hv = base.get(axis), head.get(axis)
+        if bv != hv:
+            reasons.append({
+                "axis": axis,
+                "base": bv,
+                "head": hv,
+                "detail": f"{label} differs: {bv!r} (base) vs {hv!r} (head)",
+            })
+    return {
+        "status": COMPARABLE if not reasons else NOT_COMPARABLE,
+        "reasons": reasons,
+        "base": _analysis_meta(base),
+        "head": _analysis_meta(head),
+    }
+
+
+def baseline_to_metrics(baseline: dict) -> ArchMetrics:
+    """Reconstruct an `ArchMetrics` from a stored baseline for a faithful D1 diff."""
+    totals = baseline.get("totals", {})
+    endpoints = frozenset(
+        (str(pair[0]).upper(), str(pair[1]))
+        for pair in baseline.get("endpoint_surface", [])
+        if isinstance(pair, (list, tuple)) and len(pair) == 2
+    )
+    return ArchMetrics(
+        cir_hash=str(baseline.get("cir_hash", "")),
+        file_count=int(totals.get("files", 0)),
+        symbol_count=int(totals.get("symbols", 0)),
+        endpoint_count=int(totals.get("endpoints", 0)),
+        dependency_edge_count=int(totals.get("dependency_edges", 0)),
+        endpoints=endpoints,
+        fan_in={str(k): int(v) for k, v in (baseline.get("fan_in") or {}).items()},
+        cycles=frozenset(
+            frozenset(str(m) for m in members)
+            for members in baseline.get("import_cycles", [])
+            if isinstance(members, (list, tuple))
+        ),
+    )
+
+
+def _base_descriptor(baseline: dict) -> dict:
+    """Self-describing block naming the stored baseline the head was diffed against."""
+    return {
+        "ref": baseline.get("ref"),
+        "commit": baseline.get("commit"),
+        "captured_at": baseline.get("captured_at"),
+        "tool_version": baseline.get("tool_version"),
+        "ir_schema_version": baseline.get("ir_schema_version"),
+    }
+
+
+def diff_baseline(
+    baseline: dict,
+    head_cir: "CanonicalRepositoryIR",
+    *,
+    allow_incomparable: bool = False,
+) -> dict:
+    """Diff a live CIR against a stored baseline — D1's delta, base loaded from disk.
+
+    Comparability first: if the base and the live head disagree on the semantic axes
+    (baseline schema / analysis version / IR schema), a delta would conflate the
+    measurement change with the code change. ASK REFUSES by default, returning an
+    `architectural-not-comparable-v1` payload (status NOT_COMPARABLE) instead of a
+    misleading delta — an honest refusal is preferred over a plausible-looking lie.
+
+    Set `allow_incomparable=True` to override: the delta is still computed but stamped
+    `status=OVERRIDDEN` with the reasons, so it can never be read as a clean diff.
+
+    When comparable, the payload is the `architectural-delta-v1` schema (identical to
+    a two-checkout `ask delta`), stamped `status=COMPARABLE`, plus a `base` block."""
+    verdict = comparability(baseline, _head_meta(head_cir))
+
+    if verdict["status"] == NOT_COMPARABLE and not allow_incomparable:
+        return {
+            "schema": ARCH_NOT_COMPARABLE_SCHEMA,
+            "status": NOT_COMPARABLE,
+            "comparability": verdict,
+            "base": _base_descriptor(baseline),
+            "message": (
+                "Refusing to diff: base and head are not comparable "
+                f"({'; '.join(r['detail'] for r in verdict['reasons'])}). "
+                "A delta would conflate the analysis change with the code change. "
+                "Re-capture the base with the current tool (ask baseline capture) for "
+                "a clean diff, or pass --allow-incomparable to override."
+            ),
+            "provenance": (
+                "architectural_baseline (D5): comparability refusal. Architectural "
+                "metrics are a pure function of source; a delta is only trustworthy "
+                "when the baseline schema, analysis version, and IR schema all match."
+            ),
+        }
+
+    base = baseline_to_metrics(baseline)
+    head = extract_metrics(head_cir)
+    delta = diff_metrics(base, head)
+    delta["status"] = (
+        OVERRIDDEN if verdict["status"] == NOT_COMPARABLE else COMPARABLE
+    )
+    delta["comparability"] = verdict
+    delta["base"] = _base_descriptor(baseline)
+    return delta
+
+
+# ── Persistence I/O ───────────────────────────────────────────────────────────
+
+
+def _baseline_filename(baseline: dict) -> str:
+    """Stable filename for a baseline: commit if known, else the capture timestamp."""
+    stem = baseline.get("commit") or baseline.get("captured_at", "baseline")
+    safe = "".join(c if (c.isalnum() or c in "-_.") else "-" for c in str(stem))
+    return f"{safe}.json"
+
+
+def write_baseline(baseline: dict, out_dir: Path) -> Path:
+    """Write `baseline` as deterministic JSON under `out_dir`; return the file path."""
+    out_dir.mkdir(parents=True, exist_ok=True)
+    path = out_dir / _baseline_filename(baseline)
+    path.write_text(
+        json.dumps(baseline, sort_keys=True, indent=2) + "\n", encoding="utf-8"
+    )
+    return path
+
+
+def load_baseline(path: Path) -> dict:
+    """Load and validate one baseline artifact."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or data.get("schema") != ARCH_BASELINE_SCHEMA:
+        raise ValueError(
+            f"{path}: not an {ARCH_BASELINE_SCHEMA} artifact "
+            f"(schema={data.get('schema') if isinstance(data, dict) else type(data).__name__})."
+        )
+    return data
+
+
+def load_baselines_dir(directory: Path) -> list[dict]:
+    """Load every architectural baseline in `directory`, sorted by capture time."""
+    out: list[dict] = []
+    for p in sorted(Path(directory).glob("*.json")):
+        try:
+            out.append(load_baseline(p))
+        except (ValueError, json.JSONDecodeError):
+            continue  # skip foreign JSON; a baseline dir may hold unrelated files
+    # Order by capture time (DR-2). captured_at now carries microsecond resolution,
+    # so real captures are distinct and lexicographic ISO order == chronological.
+    # commit is only a deterministic fallback for the degenerate exact-timestamp tie
+    # (same instant → order is genuinely ambiguous); it never reorders distinct times.
+    out.sort(key=lambda b: (str(b.get("captured_at", "")), str(b.get("commit", ""))))
+    return out
+
+
+# ── Trend (multi-ref series) ──────────────────────────────────────────────────
+
+
+def build_trend(baselines: list[dict]) -> dict:
+    """A multi-ref series over N baselines: totals over time + hotspot fan-in tracks.
+
+    Deterministic projection: points ordered by capture time; hotspot tracks cover
+    the union of every baseline's named hotspots, each track a per-point fan-in
+    series (0 where the symbol is absent). Reports movement only — no trajectory
+    label, no verdict."""
+    points = [
+        {
+            "ref": b.get("ref"),
+            "commit": b.get("commit"),
+            "captured_at": b.get("captured_at"),
+            "tool_version": b.get("tool_version"),
+            "ir_schema_version": b.get("ir_schema_version"),
+            "totals": b.get("totals", {}),
+        }
+        for b in baselines
+    ]
+
+    # Comparability across the SERIES. A trend is not refused — cross-version history
+    # is still worth seeing — but every point-to-point transition that crosses an
+    # analysis-version boundary is flagged, because a metric jump there may be the
+    # extractor changing, not the code. The reader must attribute those with care.
+    boundaries: list[dict] = []
+    for i in range(1, len(baselines)):
+        v = comparability(baselines[i - 1], baselines[i])
+        if v["status"] == NOT_COMPARABLE:
+            boundaries.append({
+                "from_index": i - 1,
+                "to_index": i,
+                "reasons": v["reasons"],
+            })
+    distinct_versions = sorted(
+        {str(b.get("tool_version")) for b in baselines}
+    )
+    series_comparability = {
+        "status": COMPARABLE if not boundaries else NOT_COMPARABLE,
+        "distinct_tool_versions": distinct_versions,
+        "boundaries": boundaries,
+    }
+
+    tracked: set[str] = set()
+    for b in baselines:
+        for h in b.get("hotspots", []):
+            if isinstance(h, dict) and h.get("symbol"):
+                tracked.add(str(h["symbol"]))
+
+    hotspot_trends: list[dict] = []
+    for sym in sorted(tracked):
+        series = [int((b.get("fan_in") or {}).get(sym, 0)) for b in baselines]
+        first, last = series[0], series[-1]
+        hotspot_trends.append({
+            "symbol": sym,
+            "fan_in_series": series,
+            "first": first,
+            "last": last,
+            "delta": last - first,
+        })
+    # Largest absolute movement first, then symbol name — deterministic.
+    hotspot_trends.sort(key=lambda t: (-abs(t["delta"]), t["symbol"]))
+
+    return {
+        "schema": ARCH_TREND_SCHEMA,
+        "baseline_count": len(baselines),
+        "comparability": series_comparability,
+        "points": points,
+        "hotspot_trends": hotspot_trends,
+        "provenance": (
+            "architectural_trend (D5): a measured series over persisted baselines. "
+            "Reports totals and fan-in movement over time; assigns no "
+            "improving/degrading label — the reading is the engineer's. Transitions "
+            "that cross an analysis-version boundary are flagged in comparability: a "
+            "metric jump there may reflect the extractor changing, not the code."
+        ),
+    }

sourcecode/architectural_delta.py

@@ -13,15 +13,19 @@ D2's contract-diff, a distinct axis). A reviewer reads the deltas and decides.
 Determinism: `extract_metrics` reads only the CIR; `diff_metrics` is a pure
 function of two metric snapshots. Same two snapshots → byte-identical delta.
 
-Increment scope (D1-a): counts + HTTP-surface set delta + fan-in shifts. Import
-cycles and blast-radius deltas are deferred to a later increment (heavier compute,
-own metric extractor) — omitted here rather than approximated.
+Increment scope: D1-a delivered counts + HTTP-surface set delta + fan-in shifts.
+D1-b adds import-cycle deltas (cheap Tarjan SCC over the dependency graph, folded into
+the pure `diff_metrics`) and blast-radius deltas (transitive reach, computed in the
+`architectural_delta` wrapper because it needs the reverse graph — scoped to the
+bounded fan-in-shift set so a hub cannot blow up the traversal).
 """
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
+from sourcecode.repository_ir import _all_callers_from_rg
+
 if TYPE_CHECKING:
     from sourcecode.canonical_ir import CanonicalRepositoryIR
 
@@ -32,6 +36,10 @@ ARCH_DELTA_SCHEMA: str = "architectural-delta-v1"
 # fan-in shifts). The counts are always exact; the lists are a bounded sample.
 _LIST_CAP: int = 50
 
+# Safety bound on the transitive-reach traversal so a hub symbol cannot make a
+# blast-radius delta walk the whole graph.
+_REACH_NODE_CAP: int = 4000
+
 # reverse_graph edge types that are NOT a dependency. `contained_in` is pure
 # structural membership (a class "contains" its own methods/ctor) — counting it
 # would make every class report a fan-in equal to its own member count (a
@@ -59,6 +67,74 @@ def _fan_in_map(cir: "CanonicalRepositoryIR") -> dict[str, int]:
     return out
 
 
+def _dependency_cycles(cir: "CanonicalRepositoryIR") -> frozenset[frozenset[str]]:
+    """Import-visible cyclic groups (SCCs of size > 1) in the dependency graph.
+
+    Builds a directed graph from `cir.dependencies` (from → to over import/extends/
+    implements edges) and returns each strongly-connected component with more than
+    one member as a frozenset of FQNs — the classic "import cycle" a reviewer cares
+    about. A self-loop alone is not a cycle here (single-node SCC). Deterministic:
+    iterative Tarjan over a sorted adjacency.
+
+    Scope (DR-3): this counts cycles that are visible through import/extends/implements
+    edges. A cycle formed ONLY by field-type or call edges within a single package —
+    where no `import` is needed — is not represented in `cir.dependencies` and is
+    therefore NOT counted. This is why the CLI names the metric "import cycle": folding
+    field/call edges into the cycle graph is a broader inference, deferred to the
+    capability phase rather than silently widened here."""
+    adjacency: dict[str, set[str]] = {}
+    nodes: set[str] = set()
+    for e in (cir.dependencies or []):
+        u, v = str(e.get("from", "")), str(e.get("to", ""))
+        if not u or not v or u == v:
+            continue
+        adjacency.setdefault(u, set()).add(v)
+        nodes.add(u)
+        nodes.add(v)
+
+    index_of: dict[str, int] = {}
+    low: dict[str, int] = {}
+    on_stack: set[str] = set()
+    stack: list[str] = []
+    counter = 0
+    cycles: list[frozenset[str]] = []
+
+    for root in sorted(nodes):
+        if root in index_of:
+            continue
+        work: list[tuple[str, int]] = [(root, 0)]
+        while work:
+            v, pi = work[-1]
+            if pi == 0:
+                index_of[v] = low[v] = counter
+                counter += 1
+                stack.append(v)
+                on_stack.add(v)
+            succ = sorted(adjacency.get(v, ()))
+            if pi < len(succ):
+                work[-1] = (v, pi + 1)
+                w = succ[pi]
+                if w not in index_of:
+                    work.append((w, 0))
+                elif w in on_stack:
+                    low[v] = min(low[v], index_of[w])
+                continue
+            if low[v] == index_of[v]:
+                members: list[str] = []
+                while True:
+                    w = stack.pop()
+                    on_stack.discard(w)
+                    members.append(w)
+                    if w == v:
+                        break
+                if len(members) > 1:
+                    cycles.append(frozenset(members))
+            work.pop()
+            if work:
+                low[work[-1][0]] = min(low[work[-1][0]], low[v])
+    return frozenset(cycles)
+
+
 @dataclass(frozen=True)
 class ArchMetrics:
     """A deterministic architectural snapshot extracted from one CIR."""
@@ -70,6 +146,7 @@ class ArchMetrics:
     dependency_edge_count: int
     endpoints: frozenset[tuple[str, str]]   # (METHOD, path) — the HTTP contract surface
     fan_in: dict[str, int]                   # symbol FQN → distinct caller count
+    cycles: frozenset[frozenset[str]] = field(default_factory=frozenset)  # import cycles
 
 
 def extract_metrics(cir: "CanonicalRepositoryIR") -> ArchMetrics:
@@ -85,6 +162,7 @@ def extract_metrics(cir: "CanonicalRepositoryIR") -> ArchMetrics:
         dependency_edge_count=len(cir.dependencies or []),
         endpoints=endpoints,
         fan_in=_fan_in_map(cir),
+        cycles=_dependency_cycles(cir),
     )
 
 
@@ -110,6 +188,16 @@ def diff_metrics(base: ArchMetrics, head: ArchMetrics) -> dict:
             shifts.append({"symbol": sym, "base": b, "head": h, "delta": h - b})
     shifts.sort(key=lambda s: (-abs(s["delta"]), s["symbol"]))
 
+    # Import-cycle delta: cycles compared by exact membership. A cycle whose members
+    # changed at all reads as the old one removed + a new one added — the honest,
+    # deterministic choice. Rendered as sorted member lists.
+    added_cycles = sorted(
+        (sorted(c) for c in (head.cycles - base.cycles)), key=lambda m: (len(m), m)
+    )
+    removed_cycles = sorted(
+        (sorted(c) for c in (base.cycles - head.cycles)), key=lambda m: (len(m), m)
+    )
+
     return {
         "schema": ARCH_DELTA_SCHEMA,
         "base_cir_hash": base.cir_hash,
@@ -121,6 +209,7 @@ def diff_metrics(base: ArchMetrics, head: ArchMetrics) -> dict:
             "dependency_edges": _count_block(
                 base.dependency_edge_count, head.dependency_edge_count
             ),
+            "import_cycles": _count_block(len(base.cycles), len(head.cycles)),
         },
         "endpoint_surface": {
             "added_count": len(added),
@@ -132,6 +221,12 @@ def diff_metrics(base: ArchMetrics, head: ArchMetrics) -> dict:
             "changed_count": len(shifts),
             "shifts": shifts[:_LIST_CAP],
         },
+        "import_cycle_shifts": {
+            "added_count": len(added_cycles),
+            "removed_count": len(removed_cycles),
+            "added": added_cycles[:_LIST_CAP],
+            "removed": removed_cycles[:_LIST_CAP],
+        },
         "provenance": (
             "architectural_delta (D1): measured deltas derived from the CIR of two "
             "snapshots. No breaking/non-breaking classification (D2), no verdict, "
@@ -140,8 +235,58 @@ def diff_metrics(base: ArchMetrics, head: ArchMetrics) -> dict:
     }
 
 
+def _transitive_reach(fqn: str, reverse_graph: dict, node_cap: int) -> int:
+    """Size of the transitive reverse-dependency set of `fqn` (its blast radius).
+
+    BFS over the reverse graph via the canonical `_all_callers_from_rg` traversal
+    (containment/imports excluded, DI owners normalized — exactly how blast-radius/
+    impact-chain compute reach), bounded by `node_cap`."""
+    seen: set[str] = {fqn}
+    queue: list[str] = [fqn]
+    while queue and len(seen) < node_cap:
+        cur = queue.pop(0)
+        for dep in _all_callers_from_rg(cur, reverse_graph):
+            if dep not in seen:
+                seen.add(dep)
+                queue.append(dep)
+    return len(seen) - 1  # exclude the seed itself
+
+
+def _blast_radius_shifts(
+    base_cir: "CanonicalRepositoryIR",
+    head_cir: "CanonicalRepositoryIR",
+    seeds: list[str],
+) -> list[dict]:
+    """Transitive blast-radius (reachable-dependent count) change for `seeds`.
+
+    Scoped to the fan-in-shift symbols: those are exactly where reach is most likely
+    to have moved, and bounding to them keeps the traversal cheap (no whole-repo
+    all-pairs closure). A symbol absent on one side has reach 0 there."""
+    b_rg = base_cir.reverse_graph or {}
+    h_rg = head_cir.reverse_graph or {}
+    out: list[dict] = []
+    for sym in seeds:
+        b = _transitive_reach(sym, b_rg, _REACH_NODE_CAP) if sym in b_rg else 0
+        h = _transitive_reach(sym, h_rg, _REACH_NODE_CAP) if sym in h_rg else 0
+        if b != h:
+            out.append({"symbol": sym, "base": b, "head": h, "delta": h - b})
+    out.sort(key=lambda s: (-abs(s["delta"]), s["symbol"]))
+    return out
+
+
 def architectural_delta(
     base_cir: "CanonicalRepositoryIR", head_cir: "CanonicalRepositoryIR"
 ) -> dict:
-    """Convenience: extract both snapshots and diff them."""
-    return diff_metrics(extract_metrics(base_cir), extract_metrics(head_cir))
+    """Convenience: extract both snapshots, diff them, and add blast-radius shifts.
+
+    Blast-radius deltas need the reverse graph (not carried in the pure snapshot), so
+    they are computed here over the fan-in-shift set the pure diff already surfaced."""
+    payload = diff_metrics(extract_metrics(base_cir), extract_metrics(head_cir))
+    seeds = [s["symbol"] for s in payload["fan_in_shifts"]["shifts"]]
+    shifts = _blast_radius_shifts(base_cir, head_cir, seeds)
+    payload["blast_radius_shifts"] = {
+        "scope": "fan_in_shift_symbols",
+        "changed_count": len(shifts),
+        "shifts": shifts[:_LIST_CAP],
+    }
+    return payload