sourcecode 2.5.20__tar.gz → 2.6.1__tar.gz

{sourcecode-2.5.20 → sourcecode-2.6.1}/CHANGELOG.md

@@ -1,5 +1,111 @@
 # Changelog
 
+## [2.6.1] — 2026-07-22
+
+**Stability patch — extraction/label fidelity on the 2.6.x line. No new
+capability, no functional-contract change.** Two isolated corrections where the
+system produced a correct result but described it imperfectly (P1-H) or gave a
+provably-correct answer a misleading label (SIM-4). `2.6.0` remains the stable
+baseline; this is a fidelity patch on top of it. Full suite: **3637 passed, 5
+skipped, 1 deselected** (the deselected chunker test is a pre-existing external
+fixture flake).
+
+### Fixed
+
+- **P1-H — lowercase-initial type declarations were silently dropped.**
+  `_CLASS_DECL_RE` assumed the PascalCase convention (`[A-Z]\w*`) for the
+  type-name start, so valid lowercase-initial Java types never entered the
+  symbol graph (e.g. `iFieldMetadata`, `i18nUpdateCartServiceExtensionHandler`;
+  JNA C-struct mirrors `passwd`/`group`/`pam_*`). The same assumption was
+  duplicated in the multi-line-join gate, so a lowercase declaration whose brace
+  sat on a continuation line stayed lost even after widening the primary regex.
+  Both name-start charsets widened to `[A-Za-z]\w*`, and a length-preserving
+  string-literal blanking guard was added at the declaration-scan sites so a
+  `class`/`interface` keyword appearing inside a string literal (e.g. a log
+  message `"... advice class for {} ..."`) can no longer mint a phantom type.
+  Fleet A/B over six real repositories: +9 real types recovered, zero phantoms,
+  zero symbols lost, control repositories byte-stable.
+- **SIM-4 — a method-precise resolution was labelled `class_expanded`.** When a
+  `Class#method` query matched one class by short/suffix name and its method
+  resolved to exactly one method node, `impact-chain` returned the correct
+  method-scoped result but tagged it `class_expanded` — signalling "I broadened
+  your query to the whole class" over a narrow, correct answer. A distinct
+  resolution value `method_resolved` now describes that case (confidence stays
+  high; nothing was widened); the genuine no-method class-expansion case keeps
+  `class_expanded`. No behavioural change — the resolved symbol set, confidence,
+  and callers are identical; only the exposed label changed to match reality.
+
+## [2.6.0] — 2026-07-22
+
+**Engineering Decision Support — Part B (capability milestone) lands, plus the
+DR-1..DR-7 signature-cleanliness family and the P1 validation-confidence
+projection.** Built directly on 2.5.20 (Part A / F1–F3). Everything here is a
+deterministic projection of evidence ASK already computes — no ROI, no verdicts,
+no business judgement. Full suite: **3631 passed, 5 skipped**. The ContextGraph
+baseline oracle was regenerated for this release (it was ~3 weeks stale,
+predating Part A); the fleet drift is additive and fully explained — every one
+of the 99 cells captures `ok`, no errors, endpoint sets preserved, only additive
+keys.
+
+### Added — Part B decision support (deterministic, agent-owned choice stays out)
+
+- **D1 — `delta` architectural before/after.** Builds IR for two refs and diffs
+  the existing structural metrics (Δ fan-in, Δ coupling, Δ import-cycles, Δ
+  blast-radius, Δ public-API surface). Import-cycle deltas and blast-radius
+  shifts included (D1-b).
+- **D2 — `contract-diff` public-contract break detection.** Classifies each
+  change `breaking | additive | non_breaking` over a stable public-contract
+  projection (endpoints + public signatures + validation constraints);
+  `non_breaking` is filled from proven constraint loosening (D2-b). No
+  behavioural-equivalence claim — structural contract deltas only.
+- **D3 — `plan` change-plan artifact.** Affected set (reverse graph), covering
+  tests, rollback surface, validation checklist. No generated code, no
+  step-by-step sequence beyond dependency ordering.
+- **D4 — `compare` candidate ranking by measured architectural cost.** Per-candidate
+  cost vector (endpoints touched, blast-radius, coupling delta, tests at risk).
+  No ROI / "best choice" field — that judgement is the engineer's / agent's.
+- **D5 — `baseline` architectural knowledge persistence.** Capture / diff / trend
+  a versioned architectural baseline per ref, mirroring the perf-harness
+  frozen-schema + same-baseline-diff discipline; comparability contract emits
+  `NOT_COMPARABLE` rather than a misleading delta (D5-b).
+- **P1 — single-repo validation-confidence block.** An Explainability projection
+  of the existing `Confidence` / `fp_causes` / `zero_result_reason` evidence into
+  a human-readable confidence block. Projection only, no new inference.
+
+### Fixed — DR-1..DR-7 parameter-signature correctness (IR extractor)
+
+Annotated-parameter method signatures were corrupted in several ways, all of
+which fed `signature` / `param_types` (and therefore `contract-diff` trust):
+
+- **DR-1 — paren-balanced parameter extraction.** A parameter annotation with
+  parenthesised args (`@PathVariable(name=…, required=…)`) truncated the naive
+  first-`)` scan, so any add/remove/retype of a parameter read as UNCHANGED.
+  Now uses a paren- and string-literal-aware `_closing_paren_index` on both the
+  method and constructor paths.
+- **DR-2 — sub-second baseline capture timestamps** so `baseline trend` orders by
+  time instead of tie-breaking on a meaningless commit string.
+- **DR-3 — import-cycle metric docstring** scoped honestly to import-visible
+  cycles (the function was over-promising cross-edge coverage).
+- **DR-4 — annotate the two distinct body-endpoint axes** (`summary` vs
+  `validation_pattern`) with a `scope_note` so the two counts read coherently.
+- **DR-5 — strip `//` line-comments (string-literal-aware) before the multi-line
+  parameter-list join**, so a commented token cannot leak into a signature.
+- **DR-6 — strip `final` + parameter annotations to a fixpoint.** `final @Ann Type`
+  kept its annotation because the anchored `^@` strip ran before the unanchored
+  `final` strip; the two now alternate until stable, regardless of order.
+- **DR-7 — string-literal-aware annotation-argument strip.** An annotation whose
+  quoted value contains parens (`@Description("a URL (http/ftp).")`) leaked its
+  tail into the type; the `\([^)]*\)` regex is replaced by
+  `_strip_param_annotations`, consuming each `@Name(...)` with the DR-1
+  paren-balanced discipline.
+
+### Changed
+
+- Version `2.5.20` → `2.6.0` (new command surface: `delta`, `contract-diff`,
+  `plan`, `compare`, `baseline`).
+- ContextGraph baseline oracle (`tests/contextgraph_baseline/baseline/index.json`)
+  regenerated against this release (99 cells, all `ok`).
+
 ## [2.5.20] — 2026-07-21
 
 **Engineering Decision Support — Part A, F3: JAX-RS composed-path canonicalization.**

{sourcecode-2.5.20 → sourcecode-2.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 2.5.20
+Version: 2.6.1
 Summary: Persistent structural context and ultra-fast repeated analysis for AI coding agents
 License-File: LICENSE
 Keywords: agents,ai,codebase,context,developer-tools,llm

{sourcecode-2.5.20 → sourcecode-2.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "2.5.20"
+version = "2.6.1"
 description = "Persistent structural context and ultra-fast repeated analysis for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-2.5.20 → sourcecode-2.6.1}/src/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.1"

sourcecode-2.6.1/src/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."
+        ),
+    }