katalyst-plugin-context 0.2.1a11__tar.gz → 0.2.1a13__tar.gz

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: katalyst-plugin-context
-Version: 0.2.1a11
+Version: 0.2.1a13
 Summary: Katalyst context plugin — the right context from the taxonomy for an agent working on a node
 Author: eSimplicity
 License: Proprietary
 Requires-Python: <3.14,>=3.13
 Requires-Dist: click>=8.0
 Requires-Dist: jsonschema>=4
-Requires-Dist: katalyst-engine<6,>=5
+Requires-Dist: katalyst-engine<6,>=5.1
 Requires-Dist: katalyst-taxonomy-cli<3,>=2
 Requires-Dist: katalyst-taxonomy-mcp<5,>=4
-Requires-Dist: katalyst-taxonomy<6,>=5
+Requires-Dist: katalyst-taxonomy<6,>=5.1

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-plugin-context"
-version = "0.2.1a11"
+version = "0.2.1a13"
 description = "Katalyst context plugin — the right context from the taxonomy for an agent working on a node"
 license = { text = "Proprietary" }
 requires-python = ">=3.13,<3.14"
@@ -9,8 +9,8 @@ authors = [
 ]
 dependencies = [
     # Bounded to the config-rooted runtime this plugin is written against.
-    "katalyst-taxonomy>=5,<6",
-    "katalyst-engine>=5,<6",
+    "katalyst-taxonomy>=5.1,<6",
+    "katalyst-engine>=5.1,<6",
     # Its MCP tools and REST routes use the server's response helpers; its command, the CLI context.
     "katalyst-taxonomy-mcp>=4,<5",
     "katalyst-taxonomy-cli>=2,<3",

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/src/katalyst_plugin_context/adapters/runtime_graph.py

@@ -6,12 +6,23 @@ the profile's filters (:func:`katalyst_taxonomy.services.filters.visible_nodes`)
 kept only when both its ends are visible. A reference into another backend is stored as
 ``backend:fqtn`` and keyed that way, so an edge held by one backend can reach a node of
 another.
+
+Cross-backend edges (#418)
+--------------------------
+A backend's ``list_relationships`` resolves references against *its own* documents only, so a
+reference with a ``backend:`` prefix that names a node in another backend silently produces no
+edge.  After collecting per-backend edges, :func:`build_graph` runs a second pass that
+resolves declared references (``FieldRef``) over the aggregated document set — the same set
+lint uses — and emits every edge a backend could not emit on its own.  The resolver is
+``engine.references.resolve_cross_references``, so the graph and the lint gate read
+identical outcomes.
 """
 
 from __future__ import annotations
 
+import logging
 from collections.abc import Callable, Iterable, Sequence
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 from katalyst_engine.model.node import Node
 from katalyst_taxonomy.engine.accessors import (
@@ -19,14 +30,23 @@ from katalyst_taxonomy.engine.accessors import (
     get_markdown_body,
     get_node_backend,
 )
-from katalyst_taxonomy.engine.identity import split_backend_prefix
+from katalyst_taxonomy.engine.identity import (
+    split_backend_prefix,
+    with_backend_prefix,
+)
 from katalyst_taxonomy.engine.qualification import split_kind_selector
+from katalyst_taxonomy.engine.references import resolve_cross_references
 from katalyst_taxonomy.ports.backend import TaxonomyBackend
 
 from katalyst_plugin_context.domain.graph import Edge, Graph, GraphNode
 
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from katalyst_engine.schema.registry import SchemaRegistry
+
 __all__ = ["Carriers", "build_graph", "graph_from"]
 
+logger = logging.getLogger(__name__)
+
 #: What a kind can carry: the relationship types it holds, each with the kinds it may point at
 #: (empty: any kind).
 Carriers = Callable[[str], Sequence[tuple[str, frozenset[str]]]]
@@ -136,14 +156,92 @@ def _of_kind(kinds: list[str], address: str) -> list[str]:
     return kinds if selected is None else [kind for kind in kinds if kind == selected]
 
 
+# ---------------------------------------------------------------------------
+# Cross-backend edge stitching (#418)
+# ---------------------------------------------------------------------------
+
+
+#: An edge by the addresses of its ends: ``((backend, fqtn), rel_type, (backend, fqtn))``.
+EdgeKey = tuple[tuple[str, str], str, tuple[str, str]]
+
+
+def _edge_key(holder: str, source: str, rel_type: str, target: str) -> EdgeKey:
+    """*source* and *target* as their backend and qualified name, *holder* filling in a
+    backend an address does not name."""
+    return (_address(holder, source), rel_type, _address(holder, target))
+
+
+def _stitch_cross_backend_edges(
+    registry: SchemaRegistry,
+    loaded: Sequence[tuple[str, Node]],
+    existing: set[EdgeKey],
+) -> list[tuple[str, str, str, str]]:
+    """Emit edges that per-backend resolution missed because the target is elsewhere.
+
+    Each backend builds its reference index from its own documents only, so a value
+    like ``ric:ric-testing`` (target in the ``ric`` backend) produces no edge when
+    resolved inside the ``golden`` backend.  This function resolves every declared
+    ``FieldRef`` over the **aggregated** document set — the same corpus lint uses —
+    and returns the edges no backend emitted.
+
+    *existing* holds the edges the backends already produced, keyed by the addresses of
+    their ends (:func:`_edge_key`), so an edge is never duplicated and two backends'
+    edges between nodes of the same names are never mistaken for each other.
+
+    Each returned tuple is ``(holder_backend, source, rel_type, target)``, both ends
+    prefixed with their backend.
+    """
+    all_docs = tuple(doc for _, doc in loaded)
+    holder_of = {id(doc): holder for holder, doc in loaded}
+
+    def fqtn_of(doc: Node) -> str:
+        return doc.fqn or doc.name
+
+    def address_of(doc: Node) -> tuple[str, str]:
+        # A document without a backend stamp belongs to the backend that held it.
+        return (get_node_backend(doc) or holder_of.get(id(doc), ""), fqtn_of(doc))
+
+    extra: list[tuple[str, str, str, str]] = []
+    for resolution in resolve_cross_references(registry, all_docs, fqtn_of=fqtn_of):
+        target = resolution.target
+        rel_type = resolution.rel_type
+        if target is None or not rel_type:
+            continue
+
+        source_address = address_of(resolution.source)
+        target_address = address_of(target)
+        key: EdgeKey = (source_address, rel_type, target_address)
+        if key in existing:
+            continue
+
+        source_backend = source_address[0]
+        extra.append(
+            (
+                source_backend,
+                with_backend_prefix(source_backend, source_address[1]),
+                rel_type,
+                with_backend_prefix(target_address[0], target_address[1]),
+            )
+        )
+        existing.add(key)
+
+    if extra:
+        logger.debug("Cross-backend stitching added %d edge(s)", len(extra))
+    return extra
+
+
 def build_graph(
     sources: Iterable[tuple[str, TaxonomyBackend]],
     *,
     profile: str | None = None,
     carriers: Carriers | None = None,
+    registry: SchemaRegistry | None = None,
 ) -> Graph:
     """Read every backend in *sources* once and build the graph the profile may see.
 
+    When *registry* is supplied, a second pass resolves cross-backend references that
+    no single backend could resolve on its own (#418).
+
     Raises:
         PermissionDeniedError: If the profile may not read a backend (as every read does).
     """
@@ -157,6 +255,12 @@ def build_graph(
             (name, rel.source_fqtn, rel.rel_type, rel.target_fqtn)
             for rel in backend.list_relationships()
         )
+
+    # --- Cross-backend edge stitching (#418) ---
+    if registry is not None and len({name for name, _ in loaded}) > 1:
+        existing = {_edge_key(*rel) for rel in relationships}
+        relationships.extend(_stitch_cross_backend_edges(registry, loaded, existing))
+
     visible = {id(doc) for doc in visible_nodes(None, [doc for _, doc in loaded], profile=profile)}
     hidden = (
         (get_node_backend(doc) or holder, doc.fqn or doc.name)

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/src/katalyst_plugin_context/composition.py

@@ -43,8 +43,12 @@ def service_for(
     *,
     profile: str | None,
 ) -> ContextService:
-    """The service over what *sources* hold, under the profile named *profile*."""
+    """The service over what *sources* hold, under the profile named *profile*.
+
+    The *registry* is forwarded to :func:`build_graph` so cross-backend references
+    can be resolved over the aggregated document set (#418).
+    """
     config, active = plugin_config(profile)
     schema = RegistrySchema(registry)
-    graph = build_graph(sources, profile=active, carriers=schema.carried)
+    graph = build_graph(sources, profile=active, carriers=schema.carried, registry=registry)
     return ContextService(registry, graph, config=config, profile=active)

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/src/katalyst_plugin_context/domain/context.py

@@ -15,7 +15,7 @@ from dataclasses import dataclass, field
 from typing import Any, Protocol, cast
 
 from katalyst_plugin_context.domain.graph import Graph, GraphNode
-from katalyst_plugin_context.domain.paths import OUT, Step, parse_path, path_text
+from katalyst_plugin_context.domain.paths import OUT, Inverses, Step, parse_path, path_text
 from katalyst_plugin_context.domain.policy import DETAIL_LEVELS, FULL, REFS, SUMMARY, Policy
 from katalyst_plugin_context.domain.settings import ItemHints, View
 
@@ -55,6 +55,7 @@ class Schema(Protocol):
     """What the context needs to know about kinds and relationships."""
 
     parent_rel: str
+    inverses: Inverses
 
     def kind_label(self, kind: str) -> str: ...
     def hints(self, kind: str) -> ItemHints: ...
@@ -125,6 +126,7 @@ def _walk(
     inherited: bool,
     parent_rel: str,
     collect_every_level: bool,
+    inverses: Inverses,
 ) -> list[_Arrival]:
     """Every node reached from *start* by following *steps*, with the hops that reached it.
 
@@ -136,7 +138,8 @@ def _walk(
     """
     frontier: list[tuple[str, tuple[_Hop, ...]]] = [(start, ())]
     arrivals: list[_Arrival] = []
-    for index, step in enumerate(steps):
+    # A step on the computed side of a declared inverse is the stored side walked the other way.
+    for index, step in enumerate(inverses.resolve(s) for s in steps):
         nxt: list[tuple[str, tuple[_Hop, ...]]] = []
         for current, hops in frontier:
             on_branch = {start, *(h.target for h in hops)}
@@ -530,6 +533,7 @@ def _collect(
                 inherited=start != focus,
                 parent_rel=schema.parent_rel,
                 collect_every_level=source.repeat > 1,
+                inverses=schema.inverses,
             )
             for arrival in arrivals:
                 node = graph.nodes[arrival.key]

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/src/katalyst_plugin_context/domain/paths.py

@@ -14,13 +14,15 @@ relationship or kind.
 from __future__ import annotations
 
 import re
-from dataclasses import dataclass
+from collections.abc import Mapping
+from dataclasses import dataclass, field
 
 __all__ = [
     "DIRECTIONS",
     "IN",
     "OUT",
     "STEP_RE",
+    "Inverses",
     "PathSyntaxError",
     "Step",
     "parse_path",
@@ -79,6 +81,34 @@ class Step:
         return self.rel
 
 
+@dataclass(frozen=True, slots=True)
+class Inverses:
+    """The declared inverses a path may be written with, as graph labels.
+
+    A schema stores one side of a pair (``BLOCKS``) and computes the other (``BLOCKED_BY``).
+    Only the stored side is an edge in the graph, so a step on the computed side means the
+    stored one walked the other way: ``BLOCKED_BY:out`` is ``BLOCKS:in``, kind qualifier
+    kept. A symmetric relationship reads the same from either end, so a step on it names no
+    direction. Nothing here knows any relationship: the schema supplies the pairs.
+    """
+
+    computed: Mapping[str, str] = field(default_factory=lambda: dict[str, str]())
+    """Computed graph label to the graph label of its stored side."""
+
+    symmetric: frozenset[str] = frozenset()
+    """Graph labels that read the same from either end."""
+
+    def resolve(self, step: Step) -> Step:
+        """*step* as the graph holds it: the stored side, walked the right way."""
+        stored = self.computed.get(step.rel)
+        if stored is not None:
+            flipped = {OUT: IN, IN: OUT}.get(step.direction or "")
+            return Step(stored, flipped, step.kinds)
+        if step.rel in self.symmetric and step.direction is not None:
+            return Step(step.rel, None, step.kinds)
+        return step
+
+
 def parse_step(text: str) -> Step:
     """Parse ``REL[:DIR[:KIND,...]]``.
 

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/src/katalyst_plugin_context/domain/policy.py

@@ -29,7 +29,7 @@ from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
 from typing import Any, cast
 
-from katalyst_plugin_context.domain.paths import Step, parse_step
+from katalyst_plugin_context.domain.paths import Inverses, Step, parse_step
 
 __all__ = [
     "BUILTIN",
@@ -84,16 +84,22 @@ class Policy:
     default_inherit: bool = True
     layers: list[str] = field(default_factory=lambda: [BUILTIN])
     notes: list[dict[str, Any]] = field(default_factory=lambda: list[dict[str, Any]]())
+    inverses: Inverses = field(default_factory=Inverses)
+    """The schema's declared inverses: a pattern written on the computed side of a pair
+    means the stored side walked the other way."""
 
     # ── visibility ──────────────────────────────────────────────────────
 
     def hidden_by(self, rel: str, direction: str, kind: str) -> str | None:
-        """The layer that hides traversing *rel* *direction* to a *kind*, or ``None``."""
+        """The layer that hides traversing *rel* *direction* to a *kind*, or ``None``.
+
+        *rel* and *direction* are the edge as the graph holds it, the stored side.
+        """
         for label, patterns in self.allow:
-            if not any(p.matches(rel, direction, kind) for p in patterns):
+            if not any(self.inverses.resolve(p).matches(rel, direction, kind) for p in patterns):
                 return label
         for label, pattern in self.deny:
-            if pattern.matches(rel, direction, kind):
+            if self.inverses.resolve(pattern).matches(rel, direction, kind):
                 return label
         return None
 
@@ -106,11 +112,12 @@ class Policy:
         A step is hidden when an allow list has nothing overlapping it, or a deny pattern
         covers it entirely (same or wider relationship, direction and kinds).
         """
+        step = self.inverses.resolve(step)
         for label, patterns in self.allow:
-            if not any(p.overlaps(step) for p in patterns):
+            if not any(self.inverses.resolve(p).overlaps(step) for p in patterns):
                 return label
         for label, pattern in self.deny:
-            if _covers(pattern, step):
+            if _covers(self.inverses.resolve(pattern), step):
                 return label
         return None
 
@@ -199,13 +206,16 @@ def _strings(value: object) -> list[str]:
     return [str(v) for v in cast("list[object]", value)] if isinstance(value, list) else []
 
 
-def fold(layers: Sequence[Layer], *, views: Sequence[str] = ()) -> Policy:
+def fold(
+    layers: Sequence[Layer], *, views: Sequence[str] = (), inverses: Inverses | None = None
+) -> Policy:
     """The effective policy *layers* give, in order, after the built-in one.
 
     *views* are the names of the views the node's kind declares, the only names
-    ``always_include`` may hold.
+    ``always_include`` may hold. *inverses* are the schema's declared inverses, so a
+    pattern written on the computed side of a pair applies to the stored side.
     """
-    policy = Policy()
+    policy = Policy(inverses=inverses or Inverses())
     declared_views = set(views)
     for layer in layers:
         declares = bool(layer.policy) or bool(layer.defaults)
@@ -223,7 +233,10 @@ def _fold_paths(policy: Policy, layer: Layer) -> None:
         patterns = tuple(parse_step(text) for text in _strings(paths["allow"]))
         for pattern in patterns:
             for label, earlier in policy.allow:
-                if not any(p.overlaps(pattern) for p in earlier):
+                if not any(
+                    policy.inverses.resolve(p).overlaps(policy.inverses.resolve(pattern))
+                    for p in earlier
+                ):
                     policy.notes.append(
                         _note(
                             layer.label,

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/src/katalyst_plugin_context/lint.py

@@ -26,7 +26,7 @@ from katalyst_engine.schema.definition import VALUE_FLAG_BLOCKING
 from katalyst_engine.schema.registry import SchemaRegistry
 from katalyst_taxonomy.plugins.extensions import LintFinding, LintSubject
 
-from katalyst_plugin_context.domain.paths import IN, OUT, PathSyntaxError, Step, path_text
+from katalyst_plugin_context.domain.paths import IN, OUT, Inverses, PathSyntaxError, Step, path_text
 from katalyst_plugin_context.domain.policy import Layer, Policy, fold
 from katalyst_plugin_context.domain.settings import View, views_from
 from katalyst_plugin_context.service import NAMESPACE, RegistrySchema
@@ -96,10 +96,12 @@ class ContextPolicyRule:
                     )
                     if section is not None
                 ]
-                policy = fold(layers, views=sorted(views))
-                declared = _declared_always(layers, views)
+                policy = fold(layers, views=sorted(views), inverses=schema.inverses)
+                declared = _declared_always(layers, views, schema.inverses)
                 for scope, profile_layers in _profile_scopes(config, kind, wing):
-                    narrowed = fold([*layers, *profile_layers], views=sorted(views))
+                    narrowed = fold(
+                        [*layers, *profile_layers], views=sorted(views), inverses=schema.inverses
+                    )
                     for message in _unreachable(reach, kind, views, declared, narrowed, scope):
                         finding(f"kind {kind!r}: {message}", "warning", kind=kind)
             except (PathSyntaxError, ValueError, TypeError) as exc:
@@ -153,10 +155,10 @@ class ContextPolicyRule:
                     )
                     if section is not None
                 ]
-                declared = _declared_always(layers, views)
+                declared = _declared_always(layers, views, schema.inverses)
                 label = f"node:{document.fqn}"
                 layers.append(_layer(label, cast("Mapping[str, Any]", own)))
-                policy = fold(layers, views=sorted(views))
+                policy = fold(layers, views=sorted(views), inverses=schema.inverses)
             except (PathSyntaxError, ValueError, TypeError) as exc:
                 finding(
                     f"{document.fqn}: spec.extensions.{NAMESPACE}: {exc}",
@@ -172,9 +174,11 @@ class ContextPolicyRule:
         return findings
 
 
-def _declared_always(layers: Sequence[Layer], views: Mapping[str, View]) -> tuple[str, ...]:
+def _declared_always(
+    layers: Sequence[Layer], views: Mapping[str, View], inverses: Inverses
+) -> tuple[str, ...]:
     """The views the schema's layers always include."""
-    return fold(layers, views=sorted(views)).always or ()
+    return fold(layers, views=sorted(views), inverses=inverses).always or ()
 
 
 def _rule_may_match(match: Mapping[str, Any], kind: str, wing: str) -> bool:

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/src/katalyst_plugin_context/service.py

@@ -24,7 +24,7 @@ from katalyst_plugin_context.domain.context import (
 )
 from katalyst_plugin_context.domain.graph import Graph, GraphNode
 from katalyst_plugin_context.domain.markdown import render_map, render_result
-from katalyst_plugin_context.domain.paths import PathSyntaxError, parse_path
+from katalyst_plugin_context.domain.paths import Inverses, PathSyntaxError, parse_path
 from katalyst_plugin_context.domain.policy import Layer, Policy, fold
 from katalyst_plugin_context.domain.settings import ItemHints, View, item_hints, views_from
 from katalyst_plugin_context.schema import (
@@ -49,6 +49,15 @@ class RegistrySchema:
         self._registry = registry
         definition = registry.get_relationship("child_of")
         self.parent_rel = definition.graph_label if definition is not None else CHILD_OF
+        relationships = registry.all_relationships()
+        self.inverses = Inverses(
+            computed={
+                r.graph_label: r.inverse_label
+                for r in relationships
+                if r.computed and r.inverse_label is not None
+            },
+            symmetric=frozenset(r.graph_label for r in relationships if r.symmetric),
+        )
         self._hints: dict[str, ItemHints] = {}
 
     def sections(self, kind: str) -> tuple[Mapping[str, Any] | None, Mapping[str, Any] | None, str]:
@@ -232,7 +241,7 @@ class ContextService:
                 wing_label=f"wing:{wing}",
                 kind_label=f"kind:{node.kind}",
             )
-            policy = fold(layers, views=sorted(views))
+            policy = fold(layers, views=sorted(views), inverses=self._schema.inverses)
         except PathSyntaxError as exc:
             raise ContextError("VALIDATION_ERROR", str(exc)) from exc
         return policy, views

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/tests/context_support.py

@@ -88,8 +88,15 @@ def registry(
     *,
     unit_settings: Mapping[str, Any] | None = None,
     wing_settings: Mapping[str, Any] | None = None,
+    with_inverse: bool = False,
+    gadget_settings: Mapping[str, Any] | None = None,
 ) -> SchemaRegistry:
-    """The test schema. *unit_settings* replace the unit kind's context section."""
+    """The test schema. *unit_settings* replace the unit kind's context section.
+
+    With *with_inverse*, ``USED_BY`` is the computed inverse of ``USES_GADGET`` (a gadget
+    reads the methods and units that use it) and ``RELATED_TO`` is symmetric.
+    *gadget_settings* replace the gadget kind's context section.
+    """
     reg = SchemaRegistry()
     tree = {"views": {"governance": GOVERNANCE}, "policy": {"always_include": ["governance"]}}
     reg.register_wing(
@@ -140,7 +147,20 @@ def registry(
         _kind(
             "gadget",
             wing="craft",
-            settings={
+            refs=(
+                FieldRef(
+                    field_name="used_by",
+                    target_kinds=("method", "unit"),
+                    rel_type="USED_BY",
+                    computed=True,
+                    inverse_of="USES_GADGET",
+                ),
+            )
+            if with_inverse
+            else (),
+            settings=gadget_settings
+            if gadget_settings is not None
+            else {
                 "views": {"methods": GADGET_METHODS},
                 "policy": {"always_include": ["methods"]},
             },
@@ -204,6 +224,21 @@ def registry(
             description="Decisions that govern a node",
         )
     )
+    if with_inverse:
+        for name, inverse, computed, symmetric in (
+            ("uses_gadget", "used_by", False, False),
+            ("used_by", "uses_gadget", True, False),
+            ("related_to", None, False, True),
+        ):
+            reg.register_relationship(
+                RelationshipDefinition(
+                    identity=Identity(kind="relationship_definition", name=name),
+                    describes_kind=name,
+                    inverse=inverse,
+                    computed=computed,
+                    symmetric=symmetric,
+                )
+            )
     return reg
 
 

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/tests/test_context.py

@@ -643,3 +643,107 @@ def test_fields_in_markdown_stay_within_the_budget_json_measures(detail: str, bu
     text = svc.markdown_for_result(METHOD, as_markdown)
     for item in as_json["items"]:
         assert ("Runs inside its worktree" in text) == ("checks" in item.get("fields", {}))
+
+
+# ── declared inverses ────────────────────────────────────────────────────
+
+HAMMER = "repo:hammer"
+RELATED: tuple[tuple[str, str, str], ...] = (("m-strict", "RELATED_TO", "m-loose"),)
+
+
+def _inverse_service(**settings: Any) -> Any:
+    """The test schema with the inverse pair, and the gadget's own views left out unless given."""
+    settings.setdefault("gadget_settings", {})
+    return service(registry(with_inverse=True, **settings), edges=EDGES + RELATED)
+
+
+def test_a_step_on_the_computed_slot_is_the_stored_slot_walked_the_other_way() -> None:
+    from katalyst_plugin_context.domain.paths import Inverses
+
+    inverses = Inverses(computed={"USED_BY": "USES_GADGET"}, symmetric=frozenset({"RELATED_TO"}))
+
+    assert inverses.resolve(parse_step("USED_BY:out")) == Step("USES_GADGET", "in")
+    assert inverses.resolve(parse_step("USED_BY:in:method")) == Step(
+        "USES_GADGET", "out", frozenset({"method"})
+    )
+    assert inverses.resolve(parse_step("USED_BY")) == Step("USES_GADGET")
+    assert inverses.resolve(parse_step("USES_GADGET:in")) == Step("USES_GADGET", "in")
+    assert inverses.resolve(parse_step("RELATED_TO:out")) == Step("RELATED_TO")
+
+
+def test_a_path_on_the_computed_slot_returns_what_the_stored_slot_walked_in_returns() -> None:
+    svc = _inverse_service()
+
+    stored = svc.query(HAMMER, ContextRequest(paths=("USES_GADGET:in",)))
+    computed = svc.query(HAMMER, ContextRequest(paths=("USED_BY:out",)))
+
+    assert _names(computed, view=None) == _names(stored, view=None)
+    assert set(_names(computed, view=None)) >= {
+        "repo:north.east.core",
+        "repo:m-strict",
+        "repo:m-loose",
+    }
+
+
+def test_the_kind_qualifier_is_kept_on_the_computed_slot() -> None:
+    svc = _inverse_service()
+
+    stored = svc.query(HAMMER, ContextRequest(paths=("USES_GADGET:in:method",)))
+    computed = svc.query(HAMMER, ContextRequest(paths=("USED_BY:out:method",)))
+
+    assert _names(computed, view=None) == _names(stored, view=None)
+    assert set(_names(computed, view=None)) == {"repo:m-strict", "repo:m-loose"}
+
+
+def test_the_computed_slot_walked_in_is_the_stored_slot_walked_out() -> None:
+    svc = _inverse_service()
+
+    stored = svc.query("repo:m-strict", ContextRequest(paths=("USES_GADGET:out",)))
+    computed = svc.query("repo:m-strict", ContextRequest(paths=("USED_BY:in",)))
+
+    assert _names(computed, view=None) == _names(stored, view=None) == ["repo:hammer"]
+
+
+def test_a_path_of_both_spellings_reaches_the_same_items() -> None:
+    svc = _inverse_service()
+
+    stored = svc.query(HAMMER, ContextRequest(paths=("USES_GADGET:in/INCLUDES_METHOD:in",)))
+    computed = svc.query(HAMMER, ContextRequest(paths=("USED_BY:out/INCLUDES_METHOD:in",)))
+
+    assert _names(computed, view=None) == _names(stored, view=None) == ["repo:b-all"]
+
+
+def test_a_view_may_be_written_with_the_computed_spelling() -> None:
+    view = {**{"title": "Users", "inherit": False, "detail": "summary", "priority": 1}}
+    svc = _inverse_service(
+        gadget_settings={
+            "views": {"users": {**view, "paths": ["USED_BY:out:method"]}},
+            "policy": {"always_include": ["users"]},
+        }
+    )
+
+    result = svc.query(HAMMER, ContextRequest())
+
+    assert set(_names(result, view="users")) == {"repo:m-strict", "repo:m-loose"}
+
+
+def test_a_deny_on_the_computed_slot_hides_the_stored_slot_walked_the_other_way() -> None:
+    svc = service(
+        registry(with_inverse=True, gadget_settings={}),
+        edges=EDGES,
+        config={"policy": {"paths": {"deny": ["USED_BY:out"]}}},
+    )
+
+    result = svc.query(HAMMER, ContextRequest(paths=("USES_GADGET:in",)))
+
+    assert _names(result, view=None) == []
+
+
+def test_a_symmetric_relationship_reads_the_same_from_either_end() -> None:
+    svc = _inverse_service()
+
+    from_source = svc.query("repo:m-strict", ContextRequest(paths=("RELATED_TO:out",)))
+    from_target = svc.query("repo:m-loose", ContextRequest(paths=("RELATED_TO:out",)))
+
+    assert _names(from_source, view=None) == ["repo:m-loose"]
+    assert _names(from_target, view=None) == ["repo:m-strict"]

katalyst_plugin_context-0.2.1a13/tests/test_cross_backend_edges.py

@@ -0,0 +1,287 @@
+# pyright: reportPrivateUsage=false
+"""Tests for cross-backend edge stitching (#418).
+
+When multiple backends contribute documents, a reference like ``beta:d-cross``
+(target in the ``beta`` backend) silently produces no edge when resolved inside the
+``alpha`` backend, because each backend resolves references against its own documents
+only.  The stitching pass in :func:`build_graph` resolves every declared
+``FieldRef`` over the aggregated document set and emits the missing edges.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import MagicMock
+
+from context_support import node, registry
+from katalyst_engine.model.node import Node
+from katalyst_plugin_context.adapters.runtime_graph import (
+    _edge_key,
+    _stitch_cross_backend_edges,
+    build_graph,
+)
+from katalyst_plugin_context.domain.graph import Graph
+from katalyst_taxonomy.engine.accessors import set_node_backend
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _stamped(n: Node, backend: str) -> Node:
+    """Return *n* stamped as owned by *backend*."""
+    return set_node_backend(n, backend)
+
+
+def _all_edges(g: Graph) -> list[tuple[str, str, str]]:
+    """Collect every edge in a graph as (source, rel, target) triples."""
+    seen: set[tuple[str, str, str]] = set()
+    for key in g.nodes:
+        for neighbour in g.neighbours(key):
+            if neighbour.direction == "out":
+                triple = (key, neighbour.rel, neighbour.other)
+            else:
+                triple = (neighbour.other, neighbour.rel, key)
+            seen.add(triple)
+    return sorted(seen)
+
+
+def _two_backend_corpus() -> tuple[list[tuple[str, Node]], list[tuple[str, Node]]]:
+    """A corpus split across backends ``alpha`` and ``beta``.
+
+    alpha has:
+        region "north" with decisions=["beta:d-cross"] (target in beta)
+        zone "east" under north
+
+    beta has:
+        decision "d-cross" (the target alpha references)
+        decision "d-local" (unreferenced)
+    """
+    north = _stamped(
+        node("region", "north", decisions=["beta:d-cross"], rules=[]),
+        "alpha",
+    )
+    east = _stamped(
+        node("zone", "east", "north", parents={"node": "north"}, decisions=[], rules=[]),
+        "alpha",
+    )
+    d_cross = _stamped(
+        node("decision", "d-cross", title="Cross-backend decision", status="accepted"),
+        "beta",
+    )
+    d_local = _stamped(
+        node("decision", "d-local", title="Local decision", status="accepted"),
+        "beta",
+    )
+    alpha_docs: list[tuple[str, Node]] = [("alpha", north), ("alpha", east)]
+    beta_docs: list[tuple[str, Node]] = [("beta", d_cross), ("beta", d_local)]
+    return alpha_docs, beta_docs
+
+
+def _make_backend(
+    docs: list[tuple[str, Node]], rels: list[tuple[str, str, str]] | None = None
+) -> Any:
+    """A mock TaxonomyBackend that returns the given documents and relationships."""
+    backend: Any = MagicMock()
+    backend.load_documents.return_value = [doc for _, doc in docs]
+    if rels:
+        rel_objects: list[Any] = []
+        for src, rel, tgt in rels:
+            r: Any = MagicMock()
+            r.source_fqtn = src
+            r.rel_type = rel
+            r.target_fqtn = tgt
+            rel_objects.append(r)
+        backend.list_relationships.return_value = rel_objects
+    else:
+        backend.list_relationships.return_value = []
+    return backend
+
+
+# ---------------------------------------------------------------------------
+# _stitch_cross_backend_edges
+# ---------------------------------------------------------------------------
+
+
+class TestStitchCrossBackendEdges:
+    """Unit tests for the stitching function itself."""
+
+    def test_emits_edge_for_cross_backend_reference(self) -> None:
+        """A reference from alpha to beta:d-cross produces an edge."""
+        alpha_docs, beta_docs = _two_backend_corpus()
+        loaded = [*alpha_docs, *beta_docs]
+        reg = registry()
+
+        extra = _stitch_cross_backend_edges(reg, loaded, existing=set())
+
+        cross_edges = [(src, rel, tgt) for _, src, rel, tgt in extra if "d-cross" in tgt]
+        assert len(cross_edges) >= 1, f"Expected cross-backend edge to d-cross, got {extra}"
+        assert any(rel == "GOVERNED_BY" for _, rel, _ in cross_edges)
+
+    def test_does_not_duplicate_existing_edges(self) -> None:
+        """Edges the backends already produced are not emitted again."""
+        alpha_docs, beta_docs = _two_backend_corpus()
+        loaded = [*alpha_docs, *beta_docs]
+        reg = registry()
+
+        extra_first = _stitch_cross_backend_edges(reg, loaded, existing=set())
+        assert len(extra_first) > 0, "Precondition: should have found cross-backend edges"
+
+        existing = {_edge_key(*edge) for edge in extra_first}
+        extra_second = _stitch_cross_backend_edges(reg, loaded, existing=existing)
+        assert extra_second == [], f"Should not duplicate, got {extra_second}"
+
+    def test_no_edges_when_all_references_are_same_backend(self) -> None:
+        """When all references resolve within the same backend, nothing new is emitted."""
+        from context_support import DOCUMENTS, EDGES
+
+        loaded: list[tuple[str, Node]] = [("repo", doc) for doc in DOCUMENTS]
+        reg = registry()
+
+        existing = {_edge_key("repo", src, rel, tgt) for src, rel, tgt in EDGES}
+        extra = _stitch_cross_backend_edges(reg, loaded, existing=existing)
+        assert extra == []
+
+    def test_skips_unresolvable_references(self) -> None:
+        """A reference to a node that doesn't exist in any backend produces no edge."""
+        north = _stamped(
+            node("region", "north", decisions=["beta:nonexistent"], rules=[]),
+            "alpha",
+        )
+        d_other = _stamped(
+            node("decision", "d-other", title="Other"),
+            "beta",
+        )
+        loaded: list[tuple[str, Node]] = [("alpha", north), ("beta", d_other)]
+        reg = registry()
+
+        extra = _stitch_cross_backend_edges(reg, loaded, existing=set())
+        assert extra == []
+
+    def test_edge_carries_correct_backend_prefixes(self) -> None:
+        """Emitted edges prefix both source and target with their backend."""
+        alpha_docs, beta_docs = _two_backend_corpus()
+        loaded = [*alpha_docs, *beta_docs]
+        reg = registry()
+
+        extra = _stitch_cross_backend_edges(reg, loaded, existing=set())
+
+        for _holder, source, _rel, target in extra:
+            if "d-cross" in target:
+                assert "beta:" in target, f"Target should be beta-prefixed: {target}"
+                assert "alpha:" in source, f"Source should be alpha-prefixed: {source}"
+
+
+# ---------------------------------------------------------------------------
+# build_graph integration
+# ---------------------------------------------------------------------------
+
+
+class TestBuildGraphCrossBackend:
+    """Integration tests: build_graph with a registry resolves cross-backend edges."""
+
+    def test_cross_backend_edges_appear_in_graph(self) -> None:
+        """build_graph with registry stitches cross-backend edges into the result."""
+        alpha_docs, beta_docs = _two_backend_corpus()
+        reg = registry()
+
+        g = build_graph(
+            [("alpha", _make_backend(alpha_docs)), ("beta", _make_backend(beta_docs))],
+            registry=reg,
+        )
+
+        edges = _all_edges(g)
+        cross_edges = [(s, r, t) for s, r, t in edges if "d-cross" in t]
+        assert len(cross_edges) >= 1, f"Expected cross-backend edge to d-cross. All edges: {edges}"
+
+    def test_no_stitching_without_registry(self) -> None:
+        """Without a registry, build_graph does not attempt stitching."""
+        alpha_docs, beta_docs = _two_backend_corpus()
+
+        g = build_graph(
+            [("alpha", _make_backend(alpha_docs)), ("beta", _make_backend(beta_docs))],
+            registry=None,
+        )
+
+        edges = _all_edges(g)
+        cross_edges = [(s, r, t) for s, r, t in edges if "d-cross" in t]
+        assert cross_edges == [], (
+            f"Without registry, should not have cross-backend edges. Edges: {edges}"
+        )
+
+    def test_no_stitching_with_single_backend(self) -> None:
+        """With only one backend, stitching is skipped even with a registry."""
+        alpha_docs, _ = _two_backend_corpus()
+        reg = registry()
+
+        g = build_graph(
+            [("alpha", _make_backend(alpha_docs))],
+            registry=reg,
+        )
+
+        edges = _all_edges(g)
+        cross_edges = [(s, r, t) for s, r, t in edges if "d-cross" in t]
+        assert cross_edges == []
+
+    def test_existing_same_backend_edges_preserved(self) -> None:
+        """Edges within a single backend still work after stitching is added."""
+        alpha_docs, beta_docs = _two_backend_corpus()
+        reg = registry()
+
+        alpha_rels = [("north.east", "CHILD_OF", "north")]
+        g = build_graph(
+            [
+                ("alpha", _make_backend(alpha_docs, alpha_rels)),
+                ("beta", _make_backend(beta_docs)),
+            ],
+            registry=reg,
+        )
+
+        edges = _all_edges(g)
+        child_edges = [(s, r, t) for s, r, t in edges if r == "CHILD_OF"]
+        assert len(child_edges) >= 1, f"Expected CHILD_OF edge to survive. All edges: {edges}"
+
+    def test_a_same_named_edge_in_another_backend_does_not_hide_a_cross_backend_one(
+        self,
+    ) -> None:
+        """foe's own x -> y edge and ric's x -> foe:y are two edges, both kept."""
+        foe_x = _stamped(node("region", "x", decisions=["y"], rules=[]), "foe")
+        foe_y = _stamped(node("decision", "y", title="Y", status="accepted"), "foe")
+        ric_x = _stamped(node("region", "x", decisions=["foe:y"], rules=[]), "ric")
+        g = build_graph(
+            [
+                (
+                    "foe",
+                    _make_backend([("foe", foe_x), ("foe", foe_y)], [("x", "GOVERNED_BY", "y")]),
+                ),
+                ("ric", _make_backend([("ric", ric_x)])),
+            ],
+            registry=registry(),
+        )
+
+        edges = _all_edges(g)
+        assert ("foe:x", "GOVERNED_BY", "foe:y") in edges, edges
+        assert ("ric:x", "GOVERNED_BY", "foe:y") in edges, edges
+
+
+class TestUnstampedDocuments:
+    """A document with no backend stamp belongs to the backend that held it."""
+
+    def test_an_unstamped_source_is_stitched_under_its_holder(self) -> None:
+        ric_x = node("region", "x", decisions=["foe:y"], rules=[])
+        foe_y = _stamped(node("decision", "y", title="Y", status="accepted"), "foe")
+        loaded: list[tuple[str, Node]] = [("ric", ric_x), ("foe", foe_y)]
+
+        extra = _stitch_cross_backend_edges(registry(), loaded, existing=set())
+
+        assert ("ric", "ric:x", "GOVERNED_BY", "foe:y") in extra, extra
+
+    def test_an_unstamped_source_gets_its_edge_in_the_graph(self) -> None:
+        ric_x = node("region", "x", decisions=["foe:y"], rules=[])
+        foe_y = _stamped(node("decision", "y", title="Y", status="accepted"), "foe")
+        g = build_graph(
+            [("ric", _make_backend([("ric", ric_x)])), ("foe", _make_backend([("foe", foe_y)]))],
+            registry=registry(),
+        )
+
+        assert ("ric:x", "GOVERNED_BY", "foe:y") in _all_edges(g)

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a13}/tests/test_lint.py

@@ -133,3 +133,28 @@ def test_a_node_hiding_its_always_view_is_a_warning(tmp_path: Path) -> None:
         "north.east.core: node:north.east.core hides always-included view 'governance' path "
         "'GOVERNED_BY:out'"
     ]
+
+
+def test_a_view_path_may_use_either_spelling_of_a_declared_inverse(tmp_path: Path) -> None:
+    def views(path: str) -> dict[str, Any]:
+        return {
+            "views": {"users": {**GOVERNANCE, "paths": [path]}},
+            "policy": {"always_include": ["users"]},
+        }
+
+    for path in ("USES_GADGET:in", "USED_BY:out"):
+        reg = registry(with_inverse=True, gadget_settings=views(path))
+        found = ContextPolicyRule(reg).check(_subject(tmp_path))
+        assert [f.message for f in found if f.severity == "error"] == [], path
+
+
+def test_a_path_naming_neither_spelling_is_still_an_error(tmp_path: Path) -> None:
+    settings = {
+        "views": {"users": {**GOVERNANCE, "paths": ["USED_NOWHERE:out"]}},
+        "policy": {"always_include": ["users"]},
+    }
+    found = ContextPolicyRule(registry(with_inverse=True, gadget_settings=settings)).check(
+        _subject(tmp_path)
+    )
+
+    assert any("USED_NOWHERE" in f.message and f.severity == "error" for f in found)