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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: katalyst-plugin-context
-Version: 0.2.1a11
+Version: 0.2.1a12
 Summary: Katalyst context plugin — the right context from the taxonomy for an agent working on a node
 Author: eSimplicity
 License: Proprietary

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

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-plugin-context"
-version = "0.2.1a11"
+version = "0.2.1a12"
 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"

{katalyst_plugin_context-0.2.1a11 → katalyst_plugin_context-0.2.1a12}/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.1a12}/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.1a12/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)