sourcecode 2.6.0__tar.gz → 2.6.1__tar.gz

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

@@ -1,5 +1,40 @@
 # Changelog
 
+## [2.6.1] — 2026-07-22
+
+**Stability patch — extraction/label fidelity on the 2.6.x line. No new
+capability, no functional-contract change.** Two isolated corrections where the
+system produced a correct result but described it imperfectly (P1-H) or gave a
+provably-correct answer a misleading label (SIM-4). `2.6.0` remains the stable
+baseline; this is a fidelity patch on top of it. Full suite: **3637 passed, 5
+skipped, 1 deselected** (the deselected chunker test is a pre-existing external
+fixture flake).
+
+### Fixed
+
+- **P1-H — lowercase-initial type declarations were silently dropped.**
+  `_CLASS_DECL_RE` assumed the PascalCase convention (`[A-Z]\w*`) for the
+  type-name start, so valid lowercase-initial Java types never entered the
+  symbol graph (e.g. `iFieldMetadata`, `i18nUpdateCartServiceExtensionHandler`;
+  JNA C-struct mirrors `passwd`/`group`/`pam_*`). The same assumption was
+  duplicated in the multi-line-join gate, so a lowercase declaration whose brace
+  sat on a continuation line stayed lost even after widening the primary regex.
+  Both name-start charsets widened to `[A-Za-z]\w*`, and a length-preserving
+  string-literal blanking guard was added at the declaration-scan sites so a
+  `class`/`interface` keyword appearing inside a string literal (e.g. a log
+  message `"... advice class for {} ..."`) can no longer mint a phantom type.
+  Fleet A/B over six real repositories: +9 real types recovered, zero phantoms,
+  zero symbols lost, control repositories byte-stable.
+- **SIM-4 — a method-precise resolution was labelled `class_expanded`.** When a
+  `Class#method` query matched one class by short/suffix name and its method
+  resolved to exactly one method node, `impact-chain` returned the correct
+  method-scoped result but tagged it `class_expanded` — signalling "I broadened
+  your query to the whole class" over a narrow, correct answer. A distinct
+  resolution value `method_resolved` now describes that case (confidence stays
+  high; nothing was widened); the genuine no-method class-expansion case keeps
+  `class_expanded`. No behavioural change — the resolved symbol set, confidence,
+  and callers are identical; only the exposed label changed to match reality.
+
 ## [2.6.0] — 2026-07-22
 
 **Engineering Decision Support — Part B (capability milestone) lands, plus the

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

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

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

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

{sourcecode-2.6.0 → sourcecode-2.6.1}/src/sourcecode/__init__.py

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

{sourcecode-2.6.0 → sourcecode-2.6.1}/src/sourcecode/repository_ir.py

