sourcecode 2.3.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

sourcecode/context_graph.py

@@ -407,7 +407,7 @@ class ContextGraph:
     __slots__ = (
         "_cir", "_nodes_by_fqn", "_nodes", "_build_ms",
         "_body_index", "_literal_index", "_guard_index", "_span_index",
-        "_class_type_index",
+        "_class_type_index", "_relations_all", "_symbols_sorted",
     )
 
     def __init__(self, cir: CanonicalRepositoryIR, *, build_ms: float = 0.0) -> None:
@@ -431,6 +431,14 @@ class ContextGraph:
             _node_to_symbol(n) for n in raw_nodes
         )
         self._nodes_by_fqn: dict[str, Symbol] = {s.fqn: s for s in self._nodes}
+        # Memoized full projections (the CIR is immutable for this graph's lifetime).
+        # `relations()`/`symbols()` are called once PER FILE by per-file consumers such as
+        # `_java_contract_from_graph`; without these caches each call re-converted every
+        # edge (`_edge_to_relation`) and re-sorted every node — an O(files × edges) blow-up
+        # that made cold `ask` / `ask --agent` take minutes on large repos. Built once,
+        # filtered cheaply thereafter.
+        self._relations_all: Optional[tuple[Relation, ...]] = None
+        self._symbols_sorted: Optional[tuple[Symbol, ...]] = None
 
     # -- construction -------------------------------------------------------
 
@@ -497,19 +505,18 @@ class ContextGraph:
         set. Results are sorted by FQN for determinism. This is the primitive
         the role-convenience methods below are thin sugar over.
         """
-        out: list[Symbol] = []
-        for s in self._nodes:
-            if kind is not None and s.kind != kind:
-                continue
-            if role is not None and s.role != role:
-                continue
-            if annotated_with is not None and not s.has_annotation(annotated_with):
-                continue
-            if name_contains is not None and name_contains not in s.fqn:
-                continue
-            out.append(s)
-        out.sort(key=lambda s: s.fqn)
-        return out
+        if self._symbols_sorted is None:
+            self._symbols_sorted = tuple(sorted(self._nodes, key=lambda s: s.fqn))
+        # Filter over the memoized fqn-sorted set (filtering preserves that order, so the
+        # result is identical to sorting after filtering — but the sort happens once).
+        return [
+            s
+            for s in self._symbols_sorted
+            if (kind is None or s.kind == kind)
+            and (role is None or s.role == role)
+            and (annotated_with is None or s.has_annotation(annotated_with))
+            and (name_contains is None or name_contains in s.fqn)
+        ]
 
     def types(self) -> list[Symbol]:
         """All class/interface/enum/annotation symbols, sorted by FQN."""
@@ -575,16 +582,17 @@ class ContextGraph:
     ) -> list[Relation]:
         """All relations matching the given filters (AND-combined), in the IR's
         stable edge order (already sorted from → type → to)."""
-        out: list[Relation] = []
-        for e in self._cir.call_graph:
-            if kind is not None and e.get("type") != kind:
-                continue
-            if source is not None and e.get("from") != source:
-                continue
-            if target is not None and e.get("to") != target:
-                continue
-            out.append(_edge_to_relation(e))
-        return out
+        if self._relations_all is None:
+            # Convert every edge ONCE; filtered calls then scan the cached Relation
+            # objects without re-running `_edge_to_relation` (the cold-path hotspot).
+            self._relations_all = tuple(_edge_to_relation(e) for e in self._cir.call_graph)
+        return [
+            r
+            for r in self._relations_all
+            if (kind is None or r.kind == kind)
+            and (source is None or r.source == source)
+            and (target is None or r.target == target)
+        ]
 
     # -- inheritance / implementation (reuses cir.implementation_graph) ------
 

sourcecode/explain.py

@@ -133,6 +133,30 @@ class ClassExplanation:
             "found": self.found,
         }
 
+    @classmethod
+    def from_dict(cls, d: dict) -> "ClassExplanation":
+        """Reconstruct from :meth:`to_dict` output (lossless round-trip).
+
+        The informational ``incoming_callers_note`` key is derived, not stored
+        on the instance, so it is dropped on the way back in.
+        """
+        return cls(
+            class_name=d.get("class_name", ""),
+            class_fqn=d.get("class_fqn", ""),
+            stereotype=d.get("stereotype", ""),
+            purpose=d.get("purpose", ""),
+            public_methods=list(d.get("public_methods", [])),
+            incoming_callers=list(d.get("incoming_callers", [])),
+            outgoing_deps=list(d.get("outgoing_deps", [])),
+            events_published=list(d.get("events_published", [])),
+            events_consumed=list(d.get("events_consumed", [])),
+            transactions=list(d.get("transactions", [])),
+            security_constraints=list(d.get("security_constraints", [])),
+            rest_endpoints=list(d.get("rest_endpoints", [])),
+            warnings=list(d.get("warnings", [])),
+            found=bool(d.get("found", True)),
+        )
+
 
 # ---------------------------------------------------------------------------
 # FQN resolution

sourcecode/repository_ir.py

@@ -742,7 +742,7 @@ def _extract_symbols(
     """Phase 1: Extract symbols from a Java source file.
 
     extra_capture: extra annotation tokens (e.g. custom security annotations like
-    "@M3FiltroSeguridad") whose argument lists must be stored in annotation_values
+    "@CustomSecurityAnnotation") whose argument lists must be stored in annotation_values
     even though they are not in the built-in _CAPTURE_ANN_ARGS set.
 
     Returns (package, symbols, raw_imports).

