sourcecode 3.1.1__py3-none-any.whl → 3.2.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__ = "3.1.1"
+__version__ = "3.2.0"

sourcecode/cli.py

@@ -4084,7 +4084,11 @@ def impact_cmd(
       - direct_callers     — classes that directly call or depend on the target
       - indirect_callers   — transitive callers (BFS, bounded by --depth)
       - endpoints_affected — HTTP endpoints that transitively depend on the target
-      - transactional_boundaries_touched — @Transactional classes in the call chain
+      - transactional_boundaries_touched — @Transactional declarations on the target
+                             and on everything that calls it
+      - transactional_boundaries_reaching — the callers-only subset: what would run
+                             this change inside a transaction (the figure
+                             `ask retrieve transactions-reaching` reports)
       - risk_score / risk_level — quantified change risk
 
     \b
@@ -4714,7 +4718,10 @@ def export_cmd(
     ),
     integrations: bool = typer.Option(
         False, "--integrations",
-        help="Detect outbound integrations (HTTP/LDAP/JMS clients) with file:line evidence.",
+        help=(
+            "Detect outbound integrations (HTTP/LDAP/JMS clients) with file:line "
+            "evidence, plus the client libraries the build declares."
+        ),
     ),
     c4: bool = typer.Option(
         False, "--c4",
@@ -4742,6 +4749,11 @@ def export_cmd(
                      rolled up from class-level relation edges.
     --integrations   Outbound integrations (RestTemplate/WebClient/Feign/LDAP/JMS)
                      with file:line evidence — external-system dependency arrows.
+                     Also lists the client libraries the BUILD declares
+                     (declared_clients) and which of those no source construct
+                     uses — a config-wired client has no construct to find, so a
+                     count of 0 is never left standing alone against a client
+                     library named in the stack block.
     --c4             Unified architecture document mapped onto the open C4 model
                      (context/containers/components/code) + an API surface and a
                      per-directory content-hash manifest for incremental consumers.
@@ -4792,9 +4804,12 @@ def export_cmd(
         graph = ir.get("graph", {})
         _ep_data = extract_java_endpoints(root)
         endpoints = _ep_data.get("endpoints", [])
+        from sourcecode.integration_coordinates import declared_integration_coordinates
         _integrations = SemanticIntegrationEngine(
             ContextGraph.build(file_list, root)
-        ).as_report(len(file_list))
+        ).as_report(
+            len(file_list), declared=declared_integration_coordinates(root),
+        )
         data = _build_c4_export(
             root,
             file_list,
@@ -4831,9 +4846,12 @@ def export_cmd(
     if integrations:
         from sourcecode.context_graph import ContextGraph
         from sourcecode.semantic_integration_engine import SemanticIntegrationEngine
+        from sourcecode.integration_coordinates import declared_integration_coordinates
         data["integrations"] = SemanticIntegrationEngine(
             ContextGraph.build(file_list, root)
-        ).as_report(len(file_list))
+        ).as_report(
+            len(file_list), declared=declared_integration_coordinates(root),
+        )
 
     _prog.finish()
     output = _serialize_dict(data, format)
@@ -5684,19 +5702,35 @@ def _render_gate_coverage_section(result: "SpringAuditResult") -> list[str]:  #
     gc = (result.security_posture or {}).get("gate_coverage")
     if not gc:
         return []
-    not_covered = gc.get("not_carrying_gate", 0)
+    not_covered = gc.get("endpoints_not_carrying_gate", gc.get("not_carrying_gate", 0))
     gates = ", ".join(f"`{g}`" for g in gc.get("gate_annotations", [])) or "the detected gate"
-    total = gc.get("total_controller_handlers", 0)
+    # One unit, named: these are endpoints, not handler methods. The two counts differ
+    # (one method can serve several mappings) and must never be summed together.
+    total = gc.get("endpoints_total", gc.get("total_controller_handlers", 0))
     lines: list[str] = ["", "---", ""]
     if not_covered == 0:
-        lines.append(f"✅ **Gate coverage** — all {total} controller handlers carry {gates}.")
+        _gated = gc.get("endpoints_carrying_gate", total)
+        _std = gc.get("endpoints_standard_guarded", 0)
+        if _std:
+            lines.append(
+                f"✅ **Gate coverage** — all {total} endpoints are guarded: {_gated} carry "
+                f"{gates}, {_std} rely on a standard guard."
+            )
+        else:
+            lines.append(f"✅ **Gate coverage** — all {total} endpoints carry {gates}.")
         return lines
 
     covered = gc.get("possibly_filter_covered", 0)
+    _standard = gc.get("endpoints_standard_guarded", 0)
     lines.append(
-        f"🔓 **Gate coverage** — {not_covered} of {total} controller handlers do not carry "
+        f"🔓 **Gate coverage** — {not_covered} of {total} endpoints do not carry "
         f"{gates}."
     )
+    if _standard:
+        lines.append(
+            f"_{gc.get('endpoints_carrying_gate', 0)} carry the gate, {_standard} rely on a "
+            f"standard guard, {not_covered} on neither — the three sum to {total}._"
+        )
     if gc.get("reconstructed_filter_patterns"):
         lines.append(
             f"_{covered} of those match a reconstructed servlet filter pattern "
@@ -6369,6 +6403,16 @@ def migrate_check_cmd(
       ask migrate-check . --output migration.json
       ask migrate-check . --snapshot --ref sprint-12   persist a readiness point
       ask migrate-check . --trend                      days-remaining over time
+      ask migrate-check . --blast-radius               endpoints behind each blocker
+
+    \b
+    Blast radius (--blast-radius):
+      Ranks the affected product files by the HTTP endpoints whose call path runs
+      through them — the re-test plan, ordered by regression scope. Reach is never
+      build breakage: a javax→jakarta finding fails compilation whether or not an
+      endpoint reaches it. A file whose types the IR could not resolve is reported
+      unresolved (reach unknown, never zero), and a repository with no endpoints in
+      the IR gets a null share with the reason stated instead of a 0.0.
 
     \b
     Readiness time series:
@@ -6587,7 +6631,8 @@ def impact_chain_cmd(
       - indirect_callers    — transitive callers (BFS up to --depth hops)
       - endpoints_affected  — HTTP endpoints reachable through the call chain
       - transaction_boundary — @Transactional semantics on the target (if any)
-      - security_surfaces   — per-endpoint security policy + SEC findings
+      - security_surfaces   — per-endpoint security verdict + confidence
+                              (security_posture authority) + declared policy + SEC findings
       - impact_findings     — TX/SEC audit findings touching the call chain
       - risk_level          — critical | high | medium | low
 

sourcecode/detectors/java.py

@@ -15,6 +15,7 @@ from sourcecode.detectors.parsers import (
     substitute_maven_properties as _resolve_maven_property,
     unique_strings,
 )
+from sourcecode.integration_coordinates import coordinates_for_kind
 from sourcecode.schema import FrameworkDetection
 from sourcecode.tree_utils import flatten_file_tree
 
@@ -488,11 +489,15 @@ class JavaDetector(AbstractDetector):
         if "spring-boot-starter-data-jpa" in text or "spring-data-jpa" in text:
             frameworks.append(FrameworkDetection(name="Spring Data JPA", source=source))
         # The Boot starter names neither of the module coordinates, so a Boot app
-        # wiring LDAP the standard way declared no LDAP framework at all.
-        if (
-            "spring-ldap-core" in text
-            or "spring-security-ldap" in text
-            or "spring-boot-starter-data-ldap" in text
+        # wiring LDAP the standard way declared no LDAP framework at all. The coordinate
+        # list lives in `integration_coordinates` — the same set `export --integrations`
+        # reads, so this stack block and that report can never recognize different
+        # libraries for the same external system (ADR-0008 R12).
+        # Only the Spring-family coordinates may carry the "Spring LDAP" label — the
+        # authority also knows non-Spring directory clients, and naming the wrong library
+        # would trade one incoherence for another.
+        if any(
+            c in text for c in coordinates_for_kind("ldap") if c.startswith("spring-")
         ):
             frameworks.append(FrameworkDetection(name="Spring LDAP", source=source))
         if "spring-aspects" in text or "spring-aop" in text:

sourcecode/integration_coordinates.py

@@ -0,0 +1,175 @@
+"""integration_coordinates.py — the declared-client signal for outbound integrations.
+
+THE authority for one question: *which outbound-integration client libraries does this
+repository's build declare?* (ADR-0008 R1). It is a different question from "which client
+constructs does the source contain" — that one belongs to
+:mod:`sourcecode.semantic_integration_engine` — and the two answers only conflict when a
+document reports one and stays silent about the other.
+
+That is exactly what the field reported, twice, two majors apart: `export --integrations`
+answered `count: 0` on a repository whose stack block listed **Spring LDAP**. Reproduced on
+a Boot app that declares `spring-boot-starter-data-ldap` and configures
+`spring.ldap.urls` in YAML: the directory is wired entirely by properties, so no LDAP
+client type is ever imported and the construct scan is *right* to find nothing — but the
+document as a whole then said the system has no outbound integrations while its own stack
+block said it talks to a directory.
+
+A declared coordinate is **evidence of a declared client, never an observed integration**
+(the same discipline that stopped a `org.mybatis` coordinate from being reported as MyBatis
+usage in `detectors/java.py`). This module answers what the build declares; the engine
+answers what the code does; the payload states both and says which is which.
+
+VAI (see `security_posture` §0.5): the table below lists **published open-source artifact
+coordinates** — the identity of a library, matched literally, the same basis as the engine's
+published client-type table. No proprietary, client or convention name appears here, and no
+predicate branches on a repository's own naming.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Optional
+
+# Build-manifest artifact coordinate → the outbound-integration kind it declares.
+# Kinds are exactly the engine's kinds, so declared and observed answers are comparable.
+# Only coordinates whose sole purpose is to talk to an external system are listed: a
+# driver-or-anything coordinate that a repository might carry for unrelated reasons has no
+# place here, because a declaration nobody can act on is noise, not evidence.
+_COORDINATE_KIND: "dict[str, str]" = {
+    # Directory (LDAP)
+    "spring-ldap-core": "ldap",
+    "spring-security-ldap": "ldap",
+    "spring-boot-starter-data-ldap": "ldap",
+    "spring-boot-starter-ldap": "ldap",
+    "unboundid-ldapsdk": "ldap",
+    # Kafka
+    "spring-kafka": "kafka",
+    "kafka-clients": "kafka",
+    "spring-cloud-stream-binder-kafka": "kafka",
+    # RabbitMQ / AMQP
+    "spring-boot-starter-amqp": "rabbitmq",
+    "spring-rabbit": "rabbitmq",
+    "amqp-client": "rabbitmq",
+    # JMS brokers
+    "spring-boot-starter-activemq": "jms",
+    "spring-boot-starter-artemis": "jms",
+    "activemq-client": "jms",
+    "activemq-broker": "jms",
+    "artemis-jms-client": "jms",
+    "spring-jms": "jms",
+    # Redis
+    "spring-boot-starter-data-redis": "redis",
+    "spring-data-redis": "redis",
+    "lettuce-core": "redis",
+    "jedis": "redis",
+    # Elasticsearch
+    "spring-boot-starter-data-elasticsearch": "elasticsearch",
+    "elasticsearch-rest-high-level-client": "elasticsearch",
+    "elasticsearch-java": "elasticsearch",
+    # Mail (SMTP)
+    "spring-boot-starter-mail": "smtp",
+    # Declarative HTTP clients
+    "spring-cloud-starter-openfeign": "http",
+    "feign-core": "http",
+    "okhttp": "http",
+    # SOAP
+    "spring-ws-core": "soap",
+    "spring-boot-starter-web-services": "soap",
+    "cxf-rt-frontend-jaxws": "soap",
+}
+
+# Build manifests scanned. Text-level, like the framework-coordinate scan in
+# `detectors/java.py` — a build file is configuration, not source.
+_MANIFEST_NAMES: frozenset[str] = frozenset({
+    "pom.xml", "build.gradle", "build.gradle.kts",
+})
+
+# Directories that never hold a production build manifest.
+_SKIP_DIRS: frozenset[str] = frozenset({
+    ".git", ".idea", "target", "build", "node_modules", ".sourcecode-cache",
+    ".gradle", "out", "dist",
+})
+
+# A repository with thousands of modules is real (OFBiz, Broadleaf); an unbounded walk is
+# not. The cap is stated in the payload when it bites, never applied silently.
+_MAX_MANIFESTS = 400
+
+_TEST_SCOPE_WINDOW = 4          # lines after a Maven coordinate that may carry its <scope>
+_TEST_SCOPE = re.compile(r"<scope>\s*(test|provided)\s*</scope>", re.IGNORECASE)
+_GRADLE_TEST_CONF = re.compile(r"^\s*(test|androidTest)[A-Za-z]*\s*[(\s'\"]", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class DeclaredClient:
+    """A client library the build declares, with the line that declares it."""
+
+    kind: str
+    coordinate: str
+    evidence: str               # "relpath:line" — same shape as an Integration's evidence
+
+    def to_dict(self) -> dict:
+        return {"kind": self.kind, "coordinate": self.coordinate, "evidence": self.evidence}
+
+
+def coordinates_for_kind(kind: str) -> tuple[str, ...]:
+    """Published coordinates that declare ``kind``. One home for the list, so a consumer
+    that recognizes a library recognizes the same set this authority does."""
+    return tuple(sorted(c for c, k in _COORDINATE_KIND.items() if k == kind))
+
+
+def _manifest_paths(root: Path) -> list[Path]:
+    found: list[Path] = []
+    for name in sorted(_MANIFEST_NAMES):
+        for path in sorted(root.rglob(name)):
+            if len(found) >= _MAX_MANIFESTS:
+                return found
+            if any(part in _SKIP_DIRS for part in path.parts):
+                continue
+            if path.is_file():
+                found.append(path)
+    return found
+
+
+def _is_test_scoped(lines: list[str], idx: int, manifest: str) -> bool:
+    """True when the declaration is a test/provided dependency — a build-time coordinate
+    is not a statement that the running system talks to that external party."""
+    if manifest == "pom.xml":
+        for line in lines[idx: idx + _TEST_SCOPE_WINDOW + 1]:
+            if _TEST_SCOPE.search(line):
+                return True
+        return False
+    return bool(_GRADLE_TEST_CONF.match(lines[idx]))
+
+
+def declared_integration_coordinates(
+    root: Optional[Path], *, manifests: Optional[Iterable[Path]] = None,
+) -> list[DeclaredClient]:
+    """Client libraries the build declares, deterministically ordered, deduplicated by
+    (kind, coordinate). Never raises: an unreadable manifest contributes nothing.
+    """
+    if root is None:
+        return []
+    root = Path(root)
+    paths = list(manifests) if manifests is not None else _manifest_paths(root)
+
+    seen: dict[tuple[str, str], DeclaredClient] = {}
+    for path in paths:
+        try:
+            lines = path.read_text(encoding="utf-8", errors="ignore").splitlines()
+        except OSError:
+            continue
+        try:
+            rel = str(path.relative_to(root)).replace("\\", "/")
+        except ValueError:
+            rel = path.name
+        for idx, line in enumerate(lines):
+            for coordinate, kind in _COORDINATE_KIND.items():
+                if coordinate not in line:
+                    continue
+                if _is_test_scoped(lines, idx, path.name):
+                    continue
+                key = (kind, coordinate)
+                if key not in seen:
+                    seen[key] = DeclaredClient(kind, coordinate, f"{rel}:{idx + 1}")
+    return [seen[k] for k in sorted(seen)]

sourcecode/mcp/registry.py

@@ -781,7 +781,9 @@ Blast-radius analysis: who calls a class and what breaks if it changes? Java onl
 
 Maps to: ask impact <target> <repo_path> [--depth <depth>]
 Returns: direct_callers, indirect_callers, endpoints_affected,
-         transactional_boundaries_touched, risk_score, risk_level, stats.
+         transactional_boundaries_touched (target + callers),
+         transactional_boundaries_reaching (callers only), risk_score,
+         risk_level, stats.
 
 Use this when:
 - Planning a refactor: understand the full call chain before changing a class

sourcecode/mcp/server.py

@@ -890,7 +890,8 @@ def get_impact_chain(repo_path: str = ".", symbol: str = "", depth: int = 4) ->
     Returns: ImpactChainResult with schema_version, symbol, resolution,
              direct_callers, indirect_callers, endpoints_affected,
              transaction_boundary (propagation/isolation/read_only),
-             security_surfaces (per-endpoint policy + finding IDs),
+             security_surfaces (per-endpoint verdict/confidence from the
+             security_posture authority + declared policy + finding IDs),
              impact_findings (TX-001..005 + SEC-001..003 findings in call chain),
              analysis_warnings, risk_level, confidence, metadata.
 
@@ -1320,7 +1321,9 @@ def get_impact_context(repo_path: str = ".", target: str = "", depth: int = 4) -
 
     Maps to: ask impact <target> <repo_path> [--depth <depth>]
     Returns: direct_callers, indirect_callers, endpoints_affected,
-             transactional_boundaries_touched, risk_score, risk_level, stats.
+             transactional_boundaries_touched (target + callers),
+             transactional_boundaries_reaching (callers only), risk_score,
+             risk_level, stats.
 
     Use this when:
     - Planning a refactor: understand the full call chain before changing a class

sourcecode/repository_ir.py

@@ -26,6 +26,10 @@ from typing import Any, Iterable, Optional
 from sourcecode.caller_metrics import CALLER_METRIC_RECONCILIATION
 from sourcecode.endpoint_metrics import ENDPOINT_SURFACE_RECONCILIATION
 from sourcecode.fqn_utils import normalize_owner_fqn as _normalize_owner_fqn
+from sourcecode.spring_semantic import (
+    boundaries_declared_within as _boundaries_declared_within,
+    build_tx_index_from_ir as _build_tx_index_from_ir,
+)
 from sourcecode.path_filters import (
     is_test_path as _is_test_path,
     is_test_fixture_module_path as _is_test_fixture_module_path,
@@ -6803,6 +6807,7 @@ def compute_blast_radius(
             "security_surface_affected": [],
             "cross_module_impact": [],
             "transactional_boundaries_touched": [],
+            "transactional_boundaries_reaching": [],
             "risk_score": 0.0,
             "risk_level": "unknown",
             "confidence_score": 0.0,
@@ -6828,6 +6833,7 @@ def compute_blast_radius(
             "security_surface_affected": [],
             "cross_module_impact": [],
             "transactional_boundaries_touched": [],
+            "transactional_boundaries_reaching": [],
             "risk_score": 0.0,
             "risk_level": "unknown",
             "confidence_score": 0.0,
@@ -7134,23 +7140,19 @@ def compute_blast_radius(
         })
     cross_module_impact = cross_module_impact[:10]
 
-    # ── 7. Transactional boundaries touched ───────────────────────────────────
-    txn_nodes: list[str] = []
-    for node_dict in graph_nodes:
-        fqn = node_dict.get("fqn") or ""
-        role = node_dict.get("role") or ""
-        symbol_kind = node_dict.get("symbol_kind") or ""
-        if role == "transaction_boundary" or "Transactional" in (node_dict.get("canonical_name") or ""):
-            if fqn in affected_classes or _enclosing_class(fqn) in affected_classes:
-                txn_nodes.append(fqn)
-        elif symbol_kind == "method" and fqn in affected_classes:
-            enc = _enclosing_class(fqn)
-            for n2 in graph_nodes:
-                if n2.get("fqn") == enc and n2.get("role") == "transaction_boundary":
-                    txn_nodes.append(fqn)
-                    break
-
-    txn_nodes = sorted(set(txn_nodes))
+    # ── 7. Transactional boundaries ───────────────────────────────────────────
+    # Both figures come from the one transaction-boundary authority (ADR-0008 R1);
+    # they differ only in which symbols are asked about:
+    #   touched   — the target and everything that calls it (what this change sits in)
+    #   reaching  — the callers alone (what would run this change inside a transaction)
+    # This used to be derived here from a graph node `role == "transaction_boundary"`
+    # that no producer ever assigns, so `impact` reported 0 boundaries on repos where
+    # `retrieve transactions-reaching` reported dozens, and `n_txn` never contributed
+    # to the risk score or its escalation rules.
+    _tx_index = _build_tx_index_from_ir(ir)
+    _caller_symbols = set(direct_callers) | set(indirect_callers)
+    txn_nodes = sorted({b.symbol for b in _boundaries_declared_within(_tx_index, affected_classes)})
+    txn_reaching = sorted({b.symbol for b in _boundaries_declared_within(_tx_index, _caller_symbols)})
 
     # ── 8. Risk score ─────────────────────────────────────────────────────────
     n_direct   = len(direct_callers)
@@ -7288,6 +7290,11 @@ def compute_blast_radius(
         "security_surface_affected": security_surface_affected,
         "cross_module_impact": cross_module_impact,
         "transactional_boundaries_touched": txn_nodes,
+        # The callers-only subset: the boundaries that would run this change inside a
+        # transaction. Same authority, narrower question — and the figure
+        # `retrieve transactions-reaching` answers, so the two commands agree by
+        # construction rather than by coincidence.
+        "transactional_boundaries_reaching": txn_reaching,
         "depth_reached": _effective_depth,  # actual BFS depth used, not the requested max
         "bfs_truncated": _bfs_truncated,
         "stats": {
@@ -7297,6 +7304,7 @@ def compute_blast_radius(
             "indirect_callers_sampled": _indirect_sampled,
             "endpoints_affected_count": n_ep,
             "transactional_boundaries_count": n_txn,
+            "transactional_boundaries_reaching_count": len(txn_reaching),
             "mappers_affected_count": n_mappers,
             "modules_affected_count": n_modules,
             "security_surface_count": n_sec,

sourcecode/retrieval/steps_graph.py

@@ -93,16 +93,18 @@ def resolve_execution_paths(step: Step, ctx: "StepContext") -> None:
 # ── transactions reaching (impact chain callers ∩ tx_index) ──────────────────────
 def resolve_transactions_reaching(step: Step, ctx: "StepContext") -> None:
     """The @Transactional boundaries whose enclosing class can reach the target through the
-    call chain. Reuses run_impact_chain (reachability) + the tx boundary index."""
+    call chain. Reuses run_impact_chain (reachability) + the tx boundary index.
+
+    Membership is decided by the one transaction-boundary authority (ADR-0008 R1), the
+    same call `impact` makes for `transactional_boundaries_reaching` — so the two
+    commands answer this question with one number instead of two."""
     assert isinstance(step, ResolveTransactionsReaching)
+    from sourcecode.spring_semantic import boundaries_declared_within
+
     result = _impact_chain(ctx)
-    caller_classes = {_enclosing_class(c) for c in result.direct_callers} | {
-        _enclosing_class(c) for c in result.indirect_callers
-    }
-    boundaries = [
-        b for b in ctx.knowledge.spring_model.tx_index.all_declared
-        if _enclosing_class(b.symbol) in caller_classes
-    ]
+    callers = set(result.direct_callers) | set(result.indirect_callers)
+    caller_classes = {_enclosing_class(c) for c in callers}
+    boundaries = boundaries_declared_within(ctx.knowledge.spring_model.tx_index, callers)
     ctx.put(
         SLOT_ENTITIES,
         [

sourcecode/retrieval/steps_intf.py

@@ -123,7 +123,29 @@ def resolve_integration_inventory(step: Step, ctx: "StepContext") -> None:
         ],
     )
     ctx.put(SLOT_EVIDENCE, [_integration_evidence(i) for i in integrations])
-    ctx.put(SLOT_OBSERVATIONS, _kind_histogram(integrations, key=lambda i: i.kind, label="integration"))
+    observations = _kind_histogram(integrations, key=lambda i: i.kind, label="integration")
+    # A client library the build declares but whose construct nothing imports is not an
+    # entry in this inventory — it is not an observed integration — but leaving it unsaid
+    # is how a `count: 0` came to sit in the same document as a directory client library
+    # in the stack block (ADR-0008 R12). Same coordinate authority `export --integrations`
+    # reads, so both surfaces recognize the same libraries.
+    from sourcecode.integration_coordinates import declared_integration_coordinates
+
+    _declared = declared_integration_coordinates(getattr(ctx.knowledge, "root", None))
+    _observed_kinds = {i.kind for i in integrations}
+    for d in _declared:
+        if d.kind in _observed_kinds:
+            continue
+        observations.append(Observation(
+            name=f"declared_not_observed:{d.kind}",
+            value=d.coordinate,
+            detail=(
+                f"the build declares this client at {d.evidence}; no client construct "
+                "found in source (a properties/YAML/XML-wired client has none) — "
+                "declared, not observed"
+            ),
+        ))
+    ctx.put(SLOT_OBSERVATIONS, observations)
     ctx.put(SLOT_CONFIDENCE, "high" if integrations else "medium")
     _add_service(ctx, "SemanticIntegrationEngine")
 

sourcecode/security_posture.py

@@ -228,14 +228,18 @@ def _collect_usage(
     cir: "CanonicalRepositoryIR",
 ) -> tuple[dict[str, _AnnotationUsage], int, int, set[str]]:
     """Scan existing per-symbol annotations. Returns (usage_by_simple,
-    total_handler_methods, total_non_handler_methods, handler_symbols).
+    handler_declarations, non_handler_declarations, handler_symbols).
 
     Controller-handler methods = the handler symbols of `cir.endpoints`; this is
     the authoritative endpoint surface (already structurally derived by the IR).
+
+    The two integers count **method declarations**, not distinct symbols: overloaded
+    methods share one FQN and are separate annotation sites, so on a real monolith 75
+    distinct handler symbols produced 90 declarations. Coverage below is measured
+    against declarations because that is what was scanned — the payload says so rather
+    than letting a reader assume it was endpoints (3574) or distinct methods (75).
     """
-    handler_symbols: set[str] = {
-        ep.handler_symbol for ep in cir.endpoints if getattr(ep, "handler_symbol", "")
-    }
+    handler_symbols: set[str] = set(_handler_symbols(cir))
     controller_classes: set[str] = {
         ep.controller_class for ep in cir.endpoints if getattr(ep, "controller_class", "")
     }
@@ -389,6 +393,9 @@ def _detect_custom_gates(
     usage, total_handler, total_non_handler, _ = _collect_usage(cir)
     if total_handler == 0:
         return []
+    _population = endpoint_population(cir)
+    population_handler_methods = _population["handler_methods"]
+    population_endpoints = _population["endpoints"]
 
     verdicts: list[Verdict] = []
     for simple, u in sorted(usage.items()):
@@ -415,9 +422,22 @@ def _detect_custom_gates(
             # concrete name lives ONLY here, as evidence (VAI §0.5)
             "annotation": u.token,
             "coverage": round(coverage, 4),
-            "coverage_pct": f"{round(coverage * 100)}% of controller handlers",
+            "coverage_pct": f"{round(coverage * 100)}% of controller handler method declarations",
+            # The denominator is stated in its own unit: handler *methods*, not
+            # endpoints. A repo with 936 handler methods can expose several thousand
+            # endpoints, so this percentage must never be read against an endpoint
+            # count (ADR-0008 — the payload states the unit, the reader does not guess).
+            "denominator": "controller handler method declarations",
             "handler_hits": u.handler_hits,
-            "handler_total": total_handler,
+            # What the percentage was actually measured against: annotation sites on
+            # handler methods. Overloads share an FQN, so this is ≥ the distinct-method
+            # count and unrelated to the endpoint count.
+            "handler_declarations_total": total_handler,
+            # The other two units, stated beside it so no reader has to guess which one
+            # a percentage used — the exact confusion this payload caused in the field.
+            "handler_methods_total": population_handler_methods,
+            "endpoints_total": population_endpoints,
+            "handler_total": total_handler,  # deprecated alias of handler_declarations_total
             "non_handler_hits": u.non_handler_hits,
             "specificity_ratio": (
                 round(handler_rate / non_handler_rate, 2)
@@ -489,6 +509,106 @@ def gate_bearing_handlers(
 _GATE_COVERAGE_LIST_CAP = 200
 
 
+def _handler_symbols(cir: "CanonicalRepositoryIR") -> set[str]:
+    """The distinct handler-method symbols behind the endpoint surface — the one place
+    this set is derived, so a count of it means the same thing everywhere."""
+    return {ep.handler_symbol for ep in cir.endpoints if getattr(ep, "handler_symbol", "")}
+
+
+def endpoint_population(cir: "CanonicalRepositoryIR") -> dict:
+    """THE population every posture partition is measured against (ADR-0008 R1).
+
+    Two units live in this projection and they are not interchangeable: a repository
+    has more *endpoints* than *handler methods*, because one method can answer several
+    mappings. Reporting a count of one next to a count of the other under names that
+    both read as "handlers" is how a payload came to show 698 + 2635 against a total of
+    3574 — three figures, no stated unit, and no way for a reader to tell which
+    denominator any percentage used.
+
+    Every count derived from either population MUST come from here and MUST say which
+    one it is.
+    """
+    return {
+        "endpoints": len(cir.endpoints),
+        "handler_methods": len(_handler_symbols(cir)),
+        "note": (
+            "Two units. 'endpoints' counts mapped routes (the denominator for every "
+            "endpoint partition below); 'handler_methods' counts the distinct methods "
+            "serving them. One method can serve several endpoints — measured on a real "
+            "monolith, 220 endpoints came from 75 methods — so the two never have to "
+            "match, and a figure is only comparable to others in its own unit."
+        ),
+    }
+
+
+def unknown_endpoint_surface(reason: str, declared_policy: str = "") -> dict:
+    """The honest answer for an endpoint this authority cannot speak about.
+
+    Absence of a posture entry is absence of evidence: it is `coverage_unknown`
+    with the reason, never a coverage claim (ADR-0008 R9). The declared per-method
+    policy, if known, travels along as evidence — it is not the answer.
+    """
+    return {
+        "verdict": "coverage_unknown",
+        "confidence": Confidence.UNKNOWN.value,
+        "declared_policy": declared_policy or "unknown",
+        "reason": reason,
+    }
+
+
+def endpoint_security_surface(
+    cir: "CanonicalRepositoryIR",
+    *,
+    root: Optional[Path] = None,
+    posture: Optional[Any] = None,
+) -> dict[str, dict]:
+    """THE per-endpoint security answer, keyed by ``endpoint_id`` (ADR-0008 R1).
+
+    One question — "what is known about the security of this endpoint?" — had two
+    producers: this module's four-way verdict, and `impact-chain`, which printed the
+    raw per-method policy under the name `security_policy`. Measured on Keycloak
+    (2026-07-28): the posture projection called 406 endpoints ``protected_custom``,
+    and **324 of those carry the declared policy ``none_detected``** because their
+    gate is a bespoke annotation with no standard vocabulary. `impact-chain` reported
+    exactly that string for the same `endpoint_id` — so one run of one tool answered
+    "guarded by a custom mechanism (Likely)" and "no security detected" about
+    ``DELETE /admin/realms/{realm}``. The declared policy is a fact about an
+    annotation; it was never an answer about coverage.
+
+    Consumers bind here instead of re-deriving. ``posture`` accepts an already-computed
+    :class:`SecurityPostureResult` or its ``to_dict()`` form, so a caller that has run
+    the security audit reuses that derivation rather than paying for a second one.
+
+    Never raises: any structural gap yields :func:`unknown_endpoint_surface`.
+    """
+    if posture is None:
+        try:
+            posture = infer_security_posture(cir, root=root)
+        except Exception:
+            return {}
+
+    verdicts: Any
+    if isinstance(posture, dict):
+        verdicts = posture.get("endpoints") or []
+    else:
+        verdicts = getattr(posture, "endpoint_verdicts", None) or []
+
+    out: dict[str, dict] = {}
+    for v in verdicts:
+        if not isinstance(v, dict):
+            continue
+        ep_id = v.get("endpoint_id") or ""
+        if not ep_id:
+            continue
+        out[ep_id] = {
+            "verdict": v.get("verdict") or "coverage_unknown",
+            "confidence": v.get("confidence") or Confidence.UNKNOWN.value,
+            # Evidence, not answer: the guard vocabulary declared on the handler.
+            "declared_policy": v.get("policy") or "unknown",
+        }
+    return out
+
+
 @dataclass
 class SecurityPostureResult:
     """Repo-level security-posture projection (P1-A)."""
@@ -499,6 +619,9 @@ class SecurityPostureResult:
     endpoint_verdicts: list[dict] = field(default_factory=list)
     rollup: dict = field(default_factory=dict)
     limitations: list[str] = field(default_factory=list)
+    # The population every partition in this projection is measured against, stated
+    # once so a reader never has to infer a denominator from a percentage.
+    population: dict = field(default_factory=dict)
     # Gate-coverage projection (P1-A follow-up): when a custom gate IS the detected
     # mechanism, which controller handlers do NOT carry it and are not standard-guarded
     # — the residue that relies solely on a centralized filter, if one exists. None when
@@ -522,6 +645,7 @@ class SecurityPostureResult:
                 self.interception.to_dict() if self.interception else None
             ),
             "endpoints": self.endpoint_verdicts,
+            "population": dict(self.population),
             "rollup": self.rollup,
             **({"gate_coverage": self.gate_coverage} if self.gate_coverage else {}),
             "limitations": list(self.limitations),
@@ -552,6 +676,7 @@ def infer_security_posture(
     Never raises; never emits a categorical "unsecured" verdict.
     """
     security_model = str(cir.metadata.get("security_model", "unknown"))
+    population = endpoint_population(cir)
 
     # (0) config: names never drive detection — only upgrade confidence.
     configured: dict[str, Any] = {}
@@ -588,6 +713,11 @@ def infer_security_posture(
     # escape set: handlers that do NOT carry the detected custom gate and have no
     # standard guard of their own — the residue that relies solely on a filter.
     escaping: list[dict] = []
+    # Three-way partition of the SAME population (endpoints), counted in the one loop
+    # that visits every endpoint exactly once, so the parts sum to the whole by
+    # construction rather than by three producers agreeing after the fact.
+    n_gated = 0            # carries the detected custom gate
+    n_standard_only = 0    # no custom gate, but a standard guard of its own
 
     for ep in cir.endpoints:
         policy = ep.security.policy if ep.security is not None else "none_detected"
@@ -640,12 +770,12 @@ def infer_security_posture(
 
         # escape set (only meaningful when a custom gate is the mechanism): a handler
         # that neither carries the gate nor a standard guard nor a config-custom policy.
-        if (
-            has_custom_gate
-            and not carries_gate
-            and policy != "custom"
-            and not _is_standard_guard_policy(policy)
-        ):
+        _gated = carries_gate or policy == "custom"
+        if _gated:
+            n_gated += 1
+        elif _is_standard_guard_policy(policy):
+            n_standard_only += 1
+        if has_custom_gate and not _gated and not _is_standard_guard_policy(policy):
             escaping.append({
                 "endpoint_id": ep.id,
                 "method": ep.method,
@@ -692,13 +822,26 @@ def infer_security_posture(
             else:
                 no_pattern += 1
 
-        total_handlers = len(cir.endpoints)
+        total_handlers = population["endpoints"]
         not_covered = len(escaping)
         _patterns = (
             filter_surface.patterns if filter_surface and not filter_surface.is_empty() else []
         )
         gate_coverage = {
             "gate_annotations": sorted(gate_names),
+            # ── the endpoint partition: three parts, one population, they sum ──────
+            "population": "endpoints",
+            "endpoints_total": population["endpoints"],
+            "endpoints_carrying_gate": n_gated,
+            "endpoints_standard_guarded": n_standard_only,
+            "endpoints_not_carrying_gate": not_covered,
+            # ── a different unit, named as one ────────────────────────────────────
+            "handler_methods_total": population["handler_methods"],
+            "handler_methods_carrying_gate": len(gate_bearers),
+            # ── deprecated aliases (two-minor window) ─────────────────────────────
+            # `total_controller_handlers` always counted endpoints, and `gate_bearing`
+            # counted handler methods, so the two never belonged in one sum. Kept so no
+            # consumer breaks; read the explicit keys above.
             "total_controller_handlers": total_handlers,
             "gate_bearing": len(gate_bearers),
             "not_carrying_gate": not_covered,
@@ -713,12 +856,14 @@ def infer_security_posture(
                 escaping, key=lambda d: (d["path"] or "", d["method"] or "")
             )[:_GATE_COVERAGE_LIST_CAP],
             "note": (
-                "Handlers that do not carry the detected custom gate and have no standard "
-                "guard. 'filter_pattern_match' marks those a declarative servlet filter "
-                "(@WebFilter / web.xml) pattern covers — still review, pattern presence is "
-                "not proof of enforcement. Spring FilterRegistrationBean / HttpSecurity DSL "
-                "/ AspectJ pointcuts are NOT reconstructed, so a missing match is not proof "
-                "of exposure."
+                "Endpoints whose handler does not carry the detected custom gate and has no "
+                "standard guard. 'filter_pattern_match' marks those a declarative servlet "
+                "filter (@WebFilter / web.xml) pattern covers — still review, pattern "
+                "presence is not proof of enforcement. Spring FilterRegistrationBean / "
+                "HttpSecurity DSL / AspectJ pointcuts are NOT reconstructed, so a missing "
+                "match is not proof of exposure. Counts marked endpoints_* partition the "
+                "endpoint population and sum to endpoints_total; handler_methods_* count a "
+                "different unit and are not comparable to them."
             ),
             "truncated": not_covered > _GATE_COVERAGE_LIST_CAP,
         }
@@ -730,6 +875,7 @@ def infer_security_posture(
         endpoint_verdicts=verdicts,
         rollup=rollup,
         limitations=limitations,
+        population=population,
         gate_coverage=gate_coverage,
     )
     # keep reference to suppress-set so callers (SEC-001) can dedupe false alarms

sourcecode/semantic_integration_engine.py

@@ -288,9 +288,23 @@ class SemanticIntegrationEngine:
             "runtime/DI-wired clients remain out of static scope."
         )
 
-    def as_report(self, n_files: Optional[int] = None) -> dict:
+    def as_report(
+        self,
+        n_files: Optional[int] = None,
+        *,
+        declared: "Optional[list]" = None,
+    ) -> dict:
         """Same output contract as integration_detector.detect_integrations, so the
-        `export --integrations` / C4 external_systems consumer is unchanged."""
+        `export --integrations` / C4 external_systems consumer is unchanged.
+
+        ``declared`` — the build's declared client libraries from the coordinate
+        authority (:mod:`sourcecode.integration_coordinates`). They are reported in
+        their own block and never counted as integrations: a coordinate says the build
+        declares a client, not that the code uses one. Passing them is what stops this
+        report from answering `count: 0` in a document whose stack block lists a client
+        library for the same external system (ADR-0008 R12/R14) — a contradiction that
+        survived two releases on the LDAP surface.
+        """
         recs = self.detect()
         by_kind: dict[str, int] = {}
         for r in recs:
@@ -306,11 +320,49 @@ class SemanticIntegrationEngine:
             if r.confidence is not None:
                 rec["confidence"] = r.confidence
             integrations.append(rec)
+
+        declared_list = list(declared or [])
+        observed_kinds = set(by_kind)
+        declared_block = [
+            {**d.to_dict(), "observed_in_source": d.kind in observed_kinds}
+            for d in declared_list
+        ]
+        declared_not_observed = sorted(
+            {d.kind for d in declared_list} - observed_kinds
+        )
+        if declared_not_observed:
+            _cites = "; ".join(
+                f"{d.kind} ({d.coordinate} at {d.evidence})"
+                for d in declared_list if d.kind in set(declared_not_observed)
+            )
+            coverage_reason = (
+                f"{coverage_reason} The build DECLARES a client library for "
+                f"{len(declared_not_observed)} kind(s) with no client construct in "
+                f"source — {_cites}. A configuration-wired client (properties, YAML, "
+                "XML, or a starter's auto-configuration) is not statically visible as a "
+                "construct, so read these as declared-not-observed, neither as an "
+                "integration record nor as their absence."
+            )
+
         return {
             "integrations": integrations,
             "by_kind": {k: by_kind[k] for k in sorted(by_kind)},
             "count": len(recs),
             "confidence": "observed" if recs else "not_analyzed",
+            # Declared ≠ observed. Two facts about the same external system, each under
+            # its own name and its own evidence, so no reader has to reconcile a count of
+            # 0 here against a client library named in the stack block.
+            "declared_clients": declared_block,
+            "declared_clients_count": len(declared_block),
+            "kinds_declared_not_observed": declared_not_observed,
+            "declared_clients_note": (
+                "Client libraries the BUILD declares (Maven/Gradle coordinates, "
+                "test/provided scope excluded). Evidence of a declared client, never of "
+                "an observed integration: a coordinate does not prove the code uses it, "
+                "and its absence from `integrations` does not prove the system does not "
+                "talk to that party — a properties/YAML/XML-wired client has no construct "
+                "to find."
+            ),
             "coverage_confidence": coverage_confidence,
             "coverage_confidence_reason": coverage_reason,
             "coverage_note": (

sourcecode/spring_impact.py

@@ -96,7 +96,13 @@ class AffectedEndpoint:
     controller_class: str
     handler_symbol: str
     source_file: str
-    security_policy: str  # e.g. "spring_pre_authorize", "none_detected", "unknown"
+    # Guard vocabulary DECLARED on the handler ("spring_pre_authorize",
+    # "none_detected", "unknown"). Evidence about an annotation — never a statement
+    # about whether the route is covered. The coverage answer is `security_verdict`,
+    # bound from the one authority (security_posture.endpoint_security_surface).
+    security_policy: str
+    security_verdict: str = "coverage_unknown"
+    security_confidence: str = "Unknown"
 
     def to_dict(self) -> dict:
         return {
@@ -106,6 +112,9 @@ class AffectedEndpoint:
             "controller_class": self.controller_class,
             "handler_symbol": self.handler_symbol,
             "source_file": self.source_file,
+            "security_verdict": self.security_verdict,
+            "security_confidence": self.security_confidence,
+            # kept for consumers reading the declared annotation; see the field note
             "security_policy": self.security_policy,
         }
 
@@ -863,11 +872,43 @@ def _build_chain_explanation(
 # Security surface aggregation
 # ---------------------------------------------------------------------------
 
+def _bind_security_surface(
+    endpoints_affected: list[AffectedEndpoint],
+    surface: dict[str, dict],
+    *,
+    unavailable_reason: str = "",
+) -> None:
+    """Bind each affected endpoint to the one security authority, in place.
+
+    An endpoint the authority does not speak about (or an authority that could not
+    be built) is `coverage_unknown` with its reason — never the declared policy
+    reused as a coverage claim (ADR-0008 R9).
+    """
+    from sourcecode.security_posture import unknown_endpoint_surface
+
+    for ep in endpoints_affected:
+        answer = surface.get(ep.endpoint_id)
+        if answer is None:
+            answer = unknown_endpoint_surface(
+                unavailable_reason
+                or "endpoint is not present in the security-posture projection",
+                declared_policy=ep.security_policy,
+            )
+        ep.security_verdict = answer.get("verdict", "coverage_unknown")
+        ep.security_confidence = answer.get("confidence", "Unknown")
+
+
 def _build_security_surfaces(
     endpoints_affected: list[AffectedEndpoint],
     impact_findings: list[SpringFinding],
 ) -> list[dict]:
-    """Per-endpoint security surface with associated finding IDs."""
+    """Per-endpoint security surface with associated finding IDs.
+
+    The surface reports the authority's verdict (`security_posture`); the declared
+    annotation policy travels with it as evidence. Emitting the declared policy
+    alone is what made this command answer "none_detected" for 324 Keycloak
+    endpoints the same run classified `protected_custom`.
+    """
     finding_by_ep: dict[str, list[str]] = {}
     for f in impact_findings:
         if f.category == "security":
@@ -881,6 +922,11 @@ def _build_security_surfaces(
             "endpoint_id": ep.endpoint_id,
             "method": ep.method,
             "path": ep.path,
+            "verdict": ep.security_verdict,
+            "confidence": ep.security_confidence,
+            "declared_policy": ep.security_policy,
+            # deprecated alias of `declared_policy` (two-minor window): it always
+            # carried the declared annotation, never a coverage verdict.
             "security_policy": ep.security_policy,
             "security_findings": finding_by_ep.get(ep.endpoint_id, []),
         })
@@ -1102,10 +1148,13 @@ class ImpactOrchestrator:
             pass
 
         # ── 5. TX + SEC audit findings, filtered to call chain ────────────
+        # The security audit already derives the posture projection; take it from
+        # there rather than deriving the same answer a second time (ADR-0008 R1).
+        posture_dict: dict = {}
         if prebuilt_findings is not None:
             all_findings = prebuilt_findings
         else:
-            all_findings = _run_audit_for_chain(cir, model, root)
+            all_findings, posture_dict = _run_audit_for_chain(cir, model, root)
 
         impact_findings_raw = _filter_findings(
             all_findings, seed_fqns, direct_callers_raw, indirect_callers_raw,
@@ -1118,6 +1167,18 @@ class ImpactOrchestrator:
         impact_findings = [f.to_dict() for f in impact_findings_raw]
 
         # ── 6. Security surfaces ──────────────────────────────────────────
+        security_surface_index, surface_gap = _endpoint_security_authority(
+            cir, root, posture_dict,
+        )
+        # The gap is only worth a warning when it actually withheld an answer:
+        # a repo with no affected endpoints is not missing a security surface.
+        surface_gap_warned = False
+        if surface_gap and endpoints_affected:
+            warnings.append(surface_gap)
+            surface_gap_warned = True
+        _bind_security_surface(
+            endpoints_affected, security_surface_index, unavailable_reason=surface_gap,
+        )
         security_surfaces = _build_security_surfaces(endpoints_affected, impact_findings_raw)
 
         # ── 7. Risk ───────────────────────────────────────────────────────
@@ -1176,6 +1237,13 @@ class ImpactOrchestrator:
                 key=lambda f: (SEVERITY_ORDER.get(f.severity, 9), f.symbol)
             )
             impact_findings = [f.to_dict() for f in impact_findings_raw]
+            _bind_security_surface(
+                endpoints_affected, security_surface_index,
+                unavailable_reason=surface_gap,
+            )
+            if surface_gap and endpoints_affected and not surface_gap_warned:
+                warnings.append(surface_gap)
+                surface_gap_warned = True
             security_surfaces = _build_security_surfaces(endpoints_affected, impact_findings_raw)
             risk_level, risk_score, risk_score_raw = _compute_risk(
                 len(direct_callers), len(indirect_callers),
@@ -1456,16 +1524,21 @@ def _run_audit_for_chain(
     cir: CanonicalRepositoryIR,
     model: SpringSemanticModel,
     root: Optional[Path],
-) -> list[SpringFinding]:
-    """Run TX + SEC audit and return combined findings list.
+) -> tuple[list[SpringFinding], dict]:
+    """Run TX + SEC audit; return (combined findings, security-posture projection).
+
+    The posture travels out with the findings because the security audit already
+    derives it — the impact chain binds to that derivation instead of computing a
+    second answer to the same question (ADR-0008 R1).
 
     Uses the pre-built model — no duplicate CIR traversal.
-    Never raises; returns [] on any error.
+    Never raises; returns ([], {}) on any error.
     """
     from sourcecode.spring_security_audit import run_security_audit
     from sourcecode.spring_tx_analyzer import run_tx_audit
 
     findings: list[SpringFinding] = []
+    posture: dict = {}
     try:
         tx_result = run_tx_audit(cir, root=root, model=model)
         findings.extend(tx_result.findings)
@@ -1474,9 +1547,53 @@ def _run_audit_for_chain(
     try:
         sec_result = run_security_audit(cir, root=root, model=model)
         findings.extend(sec_result.findings)
+        posture = getattr(sec_result, "security_posture", None) or {}
+    except Exception:
+        pass
+    return findings, posture
+
+
+# Per-CIR memo of the endpoint security authority's answer (one derivation per repo).
+_SURFACE_CACHE_ATTR = "_impact_endpoint_security_surface"
+
+
+def _endpoint_security_authority(
+    cir: CanonicalRepositoryIR,
+    root: Optional[Path],
+    posture: dict,
+) -> tuple[dict[str, dict], str]:
+    """(endpoint_id → security answer, reason it is unavailable).
+
+    Reuses ``posture`` when the audit already produced it; otherwise asks the
+    authority directly (the `prebuilt_findings` path, where no audit ran here).
+    Memoized on the CIR because `pr-impact` issues one query per changed class
+    against the same repository — reuse is what keeps "one authority" from meaning
+    "one full projection per query".
+    """
+    from sourcecode.security_posture import endpoint_security_surface
+
+    cached = getattr(cir, _SURFACE_CACHE_ATTR, None)
+    if cached is not None:
+        return cached
+
+    try:
+        surface = endpoint_security_surface(
+            cir, root=root, posture=posture or None,
+        )
+    except Exception:
+        surface = {}
+    if not surface:
+        answer = ({}, (
+            "security-posture projection unavailable for this repository; every "
+            "endpoint security answer is coverage_unknown (absence of evidence)"
+        ))
+    else:
+        answer = (surface, "")
+    try:
+        setattr(cir, _SURFACE_CACHE_ATTR, answer)
     except Exception:
         pass
-    return findings
+    return answer
 
 
 # ---------------------------------------------------------------------------

sourcecode/spring_semantic.py

@@ -16,7 +16,7 @@ from __future__ import annotations
 import re
 import time
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Iterable, Optional
 
 if TYPE_CHECKING:
     from sourcecode.canonical_ir import CanonicalRepositoryIR
@@ -295,12 +295,24 @@ def build_tx_index(cir: "CanonicalRepositoryIR") -> TransactionBoundaryIndex:
       3. Method-level boundaries override class-level for the same method.
       4. Class-level boundaries are inherited by methods that lack their own.
     """
+    return build_tx_index_from_ir(
+        getattr(cir, "_raw_ir", {}) or {}, repo_id=getattr(cir, "cir_hash", "")[:16]
+    )
+
+
+def build_tx_index_from_ir(raw_ir: dict, repo_id: str = "") -> TransactionBoundaryIndex:
+    """Same index, built straight from a repo IR dict.
+
+    THE authority for "where are the @Transactional boundaries" (ADR-0008 R1).
+    `build_tx_index` is the CanonicalRepositoryIR-shaped entry point; consumers that
+    hold the raw IR dict (blast radius) call this one instead of re-deriving
+    boundaries from graph node roles. Both produce the same index from the same nodes.
+    """
     t0 = time.monotonic()
-    index = TransactionBoundaryIndex(repo_id=getattr(cir, "cir_hash", "")[:16])
+    index = TransactionBoundaryIndex(repo_id=repo_id)
 
     try:
-        raw_ir = getattr(cir, "_raw_ir", {}) or {}
-        graph = raw_ir.get("graph") or {}
+        graph = (raw_ir or {}).get("graph") or {}
         nodes = graph.get("nodes") or []
 
         # Pass 1: build meta-@Transactional map from annotation-type nodes.
@@ -378,3 +390,43 @@ def build_tx_index(cir: "CanonicalRepositoryIR") -> TransactionBoundaryIndex:
 
     index.build_time_ms = round((time.monotonic() - t0) * 1000, 2)
     return index
+
+
+def boundaries_declared_within(
+    index: TransactionBoundaryIndex, symbols: "Iterable[str]"
+) -> list[TransactionBoundary]:
+    """The @Transactional declaration sites carried by *symbols*, ordered by symbol.
+
+    THE authority for "which transaction boundaries belong to this set of symbols"
+    (ADR-0008 R1). Every consumer that reports transaction boundaries over a set of
+    symbols — a blast radius, a caller closure, a module — calls this. A consumer that
+    re-derives the answer from graph node roles, annotation strings or naming is in
+    violation of the ADR, and is how `impact` came to report 0 boundaries where
+    `retrieve transactions-reaching` reported 47 on the same symbol.
+
+    Membership follows Spring's own inheritance, in both directions and no further:
+
+    - the declaration site itself is in the set;
+    - a **class**-level boundary when a method of that class is in the set (the method
+      runs inside it);
+    - a **method**-level boundary when its class is in the set (asking about a class asks
+      about the methods it declares).
+
+    Asking about one method does *not* pull in a sibling method's own boundary — that
+    sibling is a different code path, and reporting it would be the kind of quietly
+    inflated count this authority exists to prevent.
+    """
+    wanted = {s for s in symbols if s}
+    if not wanted:
+        return []
+    declaring_classes = {s.split("#", 1)[0] for s in wanted if "#" in s}
+
+    def _belongs(b: TransactionBoundary) -> bool:
+        if b.symbol in wanted:
+            return True
+        if b.scope == "class":
+            return b.symbol in declaring_classes
+        return _enclosing_class(b.symbol) in wanted
+
+    found = [b for b in index.all_declared if _belongs(b)]
+    return sorted(found, key=lambda b: (b.symbol, b.scope, b.source_file))

{sourcecode-3.1.1.dist-info → sourcecode-3.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 3.1.1
+Version: 3.2.0
 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-3.1.1.dist-info → sourcecode-3.2.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-sourcecode/__init__.py,sha256=gL2tqDxnoKJo0NZ97V-BftlhGDV-Hcty4joUrxJ6XF0,308
+sourcecode/__init__.py,sha256=4hwV87XY8dgmsv4RaWkZzBMSpB_T8EQ4A9_-xB5CzmI,308
 sourcecode/adaptive_scanner.py,sha256=yJBKjNpkY6bpueYJ2YnRezen3sYZDecEt7WaaNWdqug,9466
 sourcecode/archetype.py,sha256=qWMCyL2UzSGXJhCIZj38JjS7wI15EE3eILsWiaoCZXQ,35779
 sourcecode/architectural_baseline.py,sha256=7QzJri4pbL3nzAn9gNutZW6mZR8HHD6H2C2H1EEwYPE,17904
@@ -14,7 +14,7 @@ sourcecode/chain_rules.py,sha256=1kLHv1t7g5rMmycIYSpm3az8SjCr01Xw7LtyV2tNhSA,106
 sourcecode/change_plan.py,sha256=MNgNyu4zrLGvBBaXPwyCh-T2ZGaUQX3Hm4W87uuhZ3w,7750
 sourcecode/cir_graphs.py,sha256=9G0HHj1kw2325IDyzo2OpX73BNswEckecf4MZUXB4JM,12078
 sourcecode/classifier.py,sha256=JBzPwSSrDG-tUHAbcKB678HRbjLpD-ohzbzzO62mgpo,20114
-sourcecode/cli.py,sha256=d6ztendlmJIuXvXqb2uoaJmZnO_nisPmsChdJBgjycU,398039
+sourcecode/cli.py,sha256=F7HXBOhTrzLppk81GDazz6sIvowkZomei1MCRXaTutc,400663
 sourcecode/code_notes_analyzer.py,sha256=EJemNCNc9Dn-1RZYu-aNbK0ELzmsyC4s6FdHi3XyNEI,9392
 sourcecode/compare.py,sha256=jdePg0dNCxFpysiTGMsROL5XABLjy_zVUgVeySvdb0o,7514
 sourcecode/confidence_analyzer.py,sha256=vnbPI-20FnHdjO6STxHW8fbaxmB4A7y58io63ibFZjc,21586
@@ -48,6 +48,7 @@ sourcecode/git_analyzer.py,sha256=irvEwddbd5_tbA_eYUZebf4mH7_nFhpjwaWAV1f7jUY,15
 sourcecode/graph_analyzer.py,sha256=lp0eB1PWC20BYF-GpPhAyegRpKrUKgOmXZIcZSIX_Ks,65777
 sourcecode/graph_evidence.py,sha256=rENNsYRZeNstX_ExNCLlbHJAruFQwxo5d00x6wO3xwI,15030
 sourcecode/hibernate_strat.py,sha256=5GmHiB865HxKdvaxeFV07ojglUgxyOP41AY2xiHfV30,61700
+sourcecode/integration_coordinates.py,sha256=7vGFxN4tCn_KTisYFJuixa8XkyHBoasEFB3fqM62OBI,7407
 sourcecode/jdk_exports.py,sha256=fCrlwNAXUT9gge_joq6kMnY3zJxYB2pxqy-0w3o3MJI,874
 sourcecode/license.py,sha256=keFuwNxdAtvK2Ds91Wl79GMYxuxWYnN5Wbw1qBpaoUI,24896
 sourcecode/mcp_nudge.py,sha256=lKemOqK_wny2u7Ymcr2Idi5Kx8pXY02jCi-_nJYLGMg,2992
@@ -71,26 +72,26 @@ sourcecode/redactor.py,sha256=SB4hwIvg8h-hvcqKcDWaZvA-aSyn-at-BIRwa0tUv5E,3227
 sourcecode/relevance_scorer.py,sha256=0AgEt4KrV73nioMqBgjhGjtY7L2C7L7cSyKtj3IKcrw,9408
 sourcecode/rename_refactor.py,sha256=h6dNFlB9aZ_3q6heeHBkgXQeXaT03nvPSsYH6P8qxFg,12965
 sourcecode/repo_classifier.py,sha256=FG1vaWKdWXsWdl-S8hjVMiTqcwgaRXkDyvK4rPcOGtQ,22681
-sourcecode/repository_ir.py,sha256=ynno-4M3iBWetuKCiZ2rfbe_fd6MibGxf1X3bXF1-18,343766
+sourcecode/repository_ir.py,sha256=2S14aUMY5vpZePObd3F87kz71KUsVXQllurXjufa6A0,344648
 sourcecode/ris.py,sha256=Hw8TakTQ6hku-Abf2k8954NwkrH_sP73_8wVH8x5khc,22079
 sourcecode/runtime_classifier.py,sha256=uTAD6BDCiBLUZEDRfqk718kM4RTT_vAbfkcOI2_Xx58,18432
 sourcecode/scanner.py,sha256=z3CV0rcGunu0Y8mpNgp07wI7nxT0pxw1BkXRRtI0Rpo,9609
 sourcecode/schema.py,sha256=aHNXDf8LGyUC8ZDE_VS9kiskC2-Oswhi_WnpdGy6HDw,24897
 sourcecode/security_config.py,sha256=KblMEoRiEjrIE68YsPaUAFebxFp8UM7MS7lAk5CGD8U,3531
-sourcecode/security_posture.py,sha256=OqVNAnBAQ3ehRDi5_3wcMO3Mwn2MSppLWjGS3GdsyVg,32152
+sourcecode/security_posture.py,sha256=0tKL_RafS0dYY5W__JTeJIfopd8f-DyKEerHrvA3-Mg,40243
 sourcecode/semantic_analyzer.py,sha256=bpgdC6m0_ftVtRf3rSdwhbhWjnZnGxRXaZVcfe4BbcQ,95414
 sourcecode/semantic_impact_engine.py,sha256=t09IirGC3JjQDy33JZd1_WKzQVKXkoNl3-XEUr5kjis,20563
-sourcecode/semantic_integration_engine.py,sha256=TDq8XrFBAjnAXRSZLjHSRLK67U-WLeA_SEECCaLwPEg,16196
+sourcecode/semantic_integration_engine.py,sha256=7a0WqAInOv39f0Yr_94TYo_JP_8QpeI9KGaknpzAyQU,18899
 sourcecode/semantic_services.py,sha256=nbUuPv-F01USTt_9CHT8iy_ucCIw3fz4W3Aquea_pd4,10782
 sourcecode/serializer.py,sha256=BAGL2J3G3bHvJS60OcxekPvTJg8x6b1LzeLKFbGaots,131497
 sourcecode/spring_event_topology.py,sha256=5_ON_21Le5zbG-1GRc5GLIi5HJfy_QjcXLVPC5WeUGQ,18055
 sourcecode/spring_findings.py,sha256=ICcR2qEZgYzWypZzsoaEmVeMYZ0YkuZ8AvTwA-rcVOs,7604
-sourcecode/spring_impact.py,sha256=Y2oUZDCeMZ6-fNYLUviC5DgiJfllE-l0yAZR7IabmxM,75083
+sourcecode/spring_impact.py,sha256=Cm2KZplpQHjdjUC8jPX1SNnLHxOdM3HsUBNFGwgTP18,80145
 sourcecode/spring_model.py,sha256=zOAgFmrRbG4a6KLm1TJl55aWMyPNsz3OS3FSczqPG6A,16594
 sourcecode/spring_profiles.py,sha256=YPgBH3RuML-mtid7YwUMfA9sfSXPZwknYL7UvRMoYbE,7946
 sourcecode/spring_properties.py,sha256=bQSOVrtj7YENsCjMQTTlVh-Gm_K0n0DdWzjPRUP38C4,8394
 sourcecode/spring_security_audit.py,sha256=FteXv5GH-iE07GLEqPpoX7sVXf_dxRns8zxh9_m6By0,23015
-sourcecode/spring_semantic.py,sha256=jteQ1PkY9ArFJv0embg_jBIdbOxqrk9mQ2Xz8OF_FKA,14214
+sourcecode/spring_semantic.py,sha256=UrmLg_4gmBVmMqvSnUMgSReVEERVGv3X7LYDBEs6k_o,16598
 sourcecode/spring_tx_analyzer.py,sha256=lp0h5Pzzd3fPxHAAagMmG8PqR1-v2uVpFIG1o7tCWQs,41148
 sourcecode/summarizer.py,sha256=sr0-tfecFKCr-fSkPPWbl-t9HC7SY2ZxkjnnXX8DB2A,26621
 sourcecode/token_estimate.py,sha256=ZP3C54aQLExuf32Yvrjok2TAS2oSSyNVRA_HjhsD6Eg,7165
@@ -112,7 +113,7 @@ sourcecode/detectors/elixir.py,sha256=jCpvt5Yi6jvplc80ovRtWh17q-11ZGo9qX7o8b57TJ
 sourcecode/detectors/go.py,sha256=2r66uRQfeTWsqxr4HDhT6vExZErby0t46QXLHVBRv9w,2782
 sourcecode/detectors/heuristic.py,sha256=7cRxrip4yIaggYzZJB6ef8yHKh-gHgiH_pXMFcjlyFU,3723
 sourcecode/detectors/hybrid.py,sha256=IGFRUVsAZ1ooRlFdznCeJAV6vy1yVDx-VyghvLtddXc,9101
-sourcecode/detectors/java.py,sha256=M8RZZkryXSDTWDZnmmnuPlZpKX9hnZ7eQy0Rh-eG3_I,44746
+sourcecode/detectors/java.py,sha256=v47yvL4mftcK35cVBpO7gru6O5AcEaKml-OoNyVU0Bg,45246
 sourcecode/detectors/jvm_ext.py,sha256=EgHJ5W8EE-ZTN9V607mVzohyKgZE8Mc2jCi-DF8RAZU,2616
 sourcecode/detectors/nodejs.py,sha256=Hg3Gmr7yIMJFiLoDwOTk2wtu00wxIs6kZf-oQujTFUA,13187
 sourcecode/detectors/parsers.py,sha256=ug9K31tyHqinmv0HkIVQVjdTZpBv67FYKAEf52YXOSM,3178
@@ -126,9 +127,9 @@ sourcecode/detectors/terraform.py,sha256=cxORPR_zVLOJpHlh4e9JnFpkQsn_UnqMMom5yG6
 sourcecode/detectors/tooling.py,sha256=8CKbtxwQoABP-WyBRNmdAmHDOvAH57AR1cF4UKuWEdQ,2074
 sourcecode/mcp/__init__.py,sha256=XU4HfRGbdid8wdUA0x_4f7uKZD1z3mv_XUY_WU_T9Mw,179
 sourcecode/mcp/orchestrator.py,sha256=diVoQgn24QmgPL3Ev8Sp6hsvh02OqY3MktHXOzrlodo,36525
-sourcecode/mcp/registry.py,sha256=OCUCRLPRM176FCw850rF7dNh74f5Zj0h3a9lpxrf8mI,68171
+sourcecode/mcp/registry.py,sha256=1qIcwtl01AGjEM3yMOwYgr_Ck3y-LZeRvh8i70Nhl_w,68258
 sourcecode/mcp/runner.py,sha256=RGimCwhLyHxjCvH7q72y12HWEnATXZLC-NBWhkzlu0I,2852
-sourcecode/mcp/server.py,sha256=P6JqQrlat2jP8OK0ysxSWNwqfUYF-bTc3X05FszR1_4,65180
+sourcecode/mcp/server.py,sha256=GH7bgJRVVkBJf-orj_Zmn_mEqMENG76-KNREJS7E5FY,65354
 sourcecode/mcp/onboarding/__init__.py,sha256=sj2PWqEBmMc4zBNkomg89WtL0M6S7A9yb7_wAuSWNP4,66
 sourcecode/mcp/onboarding/applier.py,sha256=Sx9vHTaXr_M1Bs4uMjO7qa_a2_p4J9oz93oJsKQ7ds4,3298
 sourcecode/mcp/onboarding/backup.py,sha256=ihqGOR8QTX8HASRSEDyfFyXr5bkXrygPHamv4p9KTmk,1452
@@ -147,9 +148,9 @@ sourcecode/retrieval/retriever.py,sha256=YdnbaXaWhFKyShuuE6fj36GfgpuGetqOFzx7_D2
 sourcecode/retrieval/runtime.py,sha256=ODQlPqyS4OfMtCb1oEA_0t7vK0uKPBLhB4K2CnytPUU,10822
 sourcecode/retrieval/steps.py,sha256=wyOiO84fuDgdd-HdugzGSEriN-lN891PTc3gU7lgcmI,9959
 sourcecode/retrieval/steps_endpoint.py,sha256=H_o4YsqgM198ZHtJg-UzhcmnFzbBeaYXrPNIDoc2IjI,13526
-sourcecode/retrieval/steps_graph.py,sha256=epr3V8qGtmFrhDnlk0ZC8eyr5-TDIhY-eiWNB5UJ0Uw,10447
+sourcecode/retrieval/steps_graph.py,sha256=E45vN9pA1lpKQ4pO2JP9-1cwIXoy1hWW6jsBDryeHGM,10684
 sourcecode/retrieval/steps_impact.py,sha256=M0AwU5Ue7nkj-A7DYgQI2BP0BV1b0TFZRrYIydF-Ajw,11605
-sourcecode/retrieval/steps_intf.py,sha256=BAh2oODyzaHpIfLwpAzE_mbG-QGXDSy60dgTROFFbzE,10549
+sourcecode/retrieval/steps_intf.py,sha256=BIopGUhxwutV51r8-1bTCC_VTYENJiHbREF13pB5mSo,11697
 sourcecode/retrieval/steps_struct.py,sha256=jO9L49hziTlS_xhuhCGUavgyAL3ZAnJSOZB-UA4GaRM,13893
 sourcecode/retrieval/steps_txsec.py,sha256=LKRzALzRw_0aQ3_tpbd34mt8u7o690g5tCnp871j7P4,17804
 sourcecode/schemas/envelope-v1.schema.json,sha256=lABkyKqXND039JUY2R6KK47OCDco5mq5PLgkcCXFhOQ,3477
@@ -159,8 +160,8 @@ sourcecode/telemetry/consent.py,sha256=GuhCiA_x2n3LwGBkZnvyIwtFcf5Zwa8O0DdLqkATI
 sourcecode/telemetry/events.py,sha256=4_yeO58U-Cwc1Qb27VB0_EjhmroY0k91n3_VGxeALB8,2776
 sourcecode/telemetry/filters.py,sha256=RzxauTz8HliO4BllQnXEXc7zTeqdCZi5MgqGEDuW7OQ,6570
 sourcecode/telemetry/transport.py,sha256=4gGHsq0WeY9VywEZXA3vUxykfiYnw9uuqfjAAec7F8o,1681
-sourcecode-3.1.1.dist-info/METADATA,sha256=u9yY71cBQ2ZoUpQWoG78kSFzKV7LXTTuEyGIYVd3Ppk,11286
-sourcecode-3.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-3.1.1.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
-sourcecode-3.1.1.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-3.1.1.dist-info/RECORD,,
+sourcecode-3.2.0.dist-info/METADATA,sha256=O9_rjaiou-XB3P9QZsqnkmS1OAKcBCiEsxJOjjN2D9A,11286
+sourcecode-3.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-3.2.0.dist-info/entry_points.txt,sha256=-JEAdChrK5We51kZcb7OaDcyil-dHBjBPL-NhuO-QY8,89
+sourcecode-3.2.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-3.2.0.dist-info/RECORD,,