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

sourcecode/confidence_analyzer.py

@@ -315,12 +315,16 @@ class ConfidenceAnalyzer:
         _test_exclude_tokens = frozenset({"test", "tests", "spec", "specs", "it", "testing"})
         _tests_deliberately_excluded = bool(_extra_exc & _test_exclude_tokens)
 
+        # One authority for which files are tests (ADR-0008 R1): the substring
+        # rule this replaces counted production classes living in a package
+        # named `test` as tests, so a repository with none reported "2 test
+        # files" while `has_tests` in the same document said the same wrong
+        # thing from a second derivation.
+        from sourcecode.test_sources import analyze_test_sources
+
         _java_all = [p for p in sm.file_paths if p.endswith(".java")]
-        _java_tests = [
-            p for p in _java_all
-            if "/test/" in p.replace("\\", "/") or "/tests/" in p.replace("\\", "/")
-            or Path(p).stem.endswith(("Test", "Tests", "IT", "Spec"))
-        ]
+        _java_test_facts = analyze_test_sources(_java_all, extensions=(".java",))
+        _java_tests = list(_java_test_facts.test_files)
         _java_prod = [p for p in _java_all if p not in set(_java_tests)]
         if _java_prod and len(_java_prod) >= 10:
             _ratio = len(_java_tests) / len(_java_prod)
@@ -341,7 +345,7 @@ class ConfidenceAnalyzer:
                     reason=(
                         f"Backend test coverage critical: {len(_java_tests)} test files "
                         f"for {len(_java_prod)} Java files "
-                        f"({_ratio:.1%})"
+                        f"({_ratio:.1%}) — {_java_test_facts.basis}"
                     ),
                     impact="high",
                 ))

sourcecode/context_cache.py

@@ -190,34 +190,14 @@ def _git_head(repo_root: Path) -> str:
 def _worktree_signature(repo_root: Path) -> str:
     """Deterministic fingerprint of the *exact* tree state.
 
-    committed HEAD, plus — only when the tree is dirty — a hash of the porcelain
-    status and the diff against HEAD. Two identical tree states yield the same
-    signature (correct reuse); any tracked edit changes it (correct invalidation).
-    Returns ``""`` when the path is not a git repo (caller disables caching).
+    Thin alias of the one authority, :func:`sourcecode.cache.worktree_signature`.
+    It used to be a second implementation living here, which is how the two caches
+    ended up invalidating on different facts: this one on the tree, the snapshot
+    cache on the committed HEAD alone.
     """
-    head = _git_head(repo_root)
-    if not head:
-        return ""
-    try:
-        status = subprocess.run(
-            ["git", "-C", str(repo_root), "status", "--porcelain"],
-            capture_output=True, text=True, timeout=5,
-        )
-        porcelain = status.stdout if status.returncode == 0 else ""
-    except Exception:
-        porcelain = ""
-    if not porcelain.strip():
-        return head  # clean tree — HEAD fully describes it
-    try:
-        diff = subprocess.run(
-            ["git", "-C", str(repo_root), "diff", "HEAD"],
-            capture_output=True, text=True, timeout=10,
-        )
-        diff_txt = diff.stdout if diff.returncode == 0 else ""
-    except Exception:
-        diff_txt = ""
-    dirty = hashlib.sha256((porcelain + "\x00" + diff_txt).encode("utf-8", "replace")).hexdigest()[:16]
-    return f"{head}+dirty:{dirty}"
+    from sourcecode.cache import worktree_signature
+
+    return worktree_signature(repo_root)
 
 
 def _options_fingerprint(options: Optional[dict[str, Any]]) -> str:

sourcecode/deployment_prefix.py

@@ -35,6 +35,11 @@ _SERVLET_PATH_KEYS: tuple[str, ...] = (
     "server.servlet-path",          # Boot 1.x spelling
 )
 