sourcecode/retrieval/__init__.py

@@ -0,0 +1,192 @@
+"""Semantic Retrieval Engine — Layer 3.5 (ADR-0001 / DESIGN-semantic-retrieval.md).
+
+Turns "ask a typed question of the repository's knowledge" into a first-class,
+reusable operation. This layer **queries already-built structured knowledge**; it
+does NOT extract, does NOT analyze source, does NOT build the Semantic IR or the
+ContextGraph, and does NOT compute new Evidence. Every answer is a *composition* of
+existing Knowledge-Layer capabilities (SemanticServices, ContextGraph, the derived
+engines, the Evidence Providers) acquired through the Knowledge Artifact Store.
+
+Public pipeline (design §3.1):
+
+    RetrievalRequest → IntentResolver → QueryPlanner → KnowledgeQuery
+                     → KnowledgeExecutor → KnowledgeResult (+ RetrievalEvidence)
+
+Phase 2 delivers the complete skeleton plus exactly one intent — ARCHITECTURAL_CORE —
+proven end-to-end over the existing ArchetypeClassifier / GraphEvidenceProvider. Adding
+a further intent is: (1) a new `RetrievalIntent` member, (2) a plan in `QueryPlanner`,
+(3) a (usually trivial) resolver strategy — the executor is unchanged when the plan
+composes existing steps.
+"""
+from __future__ import annotations
+
+from sourcecode.retrieval.context import KnowledgeContext
+from sourcecode.retrieval.errors import (
+    IncompletePlanError,
+    KnowledgeUnavailableError,
+    RetrievalError,
+    StepContractError,
+    StepExecutionError,
+    UnknownDimensionError,
+    UnknownIntentError,
+    UnknownStepError,
+)
+from sourcecode.retrieval.executor import KnowledgeExecutor
+from sourcecode.retrieval.planner import QueryPlanner
+from sourcecode.retrieval.query import (
+    BuildResult,
+    Characterize,
+    CollectEvidence,
+    CollectImpactEvidence,
+    ComputeBlastRadius,
+    KnowledgeQuery,
+    RankByRisk,
+    RankByScore,
+    ResolveDependents,
+    ResolveEndpoints,
+    ResolveIntegrations,
+    ResolveModules,
+    ResolveTarget,
+    ResolveTransactions,
+    ResolveTransactionFlow,
+    ResolveTransactionEntrypoints,
+    ResolvePropagation,
+    ResolveSecuritySurface,
+    ResolveSecurityChain,
+    ResolveValidationPoints,
+    RankByCriticality,
+    CollectSecurityEvidence,
+    ResolveEndpointInventory,
+    ResolveIntegrationInventory,
+    ResolveEventTopology,
+    CollectInterfaceEvidence,
+    ResolveScope,
+    ResolveSubsystemInventory,
+    ResolveSubsystemMembers,
+    ResolveModuleDependents,
+    ResolveModuleDependencies,
+    ResolveTypeDependents,
+    CollectStructureEvidence,
+    ResolveEndpointRef,
+    ResolveEndpointContract,
+    ResolveEndpointSecurity,
+    ResolveCallNeighborhood,
+    CollectEndpointEvidence,
+    ResolveExecutionPaths,
+    ResolveTransactionsReaching,
+    ResolveSubsystemCoupling,
+    CollectGraphEvidence,
+    Step,
+    step_from_dict,
+)
+from sourcecode.retrieval.runtime import (
+    QueryPlanRuntime,
+    RuntimeReport,
+    RuntimeResult,
+    StepContext,
+    StepRegistry,
+    StepTrace,
+)
+from sourcecode.retrieval.steps import default_registry
+from sourcecode.retrieval.request import (
+    RetrievalAnchor,
+    RetrievalIntent,
+    RetrievalOptions,
+    RetrievalRequest,
+)
+from sourcecode.retrieval.resolution import IntentResolver, ResolvedAnchor, ResolvedIntent
+from sourcecode.retrieval.result import (
+    Explanation,
+    KnowledgeEntity,
+    KnowledgeResult,
+    Observation,
+    Provenance,
+    RetrievalEvidence,
+)
+from sourcecode.retrieval.retriever import SemanticRetriever
+
+__all__ = [
+    # façade
+    "SemanticRetriever",
+    # request
+    "RetrievalRequest",
+    "RetrievalIntent",
+    "RetrievalAnchor",
+    "RetrievalOptions",
+    # resolution
+    "IntentResolver",
+    "ResolvedIntent",
+    "ResolvedAnchor",
+    # plan
+    "QueryPlanner",
+    "KnowledgeQuery",
+    "Step",
+    "Characterize",
+    "RankByScore",
+    "CollectEvidence",
+    "BuildResult",
+    "ResolveTarget",
+    "ComputeBlastRadius",
+    "ResolveDependents",
+    "ResolveEndpoints",
+    "ResolveIntegrations",
+    "ResolveTransactions",
+    "ResolveModules",
+    "RankByRisk",
+    "CollectImpactEvidence",
+    "ResolveTransactionFlow",
+    "ResolveTransactionEntrypoints",
+    "ResolvePropagation",
+    "ResolveSecuritySurface",
+    "ResolveSecurityChain",
+    "ResolveValidationPoints",
+    "RankByCriticality",
+    "CollectSecurityEvidence",
+    "ResolveEndpointInventory",
+    "ResolveIntegrationInventory",
+    "ResolveEventTopology",
+    "CollectInterfaceEvidence",
+    "ResolveScope",
+    "ResolveSubsystemInventory",
+    "ResolveSubsystemMembers",
+    "ResolveModuleDependents",
+    "ResolveModuleDependencies",
+    "ResolveTypeDependents",
+    "CollectStructureEvidence",
+    "ResolveEndpointRef",
+    "ResolveEndpointContract",
+    "ResolveEndpointSecurity",
+    "ResolveCallNeighborhood",
+    "CollectEndpointEvidence",
+    "ResolveExecutionPaths",
+    "ResolveTransactionsReaching",
+    "ResolveSubsystemCoupling",
+    "CollectGraphEvidence",
+    # execution / runtime
+    "KnowledgeExecutor",
+    "KnowledgeContext",
+    "QueryPlanRuntime",
+    "StepRegistry",
+    "StepContext",
+    "StepTrace",
+    "RuntimeReport",
+    "RuntimeResult",
+    "default_registry",
+    "step_from_dict",
+    # result
+    "KnowledgeResult",
+    "KnowledgeEntity",
+    "RetrievalEvidence",
+    "Observation",
+    "Explanation",
+    "Provenance",
+    # errors
+    "RetrievalError",
+    "UnknownIntentError",
+    "UnknownStepError",
+    "UnknownDimensionError",
+    "IncompletePlanError",
+    "KnowledgeUnavailableError",
+    "StepExecutionError",
+    "StepContractError",
+]