@@ -134,7 +134,13 @@ _ANN_WITH_ARGS_RE = re.compile(
 _CLASS_DECL_RE = re.compile(
     r'(?:^|(?<=\s))'
     r'(?P<kind>class|interface|enum|record|@interface)\s+'
-    r'(?P<name>[A-Z]\w*)'
+    # P1-H: Java identifiers may start lowercase — the uppercase-only start
+    # (PascalCase convention) silently dropped valid lowercase-initial types
+    # (Broadleaf `iFieldMetadata`, `i18nUpdateCartServiceExtensionHandler`).
+    # A literal type keyword + terminal `{` already gates the match, so widening
+    # the name-start does not admit prose/string phantoms the uppercase form
+    # was not already exposed to (verified fleet A/B, no new symbols on controls).
+    r'(?P<name>[A-Za-z]\w*)'
     r'(?:\s*<[^{;]*?(?=>|\{))?'
     # P1-F: record component list `record Point(int x, int y)`. `[^{;]*` is greedy
     # to the LAST ')' before the body brace, so annotated components with
@@ -663,7 +669,22 @@ _ANN_NAME_RE = re.compile(r'^@\w+\s*')
 _STRING_LITERAL_RE = re.compile(r'"(?:[^"\\]|\\.)*"|\'(?:[^\'\\]|\\.)*\'')
 
 # Module-level cache for class-keyword detection (avoids recompilation per _extract_symbols call)
-_CLASS_KW_RE = re.compile(r'\b(?:class|interface|enum|record)\s+[A-Z]')
+# P1-H: lowercase-initial start mirrors _CLASS_DECL_RE so multi-line lowercase-named
+# declarations (`class i18nHandler extends A\n implements B {`) are joined too.
+_CLASS_KW_RE = re.compile(r'\b(?:class|interface|enum|record)\s+[A-Za-z]')
+
+
+def _blank_string_literals(text: str) -> str:
+    """Return `text` with each string/char literal replaced by equal-length spaces.
+
+    P1-H: type-declaration scans (_CLASS_DECL_RE / _CLASS_KW_RE) run on lines whose
+    comments are stripped but whose STRING content survives. A log/message literal
+    such as `log.debug("... advice class for {} ...")` then matches `class for {`
+    and mints a phantom type `for`. Blanking the literal content (length-preserving,
+    so match offsets stay aligned with the original line) removes the false surface
+    without touching genuine declarations, which never live inside a string.
+    """
+    return _STRING_LITERAL_RE.sub(lambda m: ' ' * len(m.group(0)), text)
 
 
 # ---------------------------------------------------------------------------
@@ -958,7 +979,8 @@ def _extract_symbols(
         _start = _i  # 0-based source index where this joined entry begins
         _line = _raw_lines[_i]
         _stripped = _line.strip()
-        if (_CLASS_KW_RE.search(_stripped) and '{' not in _stripped
+        _kw_scan = _blank_string_literals(_stripped)
+        if (_CLASS_KW_RE.search(_kw_scan) and '{' not in _kw_scan
                 and not _stripped.startswith('//')
                 and not _stripped.startswith('*')):
             # Continuation: join until we hit a line containing '{'
@@ -1043,7 +1065,10 @@ def _extract_symbols(
             _pop_closed(class_stack, depth)
             continue
 
-        cls_m = _CLASS_DECL_RE.search(stripped)
+        # P1-H: search a string-blanked view so `class`/`interface` keywords that
+        # appear inside string literals (log messages, templates) do not mint a
+        # phantom type. Length-preserving, so cls_m offsets align with `stripped`.
+        cls_m = _CLASS_DECL_RE.search(_blank_string_literals(stripped))
         if cls_m:
             kind_kw = cls_m.group("kind")
             name = cls_m.group("name")
@@ -2311,7 +2336,9 @@ def _extract_field_types(
             package = stripped[8:].rstrip(";").strip()
             continue
         net = _count_net_braces(stripped)
-        cls_m = _CLASS_DECL_RE.search(stripped)
+        # P1-H: string-blanked search (see _blank_string_literals) — a keyword inside
+        # a literal must not push a phantom nesting frame onto class_stack.
+        cls_m = _CLASS_DECL_RE.search(_blank_string_literals(stripped))
         if cls_m:
             name = cls_m.group("name")
             fqn = f"{class_stack[-1][0]}.{name}" if class_stack else (

sourcecode-2.6.1/src/sourcecode/retrieval/composition.py

@@ -0,0 +1,496 @@
+"""Composition Semantics — Layer 1 foundations (ADR-0007).
+
+This module is the single source of truth for the **identity namespace** of every
+entity kind the retrieval step library emits. It realizes two ADR-0007 invariants
+as executable contract:
+
+- **INV-C10 (node-vs-facet).** A kind is a *base namespace* iff it carries an
+  independent identity; a kind whose identity is another entity's identity is a
+  *facet* of that entity. The three base namespaces are ``symbol`` (the join hub),
+  ``endpoint`` and ``module``. Facet kinds (a tx-role, a public contract, a
+  validation point, a security finding) live in the base namespace of the identity
+  they are keyed by — e.g. ``transaction_boundary`` has ``identity = b.symbol`` and
+  therefore reports namespace ``symbol``.
+- **INV-C5 (single bridge-graph / single mapping).** There is exactly ONE table
+  mapping kinds to namespaces. No capability may keep its own copy; the join engine
+  and every future composed intent read this one.
+
+``integration`` and ``event_type`` carry a synthetic independent identity but have
+low join value in v1 (ADR-0007 §3); they are *peripheral* namespaces, outside the
+base graph. An unknown kind maps to ``None`` — the honest answer is "not classified",
+never a guess (a mis-guess would silently enable a wrong join).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Any, Callable, Iterable, Optional
+
+from .errors import CompositionError
+from .result import KnowledgeEntity
+
+# The three base namespaces (ADR-0007 §3). Order is the hub-first convention, not
+# semantic — membership is what matters.
+BASE_NAMESPACES: tuple[str, ...] = ("symbol", "endpoint", "module")
+
+# Peripheral namespaces: real independent identity, deferred out of the v1 join graph.
+PERIPHERAL_NAMESPACES: tuple[str, ...] = ("integration", "event")
+
+# The single kind→namespace table. Derived from the real ``identity=`` of each kind
+# emitted in ``steps_*.py`` (verified 2026-07-22). Adding a new emitted kind MUST add
+# a row here (the join engine treats an unmapped kind as unclassifiable).
+_KIND_TO_NAMESPACE: dict[str, str] = {
+    # ── symbol namespace (identity = FQN) — the join hub ────────────────────────
+    "dependent": "symbol",            # impact reverse-reach
+    "caller": "symbol",               # call graph, in-edge
+    "callee": "symbol",               # call graph, out-edge
+    "execution_path": "symbol",       # graph reachability
+    "type_dependent": "symbol",       # type-usage reverse dep
+    "subsystem_member": "symbol",     # module membership member
+    "coupling_hub": "symbol",         # high-degree node
+    "transaction_boundary": "symbol",   # facet: tx-role  (identity = b.symbol)
+    "transaction_entrypoint": "symbol",  # facet: tx-role
+    "propagation_point": "symbol",       # facet: tx-role
+    "transaction_reaching": "symbol",    # facet: reaches a tx (identity = b.symbol)
+    "security_finding": "symbol",        # facet: security (identity = f.symbol)
+    # ── endpoint namespace (identity = route id / handler) ──────────────────────
+    "endpoint": "endpoint",
+    "endpoint_contract": "endpoint",   # facet: public contract (identity = _endpoint_id)
+    "endpoint_security": "endpoint",   # facet: security, keyed by endpoint
+    "validation_point": "endpoint",    # facet: validation (identity = _route_id)
+    "validation_gap": "endpoint",      # facet: validation
+    # ── module namespace (identity = path / label) ──────────────────────────────
+    "module": "module",
+    "subsystem": "module",
+    # ── peripheral (deferred, ADR-0007 §3) ──────────────────────────────────────
+    "integration": "integration",
+    "event_type": "event",
+}
+
+
+def namespace_of(kind: str) -> Optional[str]:
+    """Return the identity namespace of an entity ``kind``, or ``None`` if the kind
+    is not classified. ``None`` is the honest answer for an unknown kind — the join
+    engine must not treat an unclassifiable entity as belonging to any namespace."""
+    return _KIND_TO_NAMESPACE.get(kind)
+
+
+def is_base_namespace(namespace: Optional[str]) -> bool:
+    """True iff ``namespace`` is one of the three base (join-graph) namespaces."""
+    return namespace in BASE_NAMESPACES
+
+
+def same_namespace(kind_a: str, kind_b: str) -> bool:
+    """True iff both kinds are classified into the SAME namespace.
+
+    This is the join engine's discriminator (ADR-0007 §3): two entities in the same
+    namespace combine by a plain set operation; two in different namespaces require a
+    declared bridge (§4). An unknown kind (namespace ``None``) is never "the same" as
+    anything — an unclassifiable entity cannot be safely set-joined.
+    """
+    ns_a = namespace_of(kind_a)
+    ns_b = namespace_of(kind_b)
+    return ns_a is not None and ns_a == ns_b
+
+
+# ── The bridge graph (ADR-0007 §4) ──────────────────────────────────────────────
+# A bridge is a declared relation that maps an entity in one base namespace to
+# entities in another, backed by a fact repository_ir already emits. It is the ONLY
+# legal way to join across namespaces (INV-C3); the set of bridges is a single source
+# of truth (INV-C5). Two of the four carry VARIABLE confidence (INV-C4) — and they
+# are exactly the two joins ASK already measures (endpoint resolution: SIM-1/2;
+# call-graph reach: P1-A/B); the rest are structural (always high).
+
+
+@dataclass(frozen=True)
+class Bridge:
+    """One declared cross-namespace relation.
+
+    ``from_ns``/``to_ns`` record the natural backing direction; a join may traverse a
+    bridge either way (see :func:`are_bridged`) — the confidence is symmetric.
+    ``variable_confidence`` marks a bridge whose per-edge confidence can be below
+    ``high`` and therefore participates in the §5 ``min`` as a real term; a structural
+    bridge is always ``high`` and can never lower a composed result.
+    """
+
+    from_ns: str
+    relation: str
+    to_ns: str
+    backing: str            # the repository_ir fact that grounds the edge
+    variable_confidence: bool
+
+
+BRIDGES: tuple[Bridge, ...] = (
+    Bridge("endpoint", "handled_by", "symbol", "route_surface[].handler", True),
+    Bridge("symbol", "reaches", "symbol", "reverse_call_graph", True),
+    Bridge("symbol", "enclosed_by", "symbol", "enclosing_class", False),
+    Bridge("module", "declares", "symbol", "subsystem_membership", False),
+)
+
+
+def bridges_between(from_ns: str, to_ns: str) -> tuple[Bridge, ...]:
+    """Declared bridges whose natural direction is exactly ``from_ns`` → ``to_ns``."""
+    return tuple(b for b in BRIDGES if b.from_ns == from_ns and b.to_ns == to_ns)
+
+
+def are_bridged(ns_a: str, ns_b: str) -> bool:
+    """True iff a declared bridge connects the two namespaces in EITHER direction."""
+    return any(
+        {b.from_ns, b.to_ns} == {ns_a, ns_b} or (b.from_ns == b.to_ns == ns_a == ns_b)
+        for b in BRIDGES
+    )
+
+
+def is_join_legal(kind_a: str, kind_b: str) -> bool:
+    """True iff two kinds may be composed: same namespace (a plain set op) OR a
+    declared bridge connects their namespaces (a bridged relate, ADR-0007 §4). An
+    unclassified kind (namespace ``None``) is never joinable — INV-C3 forbids an
+    implicit or guessed join."""
+    ns_a = namespace_of(kind_a)
+    ns_b = namespace_of(kind_b)
+    if ns_a is None or ns_b is None:
+        return False
+    return ns_a == ns_b or are_bridged(ns_a, ns_b)
+
+
+# ── The confidence lattice (ADR-0007 §5 / §11.2) ────────────────────────────────
+# Confidence is a TOTAL ORDER; the ONLY combinator is min (greatest-lower-bound);
+# `unproven` is absorbing. No max / average / heuristic exists (INV-C9). A composed
+# result can be no more certain than its weakest constituent OR its weakest bridge.
+
+# Strongest → weakest. Index is the rank; a larger index is weaker.
+CONFIDENCE_ORDER: tuple[str, ...] = ("high", "medium", "low", "unproven")
+_CONF_RANK: dict[str, int] = {level: i for i, level in enumerate(CONFIDENCE_ORDER)}
+_UNPROVEN_RANK: int = _CONF_RANK["unproven"]
+
+
+def confidence_min(*values: Optional[str]) -> str:
+    """Combine confidences by greatest-lower-bound on the total order (ADR-0007 §5).
+
+    Returns the WEAKEST of ``values``. `unproven` is absorbing. An unrecognized or
+    ``None`` value degrades to `unproven` — the honest floor, never silently ignored.
+    With no values at all the result is `unproven`: a composition standing on nothing
+    cannot claim confidence (this deliberately breaks the empty-min=top identity in
+    favour of honesty).
+    """
+    worst_rank = -1
+    for v in values:
+        rank = _CONF_RANK.get(v if v is not None else "", _UNPROVEN_RANK)
+        if rank > worst_rank:
+            worst_rank = rank
+    if worst_rank < 0:
+        return "unproven"
+    return CONFIDENCE_ORDER[worst_rank]
+
+
+# ── The typed algebra operators (ADR-0007 §2 / §11.3) ───────────────────────────
+# A small, closed, TOTAL, DETERMINISTIC operator set over KnowledgeEntity sets:
+#   • combine — typed union / difference / intersection WITHIN one namespace (§3.1)
+#   • filter  — a predicate over an entity's own attributes (§3.3, no join)
+#   • relate  — a bridged join ACROSS namespaces, through a declared bridge (§4)
+# They CONSUME facts and never produce them (INV-C1): `relate` takes a *bridge
+# resolver* (a function that reports, per source entity, the target identities an IR
+# fact already links it to, with that edge's confidence). The operators resolve
+# nothing themselves — wiring a resolver to a real repository_ir fact is a separate
+# build step. Confidence only ever attenuates (INV-C2) via `confidence_min` (§5),
+# and includes the traversed bridge edge (INV-C4). An illegal request (cross-namespace
+# combine, undeclared bridge, unclassifiable kind) RAISES `CompositionError` — never a
+# silently-empty result (INV-F1-6).
+
+# Per-entity confidence lives in `attributes` under this key. Absent → the caller's
+# supplied constituent confidence, ultimately `unproven` (never silently `high`).
+ATTR_CONFIDENCE = "confidence"
+# The symbol an endpoint is handled_by, as a first-class attribute (ADR-0007 §11.1b) —
+# so the `handled_by` bridge reads a field instead of parsing the entity identity.
+ATTR_HANDLER_SYMBOL = "handler_symbol"
+# Provenance breadcrumbs a `relate` writes onto each produced entity (§8.1: composition
+# adds provenance edges, removes none).
+ATTR_BRIDGED_VIA = "bridged_via"
+ATTR_BRIDGE_TARGET = "bridge_target"
+
+# A bridge resolver reports, for one source entity, the edges an IR fact links it to,
+# as (target_identity, edge_confidence) pairs. Zero pairs = this source has no such
+# edge (an honest empty, not an error).
+BridgeResolver = Callable[[KnowledgeEntity], Iterable[tuple[str, str]]]
+
+
+def entity_confidence(entity: KnowledgeEntity, default: str = "unproven") -> str:
+    """Read an entity's own confidence from its attributes.
+
+    An absent or unrecognized value degrades to ``default`` — a caller passes the
+    constituent surface's result-level confidence so a per-entity omission does not
+    silently read as ``high``. With no default supplied the floor is ``unproven``
+    (INV-C7: an input's uncertainty is never laundered away)."""
+    v = entity.attributes.get(ATTR_CONFIDENCE)
+    return v if v in _CONF_RANK else default
+
+
+def _with_confidence(entity: KnowledgeEntity, confidence: str, **extra: Any) -> KnowledgeEntity:
+    """Return a copy of ``entity`` carrying ``confidence`` (and any provenance extras)
+    in its attributes. Frozen entity in, frozen entity out — never mutated in place."""
+    attrs = dict(entity.attributes)
+    attrs[ATTR_CONFIDENCE] = confidence
+    attrs.update(extra)
+    return replace(entity, attributes=attrs)
+
+
+def _uniform_namespace(entities: Iterable[KnowledgeEntity], *, op: str) -> Optional[str]:
+    """The single base namespace shared by every entity, or ``None`` for the empty set.
+
+    Raises ``CompositionError`` if the entities span more than one namespace or include
+    an unclassifiable kind — a set operation is only defined within one namespace (§3.1;
+    INV-C10)."""
+    ns: Optional[str] = None
+    for e in entities:
+        e_ns = namespace_of(e.kind)
+        if e_ns is None:
+            raise CompositionError(
+                f"{op}: kind {e.kind!r} is unclassified (no namespace); "
+                "an unclassifiable entity cannot take part in a set operation"
+            )
+        if ns is None:
+            ns = e_ns
+        elif ns != e_ns:
+            raise CompositionError(
+                f"{op}: operands span namespaces {ns!r} and {e_ns!r}; a set operation "
+                "is defined only within one namespace — use `relate` across a bridge"
+            )
+    return ns
+
+
+def combine(
+    left: Iterable[KnowledgeEntity],
+    right: Iterable[KnowledgeEntity],
+    op: str,
+    *,
+    default_confidence: str = "unproven",
+) -> tuple[KnowledgeEntity, ...]:
+    """Typed set operation on ONE namespace, keyed on ``identity`` (ADR-0007 §3.1).
+
+    ``op`` is ``"union"``, ``"intersection"`` or ``"difference"`` (left minus right).
+    Both operands MUST resolve to the same base namespace; a cross-namespace combine is
+    a category error and RAISES (INV-C3). Intersection attenuates: an identity present
+    in both carries ``min`` of the two copies' confidence (§5). Union/difference carry
+    each surviving entity's own confidence unchanged. Order is deterministic: left order
+    first, then (for union) the right-only entities in their own order."""
+    left = tuple(left)
+    right = tuple(right)
+    ns_left = _uniform_namespace(left, op=f"combine/{op}")
+    ns_right = _uniform_namespace(right, op=f"combine/{op}")
+    if ns_left is not None and ns_right is not None and ns_left != ns_right:
+        raise CompositionError(
+            f"combine/{op}: operands are in namespaces {ns_left!r} and {ns_right!r}; "
+            "a set operation is defined only within one namespace"
+        )
+    right_by_id = {e.identity: e for e in right}
+    left_ids = {e.identity for e in left}
+
+    if op == "union":
+        out = list(left)
+        out.extend(e for e in right if e.identity not in left_ids)
+        return tuple(out)
+    if op == "difference":
+        return tuple(e for e in left if e.identity not in right_by_id)
+    if op == "intersection":
+        out = []
+        for e in left:
+            match = right_by_id.get(e.identity)
+            if match is None:
+                continue
+            conf = confidence_min(
+                entity_confidence(e, default_confidence),
+                entity_confidence(match, default_confidence),
+            )
+            out.append(_with_confidence(e, conf))
+        return tuple(out)
+    raise CompositionError(
+        f"combine: unknown set operation {op!r} (expected union/intersection/difference)"
+    )
+
+
+def filter_entities(
+    entities: Iterable[KnowledgeEntity],
+    predicate: Callable[[KnowledgeEntity], bool],
+) -> tuple[KnowledgeEntity, ...]:
+    """Keep entities whose ``predicate`` holds (ADR-0007 §3.3 — a facet is reached by a
+    predicate on its own base entity, never a join). Pure subtraction: confidence is
+    unchanged (filtering welds no views) and input order is preserved."""
+    return tuple(e for e in entities if predicate(e))
+
+
+def attribute_predicate(name: str, op: str, value: Any) -> Callable[[KnowledgeEntity], bool]:
+    """Build a predicate over one attribute (ADR-0007 §11.5). Supports ``==`` / ``!=``
+    and the numeric comparators ``>`` / ``>=`` / ``<`` / ``<=``. A missing attribute
+    makes the predicate False (never a raise) — an entity lacking the tested attribute
+    simply does not match."""
+    comparators: dict[str, Callable[[Any, Any], bool]] = {
+        "==": lambda a, b: a == b,
+        "!=": lambda a, b: a != b,
+        ">": lambda a, b: a > b,
+        ">=": lambda a, b: a >= b,
+        "<": lambda a, b: a < b,
+        "<=": lambda a, b: a <= b,
+    }
+    cmp = comparators.get(op)
+    if cmp is None:
+        raise CompositionError(f"attribute_predicate: unknown operator {op!r}")
+
+    def _pred(entity: KnowledgeEntity) -> bool:
+        if name not in entity.attributes:
+            return False
+        try:
+            return cmp(entity.attributes[name], value)
+        except TypeError:
+            # incomparable types (e.g. numeric op on a string) → no match, never raise
+            return False
+
+    return _pred
+
+
+def relate(
+    left: Iterable[KnowledgeEntity],
+    right: Iterable[KnowledgeEntity],
+    relation: str,
+    resolver: BridgeResolver,
+    *,
+    keep: str = "left",
+    default_confidence: str = "unproven",
+) -> tuple[KnowledgeEntity, ...]:
+    """Bridged join across two namespaces through a DECLARED bridge (ADR-0007 §4).
+
+    ``relation`` names a bridge in :data:`BRIDGES`; ``resolver`` reports, per left
+    entity, the ``(target_identity, edge_confidence)`` pairs an IR fact links it to.
+    A left entity is kept iff at least one resolved target is present in ``right``
+    (a semi-join). ``keep`` selects which side survives: ``"left"`` returns the matched
+    left entities, ``"right"`` the matched right entities.
+
+    Confidence attenuates per §5: each surviving entity carries
+    ``min(its own conf, the matched partner's conf, the bridge edge's conf)`` — the
+    bridge edge is a term in the minimum (INV-C4), so a strong pair welded through a
+    weak edge is weak. The bridge and matched target are recorded in the result's
+    attributes for provenance (§8.1).
+
+    RAISES ``CompositionError`` if ``relation`` is not a declared bridge or does not
+    connect the two operands' namespaces (INV-C3) — never a silently-empty result."""
+    left = tuple(left)
+    right = tuple(right)
+    # An undeclared bridge name is a wiring fault regardless of operand emptiness.
+    bridge = next((b for b in BRIDGES if b.relation == relation), None)
+    if bridge is None:
+        raise CompositionError(
+            f"relate: {relation!r} is not a declared bridge (INV-C3: no implicit joins)"
+        )
+    if keep not in ("left", "right"):
+        raise CompositionError(f"relate: keep must be 'left' or 'right', got {keep!r}")
+    ns_left = _uniform_namespace(left, op=f"relate/{relation}")
+    ns_right = _uniform_namespace(right, op=f"relate/{relation}")
+    if ns_left is None or ns_right is None:
+        # one side empty: nothing to relate, and no namespaces to validate against
+        return ()
+    if {bridge.from_ns, bridge.to_ns} != {ns_left, ns_right}:
+        raise CompositionError(
+            f"relate: bridge {relation!r} connects {bridge.from_ns!r}↔{bridge.to_ns!r}, "
+            f"not the operands' namespaces {ns_left!r}↔{ns_right!r}"
+        )
+
+    right_by_id = {e.identity: e for e in right}
+    out: list[KnowledgeEntity] = []
+    seen_right: set[str] = set()
+    for src in left:
+        for target_id, edge_conf in resolver(src):
+            match = right_by_id.get(target_id)
+            if match is None:
+                continue
+            conf = confidence_min(
+                entity_confidence(src, default_confidence),
+                entity_confidence(match, default_confidence),
+                edge_conf,
+            )
+            if keep == "left":
+                out.append(
+                    _with_confidence(
+                        src, conf,
+                        **{ATTR_BRIDGED_VIA: relation, ATTR_BRIDGE_TARGET: target_id},
+                    )
+                )
+                break  # one qualifying edge is enough to keep the left entity
+            if match.identity not in seen_right:
+                seen_right.add(match.identity)
+                out.append(
+                    _with_confidence(
+                        match, conf,
+                        **{ATTR_BRIDGED_VIA: relation, ATTR_BRIDGE_TARGET: src.identity},
+                    )
+                )
+    return tuple(out)
+
+
+# ── Concrete bridge resolvers — wiring the two variable bridges to IR facts ─────────
+# `relate` consumes a BridgeResolver; these builders produce the concrete resolvers for
+# the `handled_by` and `reaches` bridges (§4). They EXTRACT nothing — the facts (the
+# handler symbol, the reach class) were produced by the endpoint / impact surfaces; a
+# resolver only PROJECTS them into (target, edge_confidence) pairs (INV-C1). The edge
+# confidence is exactly the uncertainty ASK already measures on these two joins
+# (endpoint resolution SIM-1/2; call-graph reach P1-A/B) — §5's `min` consumes it, it
+# does not originate it.
+
+# Impact reach class → `reaches`-bridge edge confidence. A direct caller edge is high;
+# an indirect (transitive / DI-mediated) edge is medium; anything else is unproven —
+# never silently high (INV-C7).
+_REACH_CONFIDENCE: dict[str, str] = {"direct": "high", "indirect": "medium"}
+
+
+def reach_confidence(reach: Optional[str]) -> str:
+    """The `reaches`-bridge edge confidence implied by an impact reach class (P1-A/B).
+    An unknown/absent reach degrades to `unproven`, the honest floor."""
+    return _REACH_CONFIDENCE.get(reach or "", "unproven")
+
+
+def endpoint_handler_symbol(endpoint: KnowledgeEntity) -> Optional[str]:
+    """The symbol an endpoint is `handled_by`. Reads the first-class ``handler_symbol``
+    attribute (ADR-0007 §11.1b); falls back to the identity only when the identity IS a
+    handler FQN (not the ``"METHOD path"`` / ``"/path"`` fallback form). Returns ``None``
+    for an endpoint with no known handler — an unresolved locator chain (SIM-1) has no
+    bridge edge, and that absence must not be guessed away."""
+    handler = endpoint.attributes.get(ATTR_HANDLER_SYMBOL)
+    if handler:
+        return handler
+    ident = endpoint.identity
+    if ident and " " not in ident and not ident.startswith("/"):
+        return ident
+    return None
+
+
+def handled_by_resolver(
+    edge_confidence: str | Callable[[KnowledgeEntity], str] = "high",
+) -> BridgeResolver:
+    """Concrete resolver for the `handled_by` bridge (endpoint → handler symbol, §4).
+
+    Yields one ``(handler_symbol, edge_confidence)`` pair per endpoint that has a known
+    handler, and nothing for an unresolved endpoint. ``edge_confidence`` defaults to
+    ``high`` (a direct ``@…Mapping``); pass a callable to lower it per endpoint for a
+    weak resolution (JAX-RS locator chain = medium/low, SIM-1), read from the endpoint's
+    own attributes — the resolver infers no weakening on its own."""
+    def _resolve(endpoint: KnowledgeEntity) -> Iterable[tuple[str, str]]:
+        handler = endpoint_handler_symbol(endpoint)
+        if not handler:
+            return ()
+        conf = edge_confidence(endpoint) if callable(edge_confidence) else edge_confidence
+        return ((handler, conf),)
+
+    return _resolve
+
+
+def stamp_reach_confidence(
+    entities: Iterable[KnowledgeEntity],
+) -> tuple[KnowledgeEntity, ...]:
+    """Return copies of impact ``dependent`` entities carrying a per-entity
+    ``confidence`` derived from their ``reach`` class (:func:`reach_confidence`), so the
+    `reaches` bridge's variable confidence participates as a real term in §5's ``min``.
+    An entity that already carries a confidence is left unchanged (never re-raised)."""
+    out: list[KnowledgeEntity] = []
+    for e in entities:
+        if e.attributes.get(ATTR_CONFIDENCE) in _CONF_RANK:
+            out.append(e)
+        else:
+            out.append(_with_confidence(e, reach_confidence(e.attributes.get("reach"))))
+    return tuple(out)

{sourcecode-2.6.0 → sourcecode-2.6.1}/src/sourcecode/retrieval/errors.py

@@ -39,3 +39,10 @@ class StepExecutionError(RetrievalError):
 class StepContractError(RetrievalError):
     """A step required a shared-context slot that a prior step did not produce (a plan
     composed steps in an invalid order)."""
+
+
+class CompositionError(RetrievalError):
+    """An illegal composition was requested (ADR-0007): a set operation across two
+    namespaces, a join over an undeclared bridge, or an unclassifiable kind. This is a
+    category error / plan-wiring fault — never a "no result" signal (INV-F1-6: a
+    composition fault is surfaced, not silently returned as an empty set)."""

{sourcecode-2.6.0 → sourcecode-2.6.1}/src/sourcecode/retrieval/steps_endpoint.py

@@ -83,7 +83,11 @@ def resolve_endpoint_contract(step: Step, ctx: "StepContext") -> None:
                 identity=_endpoint_id(ep),
                 kind="endpoint_contract",
                 score=0.0,
-                attributes={k: v for k, v in ep.items() if k not in ("source_file",)},
+                attributes={
+                    **{k: v for k, v in ep.items() if k not in ("source_file",)},
+                    # first-class handler symbol for the ADR-0007 handled_by bridge (§11.1b)
+                    "handler_symbol": ep.get("handler", "") or "",
+                },
             )
             for ep in matched
         ],
@@ -131,6 +135,8 @@ def resolve_endpoint_security(step: Step, ctx: "StepContext") -> None:
                 attributes={
                     "method": ep.method or "",
                     "path": ep.path or "",
+                    # first-class handler symbol for the ADR-0007 handled_by bridge (§11.1b)
+                    "handler_symbol": ep.handler_symbol or "",
                     "security": _security_summary(ep.security),
                     "findings": [f.pattern_id for f in findings if _finding_on_handler(f, {ep.handler_symbol})],
                 },