+#: The same keys, exported: every consumer that needs to ask a resolved-property
+#: authority for a prefix reads them from here rather than spelling them again.
+CONTEXT_PATH_KEYS: tuple[str, ...] = _CONTEXT_PATH_KEYS
+SERVLET_PATH_KEYS: tuple[str, ...] = _SERVLET_PATH_KEYS
+
 # Published multi-document / profile activation keys.
 _PROFILE_KEYS: tuple[str, ...] = (
     "spring.config.activate.on-profile",
@@ -227,3 +232,83 @@ def detect_deployment_prefix(root: Path) -> DeploymentPrefix:
 
     result.sources.sort(key=lambda s: (s.file, s.key, s.profile or "", s.value))
     return result
+
+
+def normalize_prefix(value: str) -> str:
+    """`api/` → `/api`; empty or `/` → `""`. A prefix is a path segment chain."""
+    cleaned = re.sub(r"/+", "/", (value or "").strip()).strip()
+    cleaned = "/" + cleaned.strip("/")
+    return "" if cleaned == "/" else cleaned
+
+
+@dataclass(frozen=True)
+class ServletPrefix:
+    """The DispatcherServlet path, and whether it could be decided at all.
+
+    Security matchers never see the servlet CONTEXT path — the container strips
+    it before the filter chain runs — but a servlet path declared by
+    ``spring.mvc.servlet.path`` IS part of what an ant matcher matches. The two
+    prefixes are therefore different facts, and only this one belongs in a
+    request-chain answer.
+    """
+
+    value: str = ""
+    #: Set when a declaration exists but its value could not be decided
+    #: (placeholder, or profile documents that disagree). The prefix is then
+    #: unknown, never assumed empty.
+    undecidable_reason: Optional[str] = None
+    key: Optional[str] = None
+    source: Optional[str] = None
+
+    @property
+    def decided(self) -> bool:
+        return self.undecidable_reason is None
+
+    def to_dict(self) -> dict:
+        out: dict = {"servlet_path": self.value, "decided": self.decided}
+        if self.key:
+            out["key"] = self.key
+        if self.source:
+            out["source"] = self.source
+        if self.undecidable_reason:
+            out["undecidable_reason"] = self.undecidable_reason
+        return out
+
+
+def servlet_prefix_from_properties(properties: Any) -> ServletPrefix:
+    """The servlet path a resolved-property authority states, or why it cannot.
+
+    `properties` is anything with `lookup(key)` / `blocked(key)` — the resolved
+    view for a profile set, so a servlet path declared only under `prod` applies
+    exactly when `prod` was asked about. An unresolved placeholder is reported
+    undecidable rather than treated as "no prefix": the difference between an
+    unknown prefix and no prefix is the difference between "cannot say" and a
+    confident wrong answer about which rule matches.
+    """
+    for key in SERVLET_PATH_KEYS:
+        blocked = None
+        try:
+            blocked = properties.blocked(key)
+        except Exception:
+            blocked = None
+        if blocked:
+            return ServletPrefix(undecidable_reason=str(blocked), key=key)
+        try:
+            found = properties.lookup(key)
+        except Exception:
+            found = None
+        if found is None:
+            continue
+        raw = str(getattr(found, "value", "") or "")
+        if _PLACEHOLDER_RE.search(raw):
+            return ServletPrefix(
+                undecidable_reason=f"value carries an unresolved placeholder: {raw}",
+                key=key,
+                source=str(getattr(found, "source", "") or "") or None,
+            )
+        return ServletPrefix(
+            value=normalize_prefix(raw),
+            key=key,
+            source=str(getattr(found, "source", "") or "") or None,
+        )
+    return ServletPrefix()

sourcecode/facts/__init__.py

@@ -0,0 +1,71 @@
+"""facts — the registry of facts that have exactly one authority (ADR-0008 §4).
+
+A fact in this registry is a question the product answers with a number, a name
+or a verdict, and which more than one command emits. The registry states who
+derives it, what it means, and which modules are allowed to emit it. R13: a new
+consumer that emits a registered fact without binding to its authority fails
+review, and a new fact is registered in the commit that introduces it.
+
+The registry is data, shipped inside the package, so an installed version can be
+asked what its own contract is — the same reason the response-envelope schema is
+shipped rather than documented.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+REGISTRY_PATH = Path(__file__).resolve().parent / "registry.json"
+
+
+@dataclass(frozen=True)
+class Fact:
+    """One registered fact and the seam that made it one."""
+
+    fact: str
+    authority: str
+    definition: str
+    consumers: "tuple[str, ...]" = ()
+    parity_test: str = ""
+    stats_key: str = ""
+    seam: str = ""
+    was: str = ""
+
+    @property
+    def authority_module(self) -> str:
+        return self.authority.split(":", 1)[0]
+
+    @property
+    def authority_symbol(self) -> str:
+        return self.authority.split(":", 1)[1] if ":" in self.authority else ""
+
+
+def load_registry() -> dict:
+    """The registry as published, unmodified."""
+    return json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
+
+
+def registered_facts() -> "tuple[Fact, ...]":
+    """Every registered fact, in registry order."""
+    return tuple(
+        Fact(
+            fact=str(entry["fact"]),
+            authority=str(entry["authority"]),
+            definition=str(entry["definition"]),
+            consumers=tuple(entry.get("consumers") or ()),
+            parity_test=str(entry.get("parity_test") or ""),
+            stats_key=str(entry.get("stats_key") or ""),
+            seam=str(entry.get("seam") or ""),
+            was=str(entry.get("was") or ""),
+        )
+        for entry in load_registry().get("facts") or []
+    )
+
+
+def fact(name: str) -> "Fact":
+    """One registered fact by name. Raises KeyError when it is not registered."""
+    for entry in registered_facts():
+        if entry.fact == name:
+            return entry
+    raise KeyError(name)

sourcecode/facts/registry.json

@@ -0,0 +1,158 @@
+{
+  "registry_version": "facts-v1",
+  "note": "ADR-0008 R11. One authority per fact. `authority` is module:symbol; `consumers` are the modules allowed to emit the fact, and each MUST import the authority rather than re-derive it (R13). `parity_test` is the assertion that keeps every emitter agreeing (R12).",
+  "facts": [
+    {
+      "fact": "transactional_boundaries_touched",
+      "authority": "sourcecode.spring_semantic:boundaries_declared_within",
+      "definition": "Transaction boundaries declared within a symbol's own body plus those declared by its callers — the blast radius of changing it.",
+      "stats_key": "transactional_boundaries_touched",
+      "consumers": [
+        "sourcecode.repository_ir"
+      ],
+      "parity_test": "tests/test_tx_boundary_authority.py",
+      "seam": "M7 seam 1",
+      "was": "A graph node role `transaction_boundary` no producer ever assigns, so the figure was structurally always 0.",
+      "unresolved_answer": null,
+      "unresolved_note": "The tx index either declares a boundary within the scanned symbols or it does not; there is no third state to report. What is unknown is whether a boundary exists in code this analyzer never saw, and that is stated as analysis scope, not as this fact's value."
+    },
+    {
+      "fact": "transactional_boundaries_reaching",
+      "authority": "sourcecode.spring_semantic:boundaries_declared_within",
+      "definition": "Transaction boundaries declared by the callers that reach a symbol — the figure `retrieve transactions-reaching` reports. A different question from `_touched`, so it carries a different name (ADR-0008 R3).",
+      "stats_key": "transactional_boundaries_reaching",
+      "consumers": [
+        "sourcecode.repository_ir",
+        "sourcecode.retrieval.steps_graph"
+      ],
+      "parity_test": "tests/test_tx_boundary_authority.py",
+      "seam": "M7 seam 1",
+      "unresolved_answer": null,
+      "unresolved_note": "Same as `transactional_boundaries_touched`: the caller set is the scope, and a boundary is declared or absent within it."
+    },
+    {
+      "fact": "endpoint_population",
+      "authority": "sourcecode.security_posture:endpoint_population",
+      "definition": "The denominator for every endpoint statement, with the three units named apart: endpoints, handler methods, declarations. Every partition sums to it or declares its exclusion set.",
+      "stats_key": "population",
+      "consumers": [
+        "sourcecode.security_posture"
+      ],
+      "parity_test": "tests/test_endpoint_count_parity.py",
+      "seam": "M7 seam 2",
+      "was": "Three incompatible denominators in one document; only the rollup reconciled.",
+      "unresolved_answer": null,
+      "unresolved_note": "A population is a count of what was parsed. Where a route could not be modelled it is excluded and the exclusion set is published, so the denominator never carries an undecided member."
+    },
+    {
+      "fact": "endpoint_security_surface",
+      "authority": "sourcecode.security_posture:endpoint_security_surface",
+      "definition": "What guards an endpoint, as a verdict plus a confidence — `coverage_unknown` where a custom gate is undetermined, never `none_detected`.",
+      "consumers": [
+        "sourcecode.spring_impact"
+      ],
+      "parity_test": "tests/test_endpoint_security_surface.py",
+      "seam": "M7 seam 3",
+      "was": "`impact-chain` printed `none_detected` for endpoints the same run classified `protected_custom`.",
+      "unresolved_answer": "coverage_unknown",
+      "unresolved_note": "Absence of a posture entry is absence of evidence, never `none_detected`."
+    },
+    {
+      "fact": "integration_coordinates",
+      "authority": "sourcecode.integration_coordinates:declared_integration_coordinates",
+      "definition": "What the build declares the application integrates with, reported beside what the source scan observed — `declared_clients` and `kinds_declared_not_observed`.",
+      "consumers": [
+        "sourcecode.cli",
+        "sourcecode.retrieval.steps_intf"
+      ],
+      "parity_test": "tests/test_integration_coordinates.py",
+      "seam": "M7 seam 4",
+      "was": "`export --integrations` reported 0 LDAP while the stack block listed a declared LDAP client.",
+      "unresolved_answer": null,
+      "unresolved_note": "The authority answers what the build declares, which a manifest either states or does not. The undecided case is the comparison against what the source scan observed, and it is published by the consumers as `kinds_declared_not_observed` rather than resolved either way."
+    },
+    {
+      "fact": "test_sources",
+      "authority": "sourcecode.test_sources:analyze_test_sources",
+      "definition": "Whether a file is a test source: it sits under a declared test source root, or matches an ecosystem naming convention. A `test` package inside a main source root is production code.",
+      "stats_key": "has_tests",
+      "consumers": [
+        "sourcecode.serializer",
+        "sourcecode.confidence_analyzer",
+        "sourcecode.metrics_analyzer",
+        "sourcecode.prepare_context"
+      ],
+      "parity_test": "tests/test_test_sources_authority.py",
+      "seam": "M7 seam 5",
+      "was": "A substring rule counted production classes in a package named `test`, contradicting `analysis_gaps` in the same document.",
+      "unresolved_answer": null,
+      "unresolved_note": "Total by construction: every path gets a decided answer, because a layout either declares a test root or it does not. The unknown lives one level up — a repository with no test sources makes a COVERAGE question unanswerable, and the consumers emit `unknown` there rather than `low`."
+    },
+    {
+      "fact": "type_reference_status",
+      "authority": "sourcecode.reference_facts:analyze_type_references",
+      "definition": "Whether a type is referenced: `referenced` / `unknown_framework_dispatch` / `no_static_callers`. A partition summing to the classes examined, where `no_static_callers` is absence of evidence and never a dead-code claim.",
+      "stats_key": "reference_status",
+      "consumers": [
+        "sourcecode.cli"
+      ],
+      "parity_test": "tests/test_reference_facts.py",
+      "seam": "M7 seam 6",
+      "was": "`statically_unreferenced: 0` over 3 374 classes: a population that never matched its own definition, and no way to say `unknown`.",
+      "unresolved_answer": "unknown_framework_dispatch",
+      "unresolved_note": "No static caller plus a dispatch signal is unknown; a static call-graph cannot decide it."
+    },
+    {
+      "fact": "profile_conditional_declarations",
+      "authority": "sourcecode.spring_profiles:conditional_beans_from_sources_detailed",
+      "definition": "Which declaration each `@Profile` annotates, and the expression as written. A member-level annotation belongs to `Type#member`; an annotation whose target cannot be read is not reported at all.",
+      "consumers": [
+        "sourcecode.serializer"
+      ],
+      "parity_test": "tests/test_deployment_prefix_and_profiles.py",
+      "seam": "M7 seam 7",
+      "was": "A class was listed under a profile AND its negation, contradicting `posture` in the same run.",
+      "unresolved_answer": null,
+      "unresolved_note": "An annotation whose target cannot be read is not reported at all — the fact omits what it cannot attribute rather than reporting it undecided."
+    },
+    {
+      "fact": "profile_activation",
+      "authority": "sourcecode.posture:resolve_beans",
+      "definition": "Whether a profile set activates a bean. Resolution — as opposed to which profile a declaration mentions — is `posture`'s answer, and it is three-valued: active, inactive, unresolved.",
+      "consumers": [
+        "sourcecode.posture"
+      ],
+      "parity_test": "tests/test_deployment_prefix_and_profiles.py",
+      "seam": "M7 seam 7",
+      "unresolved_answer": "unresolved",
+      "unresolved_note": "A condition that cannot be evaluated is never folded into active or inactive."
+    },
+    {
+      "fact": "deployment_prefix",
+      "authority": "sourcecode.deployment_prefix:detect_deployment_prefix",
+      "definition": "The URL prefix the application is served under (`server.servlet.context-path` + `spring.mvc.servlet.path`), applied to mapping-relative paths as `effective_path`.",
+      "stats_key": "effective_path",
+      "consumers": [
+        "sourcecode.repository_ir",
+        "sourcecode.posture"
+      ],
+      "parity_test": "tests/test_deployment_prefix_and_profiles.py",
+      "seam": "M7 seam 8",
+      "unresolved_answer": "unconditional",
+      "unresolved_note": "A prefix declared only under a profile, or carrying an unresolved placeholder, is published with `unconditional: false` and never silently applied to every route."
+    },
+    {
+      "fact": "servlet_prefix",
+      "authority": "sourcecode.deployment_prefix:servlet_prefix_from_properties",
+      "definition": "The part of the prefix a security matcher sees: the servlet path for the profile set asked about. The servlet CONTEXT path is excluded — the container strips it before the filter chain runs — so this is a different fact from `deployment_prefix`, not a view of it.",
+      "consumers": [
+        "sourcecode.posture"
+      ],
+      "parity_test": "tests/test_posture.py",
+      "seam": "M7 seam 8",
+      "was": "`posture` matched chain rules against unprefixed paths and reported endpoints as covered by no rule — or, with a catch-all behind the rule, as open.",
+      "unresolved_answer": "undecidable_reason",
+      "unresolved_note": "A declared servlet path that cannot be resolved makes the matching basis unknown, and every path-dependent verdict becomes `undecided`."
+    }
+  ]
+}

sourcecode/license.py

@@ -396,7 +396,7 @@ _init()
 # ---------------------------------------------------------------------------
 
 def _emit_telemetry(event: str, **kw: object) -> None:
-    """Best-effort telemetry emit. Respects the user's opt-out; never raises or blocks."""
+    """Best-effort telemetry emit. Sends nothing unless the user opted in; never raises or blocks."""
     try:
         from sourcecode import telemetry as _tel
         _tel.record(event, **kw)  # type: ignore[arg-type]

sourcecode/mcp/registry.py

@@ -800,7 +800,7 @@ depth: BFS depth for indirect caller traversal (1–8, default: 4).
 Analyzes codebase for modernization opportunities: dead zones, hotspot scores, upgrade candidates.
 
 Maps to: ask modernize <repo_path>
-Returns: hotspot_candidates (high fan-in + git churn), statically_unreferenced (zero-caller classes — NOT confirmed dead; verify no framework dispatch) + framework_dispatched,
+Returns: hotspot_candidates (high fan-in + git churn), statically_unreferenced (no static caller AND no dispatch signal found — absence of evidence, NOT confirmed dead code) + framework_dispatched (no static caller but a framework may invoke them: status unknown). Counts live in summary.reference_status, which partitions every class,
          high_coupling_nodes, subsystem_summary, cross_module_tangles, recommendation.
 
 Best for: refactor planning, identifying where to start, finding safe removal candidates.

sourcecode/mcp/server.py

@@ -33,8 +33,8 @@ def _record_tool_invocation(name: Any, success: bool, started: float) -> None:
 
     Aggregate only: which of our own tools ran, whether it succeeded, and a
     duration bucket. Never the arguments — those carry repository paths — and
-    never any result content. Honours the same opt-out as every other event
-    (`ask telemetry disable`, SOURCECODE_TELEMETRY=0, DO_NOT_TRACK=1); when
+    never any result content. Honours the same opt-in as every other event
+    (off until `ask telemetry enable` or SOURCECODE_TELEMETRY=1); when
     telemetry is off, `record` returns before building anything.
     """
     try:
@@ -1377,7 +1377,7 @@ def modernize_context(repo_path: str = ".", format: str = "json") -> dict:
     """Analyzes codebase for modernization opportunities: dead zones, hotspot scores, upgrade candidates.
 
     Maps to: ask modernize <repo_path>
-    Returns: hotspot_candidates (high fan-in + git churn), statically_unreferenced (zero-caller classes — NOT confirmed dead; verify no framework dispatch) + framework_dispatched,
+    Returns: hotspot_candidates (high fan-in + git churn), statically_unreferenced (no static caller AND no dispatch signal found — absence of evidence, NOT confirmed dead code) + framework_dispatched (no static caller but a framework may invoke them: status unknown). Counts live in summary.reference_status, which partitions every class,
              high_coupling_nodes, subsystem_summary, cross_module_tangles, recommendation.
 
     Best for: refactor planning, identifying where to start, finding safe removal candidates.

sourcecode/metrics_analyzer.py

@@ -60,13 +60,16 @@ _STEM_PATTERNS: list[tuple[re.Pattern[str], str]] = [
 
 
 def is_test_file(path: str) -> bool:
-    """Return True if path corresponds to a test file based on ecosystem conventions.
+    """Return True if path corresponds to a test file.
 
-    Normalizes Windows backslashes to forward slashes before matching.
-    Patterns are anchored to avoid false positives (e.g., 'testdata/', '*_tested.py').
+    Delegates to `test_sources.is_test_path`, the one authority for this fact
+    (ADR-0008 R1): a declared test source root (`src/test`, `src/it`, `tests/`)
+    or an ecosystem naming convention — and never a `test` package that sits
+    inside a main source root.
     """
-    normalized = path.replace("\\", "/")
-    return any(p.search(normalized) for p in _TEST_FILE_PATTERNS)
+    from sourcecode.test_sources import is_test_path
+
+    return is_test_path(path)
 
 
 def infer_production_target(test_path: str) -> str | None:

sourcecode/posture.py

@@ -542,8 +542,29 @@ _ACCESS_DECISIONS_ORDER = (
 )
 
 
+def _servlet_prefix_from_root(root: Path) -> "ServletPrefix":
+    """The servlet path from the repository's own configuration.
+
+    Used when no resolved-property view is supplied. It applies only the
+    unconditional declaration — a servlet path declared under a profile is a fact
+    about that profile, and this caller did not name one.
+    """
+    from sourcecode.deployment_prefix import (
+        ServletPrefix, detect_deployment_prefix, normalize_prefix,
+    )
+
+    try:
+        detected = detect_deployment_prefix(Path(root))
+    except Exception:
+        return ServletPrefix()
+    return ServletPrefix(value=normalize_prefix(detected.servlet_path))
+
+
 def access_projection(
-    cir: "CanonicalRepositoryIR", resolution: BeanResolution, root: Path
+    cir: "CanonicalRepositoryIR",
+    resolution: BeanResolution,
+    root: Path,
+    properties: "Optional[object]" = None,
 ) -> "tuple[dict, dict[str, str]]":
     """What the active chain configuration decides for each endpoint.
 
@@ -555,9 +576,20 @@ def access_projection(
     with different decisions, the answer is `undecided`: their relative order is
     an `@Order`/bean-ordering question this analyzer does not resolve, and picking
     one would state a security fact by coin flip.
+
+    Rules are matched against the path the filter chain receives, which is the
+    mapping-relative path prefixed by any declared `spring.mvc.servlet.path`.
+    Matching the unprefixed path instead reports `no_rule_matched` for endpoints
+    a declared matcher covers — a posture answer that under-reports protection.
     """
-    from sourcecode.chain_rules import extract_chain_rules, first_matching_rule
+    from sourcecode.chain_rules import extract_chain_rules, first_match
+    from sourcecode.deployment_prefix import servlet_prefix_from_properties
 
+    servlet = (
+        servlet_prefix_from_properties(properties) if properties is not None
+        else _servlet_prefix_from_root(root)
+    )
+    prefix = servlet.value if servlet.decided else ""
     states = _chain_state_by_file(cir, resolution)
     rules_by_file = extract_chain_rules(root, sorted(states)) if states else {}
     active_files = sorted(f for f in rules_by_file if states.get(f) == "active")
@@ -573,12 +605,17 @@ def access_projection(
             continue
         decisions: dict[str, dict] = {}
         for source_file in active_files:
-            rule = first_matching_rule(rules_by_file[source_file], endpoint.method, endpoint.path)
+            rule, matched = first_match(
+                rules_by_file[source_file], endpoint.method, endpoint.path, prefix
+            )
             if rule is None:
                 continue
-            decisions["undecided" if rule.paths_unknown else rule.decision] = rule.to_dict()
+            evidence = rule.to_dict()
+            if matched != endpoint.path:
+                evidence["matched_path"] = matched
+            decisions["undecided" if rule.paths_unknown else rule.decision] = evidence
         if any(
-            first_matching_rule(rules_by_file[f], endpoint.method, endpoint.path) is not None
+            first_match(rules_by_file[f], endpoint.method, endpoint.path, prefix)[0] is not None
             for f in undecided_files
         ):
             decisions["undecided"] = {
@@ -599,6 +636,28 @@ def access_projection(
         by_endpoint[endpoint.id] = decision
         details[endpoint.id] = evidence
 
+    # A declared-but-undecidable servlet path means the URL the chain matches is
+    # unknown. Where any pattern rule is declared, that unknown decides which rule
+    # is reached — including whether a later `anyRequest` is reached at all — so
+    # no chain-derived verdict survives it. A handler's own guard does, and so
+    # does a chain whose only rule is `anyRequest`: it matches every URL.
+    path_dependent = any(
+        not rule.is_any_request
+        for source_file in active_files + undecided_files
+        for rule in rules_by_file[source_file]
+    )
+    if not servlet.decided and path_dependent:
+        for endpoint_id, decision in list(by_endpoint.items()):
+            if decision == "guarded_by_own_annotation":
+                continue
+            by_endpoint[endpoint_id] = "undecided"
+            details[endpoint_id] = {
+                "reason": "the declared servlet path could not be resolved, so the URL "
+                          "these matchers compare against is unknown",
+                "servlet_path": servlet.to_dict(),
+                "decision_if_unprefixed": decision,
+            }
+
     summary = {
         key: sum(1 for d in by_endpoint.values() if d == key)
         for key in _ACCESS_DECISIONS_ORDER
@@ -612,6 +671,19 @@ def access_projection(
         },
         "summary": {k: v for k, v in summary.items() if v},
     }
+    # State the URL basis the rules were matched against. `endpoints` publishes
+    # `effective_path` (context path included, which the container strips before
+    # the chain runs); this is the same authority read for the part a matcher
+    # actually sees.
+    if servlet.value or not servlet.decided:
+        payload["path_basis"] = {
+            **servlet.to_dict(),
+            "note": (
+                "chain rules are matched against the servlet path + the "
+                "mapping-relative path; the servlet context path is not part of "
+                "it, because the container strips it before the filter chain runs"
+            ),
+        }
     for key in ("permit_all", "deny_all", "no_rule_matched", "undecided"):
         listed = sorted(e for e, d in by_endpoint.items() if d == key)
         if listed:
@@ -682,7 +754,7 @@ def _posture(
     payload["endpoints"] = endpoint_projection(cir, payload["security"])
     # Which chain is wired is a fact about a bean; what that chain permits is the
     # fact about the request, and it is the one a reviewer asked for.
-    access, by_endpoint = access_projection(cir, resolution, root)
+    access, by_endpoint = access_projection(cir, resolution, root, resolved_properties)
     payload["endpoints"]["effective_access"] = access
     # A requested profile no repository artefact mentions is almost always a typo,
     # and silently resolving every `@Profile` against it would answer confidently