sourcecode/retrieval/context.py

@@ -0,0 +1,241 @@
+"""KnowledgeContext — the read-only bundle of ALREADY-BUILT knowledge (design §3.2, §4.1).
+
+The retrieval layer never extracts. It receives knowledge here and only queries it.
+Two ways to obtain a context:
+
+* **Injected** — construct with pre-built handles (a `SourceMap`, a `ContextGraph`).
+  This is how the pipeline is unit-tested: no scan, no parse, provably no source access.
+* **Acquired** — `KnowledgeContext.for_repo(root)` obtains existing knowledge using the
+  engine's OWN builders (the same AdaptiveScanner/ProjectDetector/GraphAnalyzer path the
+  `archetype` command uses, and the `context_cache` Knowledge Artifact Store for the
+  CIR). This is the acquisition BOUNDARY — it delegates to existing extractors; it adds
+  no retrieval-specific parser. The pipeline stages (resolver/planner/executor) never
+  call acquisition; they only read the handles exposed here.
+
+`ContextGraph` / `SemanticServices` are acquired **lazily** via the Knowledge Artifact
+Store so an intent that does not need them (like ARCHITECTURAL_CORE) pays nothing, while
+the wiring is present and exercised for future anchored intents.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from time import perf_counter
+from typing import TYPE_CHECKING, Any, Optional
+
+from sourcecode.retrieval.errors import KnowledgeUnavailableError
+
+if TYPE_CHECKING:
+    from sourcecode.context_graph import ContextGraph
+    from sourcecode.schema import SourceMap
+    from sourcecode.semantic_services import SemanticServices
+
+
+class KnowledgeContext:
+    """Handles to already-built knowledge. Read-only from the pipeline's view."""
+
+    def __init__(
+        self,
+        *,
+        root: Optional[Path] = None,
+        repo_root: Optional[Path] = None,
+        source_map: "Optional[SourceMap]" = None,
+        module_graph: Any = None,
+        context_graph: "Optional[ContextGraph]" = None,
+        file_list: Optional[list[str]] = None,
+        repo_ir: Optional[dict] = None,
+        spring_model: object = None,
+    ) -> None:
+        self._root = root
+        self._repo_root = repo_root or root
+        self._source_map = source_map
+        self._module_graph = module_graph
+        # True once the SourceMap/module_graph pair has been acquired (or injected), so a
+        # legitimately-None module_graph is not re-acquired on every access.
+        self._source_map_ready = source_map is not None
+        self._context_graph = context_graph
+        self._file_list = file_list
+        self._repo_ir = repo_ir
+        self._spring_model = spring_model
+        self._services: "Optional[SemanticServices]" = None
+        self._cache_render: Optional[str] = None
+        # B2: acquisition instrumentation — ordered (name, wall-time-ms) records of every
+        # lazy knowledge acquisition this context performed. Cross-cutting infra: it lets
+        # the runtime report attribute the real cost of acquiring knowledge separately from
+        # the step that happened to trigger it, without the runtime knowing any intent.
+        self._acquisitions: list[tuple[str, float]] = []
+
+    # ── read handles ────────────────────────────────────────────────────────────
+    @property
+    def root(self) -> Optional[Path]:
+        return self._root
+
+    @property
+    def source_map(self) -> "SourceMap":
+        """The built `SourceMap`, acquired lazily from the same AdaptiveScanner /
+        ProjectDetector / GraphAnalyzer path the `archetype` command uses. Acquired only
+        when an intent actually needs it (e.g. ARCHITECTURAL_*); tx / security / impact
+        intents never touch it and pay nothing for its ~7s construction (design B1)."""
+        if not self._source_map_ready:
+            self._acquire_source_map()
+        if self._source_map is None:
+            raise KnowledgeUnavailableError("no SourceMap was injected or acquired")
+        return self._source_map
+
+    @property
+    def module_graph(self) -> Any:
+        if not self._source_map_ready:
+            self._acquire_source_map()
+        return self._module_graph
+
+    @property
+    def context_graph(self) -> "ContextGraph":
+        """The built ContextGraph, fetched lazily from the Knowledge Artifact Store
+        (cached CIR — no re-parse on a hit). Never built by the retrieval steps."""
+        if self._context_graph is None:
+            self._acquire_context_graph()
+        assert self._context_graph is not None
+        return self._context_graph
+
+    @property
+    def services(self) -> "SemanticServices":
+        if self._services is None:
+            from sourcecode.semantic_services import SemanticServices
+
+            t0 = perf_counter()
+            self._services = SemanticServices(self.context_graph)
+            self._record_acquisition("services", t0)
+        return self._services
+
+    @property
+    def repo_ir(self) -> dict:
+        """The structural repo IR dict (from `build_repo_ir`), acquired lazily and shared
+        across steps. Same builder the legacy `impact` command uses — the retrieval layer
+        introduces no parser; it reuses this one. Built at most once per context."""
+        if self._repo_ir is None:
+            self._acquire_repo_ir()
+        assert self._repo_ir is not None
+        return self._repo_ir
+
+    @property
+    def spring_model(self) -> object:
+        """The `SpringSemanticModel` (tx index, endpoint index, call adjacency, bean/event
+        graphs), built lazily over the acquired ContextGraph's CIR — the SAME builder the
+        `spring-audit` command uses. Reused, never re-derived. Built at most once."""
+        if self._spring_model is None:
+            from sourcecode.spring_model import SpringSemanticModel
+
+            t0 = perf_counter()
+            self._spring_model = SpringSemanticModel.build(self.context_graph.cir)
+            self._record_acquisition("spring_model", t0)
+        return self._spring_model
+
+    @property
+    def cache_render(self) -> str:
+        """Human-free provenance of how the CIR was obtained (cache HIT/MISS/disabled),
+        or "not acquired" when the ContextGraph was never needed."""
+        return self._cache_render or "not acquired"
+
+    @property
+    def acquisitions(self) -> tuple[tuple[str, float], ...]:
+        """Ordered (name, wall-time-ms) records of the knowledge acquisitions performed
+        (B2). Empty when everything was injected (no acquisition happened)."""
+        return tuple(self._acquisitions)
+
+    def _record_acquisition(self, name: str, t0: float) -> None:
+        self._acquisitions.append((name, (perf_counter() - t0) * 1000.0))
+
+    # ── lazy ContextGraph acquisition (Knowledge Artifact Store) ────────────────
+    def _acquire_context_graph(self) -> None:
+        if self._root is None:
+            raise KnowledgeUnavailableError(
+                "cannot acquire a ContextGraph without a repository root"
+            )
+        from sourcecode.context_cache import get_or_build_cir
+        from sourcecode.context_graph import ContextGraph
+        from sourcecode.repository_ir import find_java_files
+
+        t0 = perf_counter()
+        files = self._file_list if self._file_list is not None else find_java_files(self._root)
+        cir, lookup = get_or_build_cir(self._repo_root or self._root, self._root, files)
+        self._context_graph = ContextGraph.from_cir(cir)
+        self._cache_render = lookup.render()
+        self._record_acquisition("context_graph", t0)
+
+    def _acquire_source_map(self) -> None:
+        if self._root is None:
+            raise KnowledgeUnavailableError(
+                "cannot acquire a SourceMap without a repository root"
+            )
+        t0 = perf_counter()
+        self._source_map, self._module_graph = _acquire_source_map(self._root)
+        self._source_map_ready = True
+        self._record_acquisition("source_map", t0)
+
+    def _acquire_repo_ir(self) -> None:
+        if self._root is None:
+            raise KnowledgeUnavailableError("cannot acquire a repo IR without a repository root")
+        from sourcecode.repository_ir import build_repo_ir, find_java_files
+
+        t0 = perf_counter()
+        files = self._file_list if self._file_list is not None else find_java_files(self._root)
+        self._repo_ir = build_repo_ir(files, self._root)
+        self._record_acquisition("repo_ir", t0)
+
+    # ── acquisition boundary ────────────────────────────────────────────────────
+    @classmethod
+    def for_repo(cls, root: Path) -> "KnowledgeContext":
+        """Obtain existing knowledge for a repository via the engine's own builders.
+
+        This mirrors the `archetype` command's SourceMap construction exactly — it
+        reuses AdaptiveScanner / ProjectDetector / GraphAnalyzer; it does not introduce
+        a retrieval-specific parser. Both the SourceMap and the ContextGraph are left for
+        lazy acquisition — built only if an intent actually needs them (design B1).
+        """
+        target = Path(root).resolve()
+        return cls(root=target, repo_root=target)
+
+
+def _acquire_source_map(target: Path) -> "tuple[SourceMap, Any]":
+    """Build a SourceMap + module graph using the existing analyzers (acquisition
+    boundary). Best-effort on the module graph, exactly like the `archetype` command:
+    on any failure it degrades to name-mass-only (module_graph=None)."""
+    from sourcecode.adaptive_scanner import AdaptiveScanner
+    from sourcecode.detectors import ProjectDetector, build_default_detectors
+    from sourcecode.repo_classifier import RepoClassifier
+    from sourcecode.schema import SourceMap
+    from sourcecode.tree_utils import flatten_file_tree
+
+    topology = RepoClassifier().classify(target)
+    scanner = AdaptiveScanner(target, topology=topology, base_depth=12)
+    file_tree = scanner.scan_tree()
+    manifests = scanner.find_manifests()
+
+    detector = ProjectDetector(build_default_detectors())
+    stacks, entry_points, _ = detector.detect(target, file_tree, manifests)
+    stacks, project_type = detector.classify_results(file_tree, stacks, entry_points)
+
+    sm = SourceMap(
+        file_tree=file_tree,
+        stacks=stacks,
+        project_type=project_type,
+        entry_points=entry_points,
+    )
+    sm.file_paths = [p.replace("\\", "/") for p in flatten_file_tree(file_tree)]
+    java = next((s for s in stacks if s.stack == "java"), None)
+    if java is not None:
+        sm.packaging = getattr(java, "packaging", None)
+
+    module_graph = None
+    try:
+        from sourcecode.graph_analyzer import GraphAnalyzer
+
+        module_graph = GraphAnalyzer(max_nodes=1200, max_edges=4000).analyze(
+            target, file_tree, detail="full", entry_points=entry_points,
+        )
+        if module_graph is not None:
+            sm.module_graph = module_graph
+            sm.module_graph_summary = module_graph.summary
+    except Exception:
+        module_graph = None
+
+    return sm, module_graph

