sourcecode 2.4.0__py3-none-any.whl → 2.5.1__py3-none-any.whl

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).
@@ -1967,6 +1967,22 @@ def _extract_class_type_refs(symbols: list[SymbolRecord]) -> dict[str, list[dict
     return out
 
 
+_LEADING_ANNOT_RE = re.compile(r'^\s*@\w+(?:\s*\([^()]*\))?\s*')
+
+
+def _strip_leading_annotations(line: str) -> str:
+    """Strip leading inline annotations from a declaration line so the residual
+    declaration is still detected (`@Autowired private Foo f;` -> `private Foo f;`).
+    A pure annotation line (`@Override`, `@GetMapping("/x")`) strips to empty.
+    Nested-paren annotation args (rare on fields) are left intact — the residual
+    just won't match a decl regex, which is safe (a miss, never a wrong entry)."""
+    prev: Optional[str] = None
+    while line != prev:
+        prev = line
+        line = _LEADING_ANNOT_RE.sub('', line, count=1)
+    return line.strip()
+
+
 def _extract_field_types(source: str) -> dict[str, dict[str, str]]:
     """{class_fqn -> {field_name -> declared_type_simple_name}} for EVERY field
     (annotated or plain), the fact that binds an invocation receiver to a typed
@@ -1994,8 +2010,17 @@ def _extract_field_types(source: str) -> dict[str, dict[str, str]]:
             if "*/" not in stripped:
                 in_block = True
             continue
-        if not stripped or stripped.startswith("//") or stripped.startswith("*") or stripped.startswith("@"):
+        if not stripped or stripped.startswith("//") or stripped.startswith("*"):
             continue
+        if stripped.startswith("@"):
+            # A field/type decl may carry leading inline annotations
+            # (`@Autowired private Foo f;`). Strip them so the residual declaration is
+            # still detected; a pure annotation line strips to empty and is skipped as
+            # before. Brace counting below runs on the stripped residual, so annotation
+            # string args containing braces (`@GetMapping("/a/{id}")`) never skew depth.
+            stripped = _strip_leading_annotations(stripped)
+            if not stripped:
+                continue
         if stripped.startswith("package "):
             package = stripped[8:].rstrip(";").strip()
             continue
@@ -4351,6 +4376,84 @@ def extract_file_ir(
     return _assemble(symbols, relations, changed_symbols, spring_summary, route_diffs)
 
 
+def _receiver_typed_call_edges(
+    body_facts: dict[str, list[dict]],
+    field_types: dict[str, dict[str, str]],
+    symbols: list[SymbolRecord],
+) -> list[RelationEdge]:
+    """Method-level `calls` edges for instance invocations through a typed field
+    receiver (`field.method(...)`).
+
+    The per-file scans in `_build_relations` resolve intra-class (`m()`/`this.m()`)
+    and static (`Type.method()`, uppercase receiver) calls, but a call through a
+    field-injected or plainly-typed dependency goes through a lowercase receiver
+    variable (`nominasCalculoService.aplicarMejora(...)`) and matched none of them.
+    A service reached only via an injected sibling therefore had NO inbound `calls`
+    edge: impact-chain found 0 callers and reported a false-confident "no blast
+    radius / low risk isolated change" — a dangerous false negative.
+
+    Joins facts already extracted (no new parse — Prime Directive):
+      - invocation atom  (owner method → {receiver, callee})            [body_facts]
+      - declared type of `receiver` on the owner's class                [field_types]
+      - target type resolved to a SINGLE in-repo class FQN              [symbols]
+      - callee resolved to that class's method(s) of that name          [symbols]
+
+    Emits `owner_method --calls--> target_class#callee` (every overload of the name —
+    arity is not resolved by name alone, matching `_intra_class_call_edges`). Anything
+    unresolved — a local variable (no field entry), a JDK/library type, an ambiguous
+    simple name, or a callee the target class does not declare — yields nothing: an
+    unresolved fact stays unresolved rather than being guessed (INV honesty). Runs as
+    a repo-wide post-pass because the target type + its methods live in other files.
+    """
+    if not body_facts or not field_types:
+        return []
+
+    # type simple name → in-repo class FQN(s); class FQN → {method name → [method FQN]}
+    type_simple_to_fqn: dict[str, list[str]] = {}
+    class_methods: dict[str, dict[str, list[str]]] = {}
+    for s in symbols:
+        if s.type in ("class", "interface", "enum", "record") and "#" not in s.symbol:
+            type_simple_to_fqn.setdefault(s.symbol.rsplit(".", 1)[-1], []).append(s.symbol)
+        elif s.symbol_kind == "method" and "#" in s.symbol:
+            cls = _enclosing_class(s.symbol)
+            name = s.symbol.rsplit("#", 1)[1]
+            class_methods.setdefault(cls, {}).setdefault(name, []).append(s.symbol)
+
+    edges: list[RelationEdge] = []
+    for owner_fqn in sorted(body_facts):
+        owner_cls = _enclosing_class(owner_fqn)
+        fmap = field_types.get(owner_cls)
+        if not fmap:
+            continue
+        for atom in body_facts[owner_fqn]:
+            if atom.get("fact") != "invocation":
+                continue
+            receiver, callee = atom.get("receiver"), atom.get("callee")
+            if not receiver or receiver == "this" or not callee:
+                continue
+            tsimple = fmap.get(receiver)
+            if not tsimple:
+                continue                       # not a typed field (local / unknown)
+            tfqns = type_simple_to_fqn.get(tsimple)
+            if not tfqns or len(tfqns) != 1:
+                continue                       # unresolved / ambiguous type → skip (honest)
+            target_cls = tfqns[0]
+            if target_cls == owner_cls:
+                continue                       # intra-class handled by _intra_class_call_edges
+            target_methods = class_methods.get(target_cls, {}).get(callee)
+            if not target_methods:
+                continue                       # callee not declared on the target type
+            for mfqn in target_methods:
+                edges.append(RelationEdge(
+                    from_symbol=owner_fqn,
+                    to_symbol=mfqn,
+                    type="calls",
+                    confidence="medium",
+                    evidence={"type": "method_call", "value": f"{receiver}.{callee}(...)"},
+                ))
+    return edges
+
+
 def build_repo_ir(
     file_paths: list[str],
     root: Path,
@@ -4495,6 +4598,17 @@ def build_repo_ir(
         _annotation_reference_edges(_ann_ref_sources, all_symbols, all_relations, _same_pkg_map)
     )
 
+    # Instance calls through a typed field receiver (`field.method(...)`). The per-file
+    # scans resolve intra-class and static (`Type.method()`) calls but never a call
+    # through a lowercase field-injected dependency, so a service reached only via an
+    # injected sibling had 0 inbound `calls` edges and impact-chain reported a
+    # false-confident "no blast radius". Repo-wide post-pass (target type + methods are
+    # cross-file). Gated on body facts + field types being present (emit_body_facts).
+    if emit_body_facts:
+        all_relations.extend(
+            _receiver_typed_call_edges(_all_body_facts, _all_field_types, all_symbols)
+        )
+
     spring_summary = _build_spring_summary(all_symbols)
 
     # Deduplicate relations

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