sourcecode 3.1.0__py3-none-any.whl → 3.2.0__py3-none-any.whl

sourcecode/migration_blast.py

@@ -0,0 +1,232 @@
+"""Migration blast radius — which request surface a migration finding sits under.
+
+`migrate-check` answers *what must change*: the files whose `javax.*` imports, XML
+descriptors and build coordinates block a Spring Boot 2→3 upgrade. It does not answer
+*what has to be re-tested when that change lands*, which is the question a migration
+plan is actually built around.
+
+This module answers it as a rule over the existing IR — no new detector, no second
+traversal engine. Each affected file resolves to the types it declares, those types are
+run through the same caller BFS `impact-chain` uses (`spring_impact._bfs_callers` +
+`_collect_endpoints`), and the reachable HTTP endpoints become that file's re-test set.
+
+Honesty contract:
+  * A `javax→jakarta` finding breaks compilation whether or not an endpoint reaches it.
+    `endpoints_reached` ranks *regression scope*, never "what fails to build".
+  * A file whose declared types the IR never resolved is reported in `files_unresolved`
+    with reach `unknown` — never folded into the zero-reach bucket.
+  * A repository the IR sees no endpoints in gets `request_surface_share: null` and a
+    note saying ranking fell back to caller counts, never a manufactured 0.0.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from sourcecode.spring_impact import _bfs_callers, _collect_endpoints
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from sourcecode.canonical_ir import CanonicalRepositoryIR
+    from sourcecode.migrate_check import MigrationFinding
+    from sourcecode.spring_model import SpringSemanticModel
+
+SCHEMA_VERSION = "1.0"
+
+DEFAULT_DEPTH = 4
+DEFAULT_TOP_N = 25
+_ENDPOINTS_PER_FILE = 10
+
+_SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+_TYPE_KINDS = ("class", "interface", "enum", "annotation")
+
+_REACH_NOTE = (
+    "endpoints_reached ranks REGRESSION SCOPE — the requests whose call path runs "
+    "through the file — not what fails to build. A javax→jakarta finding breaks "
+    "compilation whether or not any endpoint reaches it."
+)
+
+
+def _types_by_file(cir: "CanonicalRepositoryIR") -> dict[str, list[str]]:
+    """Map source file → the type FQNs declared in it, from the IR's graph nodes."""
+    raw = getattr(cir, "_raw_ir", None) or {}
+    nodes = (raw.get("graph") or {}).get("nodes") or []
+    out: dict[str, list[str]] = {}
+    for node in nodes:
+        if not isinstance(node, dict):
+            continue
+        src = node.get("source_file") or ""
+        fqn = node.get("fqn") or ""
+        if not src or not fqn or "#" in fqn:
+            continue
+        if (node.get("symbol_kind") or node.get("type")) not in _TYPE_KINDS:
+            continue
+        out.setdefault(src, []).append(fqn)
+    for src in out:
+        out[src] = sorted(set(out[src]))
+    return out
+
+
+def _max_severity(findings: list["MigrationFinding"]) -> str:
+    return min(
+        (f.severity for f in findings),
+        key=lambda s: _SEVERITY_ORDER.get(s, 3),
+        default="low",
+    )
+
+
+def compute_migration_blast(
+    cir: "CanonicalRepositoryIR",
+    model: "SpringSemanticModel",
+    findings: list["MigrationFinding"],
+    *,
+    depth: int = DEFAULT_DEPTH,
+    top_n: int = DEFAULT_TOP_N,
+) -> dict:
+    """Resolve the request surface behind each migration finding.
+
+    Args:
+        cir:      CanonicalRepositoryIR for the same repository that was scanned.
+        model:    SpringSemanticModel built from that CIR (endpoint index).
+        findings: MigrationFinding list from `run_migrate_check`.
+        depth:    Caller BFS depth, the same knob `impact-chain --depth` exposes.
+        top_n:    Files retained in `files`; the rest are counted in `files_omitted`.
+
+    Returns a JSON-serializable dict. Never raises on a partial IR: anything it
+    could not resolve is reported as unresolved rather than dropped.
+    """
+    by_file: dict[str, list["MigrationFinding"]] = {}
+    non_source = 0
+    non_product = 0
+    for f in findings:
+        src = getattr(f, "source_file", "") or ""
+        if not src.endswith(".java"):
+            # XML descriptors and build coordinates carry no type the call graph
+            # can reach; they are counted, never ranked.
+            non_source += 1
+            continue
+        if getattr(f, "code_context", "main") != "main":
+            # Test and generated sources are outside the product blast radius, the
+            # same boundary blocking_count draws.
+            non_product += 1
+            continue
+        by_file.setdefault(src, []).append(f)
+
+    declared = _types_by_file(cir)
+    impl_graph = getattr(cir, "implementation_graph", None)
+    reverse_graph = getattr(cir, "reverse_graph", None) or {}
+    endpoints_in_repo = len(getattr(cir, "endpoints", None) or [])
+
+    rows: list[dict[str, Any]] = []
+    unresolved: list[str] = []
+    reached_ids: set[str] = set()
+
+    for src in sorted(by_file):
+        seeds = declared.get(src) or []
+        if not seeds:
+            unresolved.append(src)
+            continue
+        direct, indirect, truncated, *_rest = _bfs_callers(
+            seeds, reverse_graph, depth, impl_graph=impl_graph,
+        )
+        endpoints = _collect_endpoints(list(direct) + list(indirect), seeds, model)
+        for ep in endpoints:
+            reached_ids.add(ep.endpoint_id)
+        file_findings = by_file[src]
+        shown = sorted(
+            (e.to_dict() for e in endpoints),
+            key=lambda e: (e["path"], e["method"], e["endpoint_id"]),
+        )
+        rows.append({
+            "file": src,
+            "max_severity": _max_severity(file_findings),
+            "finding_count": len(file_findings),
+            "rule_ids": sorted({f.rule_id for f in file_findings}),
+            "types": seeds,
+            "direct_callers": len(direct),
+            "indirect_callers": len(indirect),
+            "traversal_truncated": bool(truncated),
+            "endpoints_reached": len(endpoints),
+            "endpoints": shown[:_ENDPOINTS_PER_FILE],
+            "endpoints_omitted": max(0, len(shown) - _ENDPOINTS_PER_FILE),
+        })
+
+    rows.sort(key=lambda r: (
+        -r["endpoints_reached"],
+        -(r["direct_callers"] + r["indirect_callers"]),
+        _SEVERITY_ORDER.get(r["max_severity"], 3),
+        r["file"],
+    ))
+
+    on_path = sum(1 for r in rows if r["endpoints_reached"] > 0)
+    notes: list[str] = [_REACH_NOTE]
+    if endpoints_in_repo:
+        share = round(len(reached_ids) / endpoints_in_repo, 4)
+    else:
+        share = None
+        notes.append(
+            "The IR resolved no HTTP endpoints in this repository, so no request "
+            "surface can be attributed — files are ranked by caller count alone."
+        )
+    if unresolved:
+        notes.append(
+            f"{len(unresolved)} file(s) carry a finding but declare no type the IR "
+            "resolved (parse gap or non-type source); their reach is unknown, not zero."
+        )
+    if any(r["traversal_truncated"] for r in rows):
+        notes.append(
+            "At least one traversal hit the hub-class guard and was capped — those "
+            "files' reach is a lower bound."
+        )
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "depth": depth,
+        "endpoints_in_repo": endpoints_in_repo,
+        "endpoints_reached": len(reached_ids),
+        "request_surface_share": share,
+        "files_analyzed": len(rows),
+        "files_on_request_path": on_path,
+        "files_off_request_path": len(rows) - on_path,
+        "files_unresolved": sorted(unresolved),
+        "findings_not_source": non_source,
+        "findings_not_product": non_product,
+        "files": rows[:top_n],
+        "files_omitted": max(0, len(rows) - top_n),
+        "notes": notes,
+    }
+
+
+def render_blast_text(blast: Optional[dict], *, top_n: int = 10) -> str:
+    """Render the blast-radius block as the text-format section."""
+    if not blast:
+        return ""
+    lines: list[str] = ["Migration blast radius (regression scope)"]
+    share = blast.get("request_surface_share")
+    if share is None:
+        lines.append(
+            f"  {blast.get('endpoints_in_repo', 0)} endpoints in IR — "
+            "no request surface attributable; ranked by callers."
+        )
+    else:
+        lines.append(
+            f"  {blast.get('endpoints_reached', 0)}/{blast.get('endpoints_in_repo', 0)} "
+            f"endpoints reached ({share * 100:.1f}% of the request surface)"
+        )
+    lines.append(
+        f"  Files on a request path: {blast.get('files_on_request_path', 0)}"
+        f" of {blast.get('files_analyzed', 0)} analyzed"
+        + (f"   [{len(blast.get('files_unresolved') or [])} unresolved]"
+           if blast.get("files_unresolved") else "")
+    )
+    for row in (blast.get("files") or [])[:top_n]:
+        lines.append(
+            f"  {row['endpoints_reached']:>4} endpoints  "
+            f"[{row['max_severity'].upper()}] {row['file']}  "
+            f"({row['direct_callers']}+{row['indirect_callers']} callers)"
+        )
+    omitted = blast.get("files_omitted", 0) + max(0, len(blast.get("files") or []) - top_n)
+    if omitted:
+        lines.append(f"  +{omitted} more file(s)")
+    for note in blast.get("notes") or []:
+        lines.append(f"  note: {note}")
+    return "\n".join(lines)

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