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

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

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: katalyst-plugin-context
-Version: 0.2.1a12
+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.1a12 → katalyst_plugin_context-0.2.1a13}/pyproject.toml

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