sourcecode/retrieval/errors.py

@@ -0,0 +1,41 @@
+"""Typed errors for the Semantic Retrieval Engine.
+
+All are programming/wiring faults (an unknown intent, a plan the executor cannot
+interpret) — never a "no result" signal. Absence of knowledge is expressed in the
+typed KnowledgeResult (empty entities, `signals_missing`), not by raising.
+"""
+from __future__ import annotations
+
+
+class RetrievalError(Exception):
+    """Base class for every retrieval-layer fault."""
+
+
+class UnknownIntentError(RetrievalError):
+    """No resolver/planner strategy is registered for the requested intent."""
+
+
+class UnknownStepError(RetrievalError):
+    """The executor has no handler for a step type in the plan (plan/executor drift)."""
+
+
+class UnknownDimensionError(RetrievalError):
+    """A Characterize step named an archetype dimension the engine does not produce."""
+
+
+class IncompletePlanError(RetrievalError):
+    """A plan finished without producing a KnowledgeResult (missing BuildResult step)."""
+
+
+class KnowledgeUnavailableError(RetrievalError):
+    """A required knowledge handle was neither injected nor acquirable."""
+
+
+class StepExecutionError(RetrievalError):
+    """A step handler raised an unexpected (non-retrieval) error while running. Wraps
+    the original cause; the failing step is recorded in the runtime trace."""
+
+
+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)."""

sourcecode/retrieval/executor.py

@@ -0,0 +1,51 @@
+"""KnowledgeExecutor — thin façade over the Query Plan Runtime (design §4.5).
+
+Fase 4 moved all execution logic into `QueryPlanRuntime` + the step handlers in
+`steps.py`. This façade preserves the stable public surface: `execute()` returns just the
+typed `KnowledgeResult` (as consumers and Phase-2 tests expect), while `run()` exposes the
+full `RuntimeResult` (result + execution report with per-step trace and profiling).
+
+The executor owns no execution logic — it delegates to the Runtime. That is why adding an
+intent never touches this file.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from sourcecode.retrieval.context import KnowledgeContext
+from sourcecode.retrieval.query import KnowledgeQuery
+from sourcecode.retrieval.request import RetrievalOptions
+from sourcecode.retrieval.resolution import ResolvedIntent
+from sourcecode.retrieval.result import KnowledgeResult
+from sourcecode.retrieval.runtime import QueryPlanRuntime, RuntimeResult
+
+
+class KnowledgeExecutor:
+    """Runs a `KnowledgeQuery` over a `KnowledgeContext` via the Query Plan Runtime."""
+
+    def __init__(self, runtime: Optional[QueryPlanRuntime] = None) -> None:
+        self._runtime = runtime or QueryPlanRuntime()
+
+    @property
+    def runtime(self) -> QueryPlanRuntime:
+        return self._runtime
+
+    def run(
+        self,
+        query: KnowledgeQuery,
+        ctx: KnowledgeContext,
+        resolved: Optional[ResolvedIntent] = None,
+        options: Optional[RetrievalOptions] = None,
+    ) -> RuntimeResult:
+        """Execute and return the full runtime result (typed result + execution report)."""
+        return self._runtime.run(query, ctx, resolved, options)
+
+    def execute(
+        self,
+        query: KnowledgeQuery,
+        ctx: KnowledgeContext,
+        resolved: Optional[ResolvedIntent] = None,
+        options: Optional[RetrievalOptions] = None,
+    ) -> KnowledgeResult:
+        """Execute and return only the typed `KnowledgeResult`."""
+        return self._runtime.run(query, ctx, resolved, options).result