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

sourcecode/__init__.py

@@ -4,4 +4,4 @@ ASK Engine is the product. ``ask`` is the canonical CLI command; ``sourcecode``
 the legacy compatibility alias and the Python/PyPI package name. See
 docs/PRODUCT_IDENTITY.md (normative)."""
 
-__version__ = "2.3.0"
+__version__ = "2.5.0"

sourcecode/archetype.py

@@ -80,6 +80,17 @@ _MIN_PRIMARY_SCORE = 0.05
 # A winner must clear this absolute score (not just the top-2 margin) to earn
 # medium/high confidence — a near-floor lone candidate stays "low".
 _MIN_CONFIDENT_SCORE = 0.5
+# Fraction of engine's positive contribution discounted for a non-runnable artifact
+# (P0 library de-bias): an engine-like internal core is expected of a library, so it is not
+# discriminating. Tuned so a clear library (no app/server/servlet entry) is not confidently
+# labeled an engine, while runnable systems (which never trigger the gate) are untouched.
+_LIBRARY_ENGINE_DISCOUNT = 0.55
+# Entry kinds that make a repo a runnable system (an app/server/servlet/daemon) rather
+# than a consumable library. Used to gate the library de-bias (P0).
+_RUNNABLE_ENTRY_KINDS = frozenset({
+    "application", "bootstrap", "main", "server", "daemon", "worker",
+    "mvc_controller", "jax_rs_controller", "servlet", "security_filter", "filter",
+})
 
 
 @dataclass
@@ -389,6 +400,41 @@ class ArchetypeClassifier:
             f"{f.module_count} modules; distributed mass ≈ {cm['distributed']:.0%}",
             1.5, multi, max(cm["distributed"], 0.1))
         self._apply_graph_evidence("software_archetype", cands, f)
+        # ── Library de-bias (P0) ────────────────────────────────────────────────
+        # A consumable JVM artifact — `jar` packaging with no server/bootstrap/application
+        # entry — is a library, not a runnable system. But a library naturally exhibits
+        # engine-like topology: a few core API types with high fan-in, tightly-coupled
+        # internals (SCCs), hub concentration. Those graph metrics (`graph_*`) otherwise
+        # label every library an "engine" (observed: jobrunr → engine(high), library 0.3).
+        # Correct it transparently: (1) add a packaging-grounded library signal that does
+        # not depend on an `api/` package existing; (2) append a NAMED negative evidence row
+        # that discounts most of engine's graph-derived score, since topological hubness in
+        # a library is expected and therefore not discriminating for "engine".
+        # A runnable/web entry of ANY kind (an app bootstrap, an HTTP controller, a
+        # servlet, a daemon) means the repo is a system you run, not a library you depend
+        # on. Packaging is unreliable here (gradle libs report no packaging; maven
+        # aggregators report `pom`), so the entry-kind surface is the robust signal.
+        is_runnable = any(k in f.entry_kinds for k in _RUNNABLE_ENTRY_KINDS)
+        is_library_shaped = not is_runnable
+        if is_library_shaped:
+            add("library", "no_runnable_entry",
+                f"entry kinds {sorted(f.entry_kinds) or 'none'} — no app/server/servlet "
+                "bootstrap; a consumable artifact, not a runnable system",
+                3.0, 1.0, 0.7)
+            # A library legitimately owns an engine-like core (storage/kernel mass, hub
+            # topology, SCCs) — that is what a library *is*. Discount most of engine's
+            # positive evidence for a non-runnable artifact so its internal machinery does
+            # not, alone, promote it to "engine". Transparent: a named negative row.
+            engine_positive = sum(max(0.0, e.contribution) for e in cands["engine"])
+            if engine_positive > 0:
+                discount = engine_positive * _LIBRARY_ENGINE_DISCOUNT
+                cands["engine"].append(Evidence(
+                    "library_core_discount",
+                    "non-runnable artifact: an engine-like internal core (storage/kernel "
+                    "mass, hubs, SCCs) is expected of a library and is not, alone, evidence "
+                    "of an engine product",
+                    1.0, 1.0, 1.0, -discount,
+                ))
         return self._resolve("software_archetype", cands, f)
 
     def _architectural_style(self, f: _Features) -> DimensionResult:

sourcecode/cli.py

@@ -248,6 +248,8 @@ _SUBCOMMANDS: frozenset[str] = frozenset(
         "chunk-file",
         # Experimental evidence-based archetype (parallel to legacy)
         "archetype",
+        # Experimental Semantic Retrieval Engine (Layer 3.5)
+        "retrieve",
     }
 )
 
@@ -600,6 +602,12 @@ app.add_typer(cache_app, name="cache")
 auth_app = typer.Typer(help="Authentication: status, logout.", rich_markup_mode="rich")
 app.add_typer(auth_app, name="auth")
 
+retrieve_app = typer.Typer(
+    help="[EXPERIMENTAL] Semantic Retrieval Engine — typed knowledge queries.",
+    rich_markup_mode="rich",
+)
+app.add_typer(retrieve_app, name="retrieve")
+
 
 def _maybe_show_telemetry_notice() -> None:
     """Show first-run telemetry notice once, on interactive TTYs only.
@@ -3887,7 +3895,7 @@ def endpoints_cmd(
     as policy "none_detected"):
       {
         "customSecurityAnnotations": [
-          {"shortName": "M3FiltroSeguridad",
+          {"shortName": "CustomSecurityAnnotation",
            "resourceParam": "nombreRecurso", "levelParam": "nivelRequerido"}
         ]
       }
@@ -5341,6 +5349,7 @@ def explain_cmd(
     from sourcecode.context_graph import ContextGraph
     from sourcecode.spring_model import SpringSemanticModel
     from sourcecode.explain import explain_class
+    from sourcecode import context_cache as _ctxcache
 
     if not class_name.strip():
         _emit_error_json(
@@ -5383,14 +5392,27 @@ def explain_cmd(
         )
         raise typer.Exit(code=1)
 
+    # AI Context Cache — operates at the *knowledge* level: it caches the
+    # reusable Canonical IR (the expensive Java parse), keyed only by knowledge
+    # state, not by command. explain then derives its answer cheaply from that
+    # shared CIR. The same cached CIR is reused for free by any other command.
+    # Provider-agnostic and best-effort: any fault degrades to a fresh build.
     _prog = Progress()
     _prog.start(f"explaining {class_name} ({len(file_list)} files)")
+    _cc_look = None
     try:
-        cir = ContextGraph.build(file_list, target).cir
+        try:
+            cir, _cc_look = _ctxcache.get_or_build_cir(
+                _resolve_repo_root(target), target, file_list
+            )
+        except Exception:
+            cir = ContextGraph.build(file_list, target).cir  # fallback: never break explain
         model = SpringSemanticModel.build(cir)
         explanation = explain_class(class_name, cir, model)
     finally:
         _prog.finish()
+    if _cc_look is not None:
+        typer.echo(_cc_look.render(), err=True)
 
     if format == "json":
         output = _json.dumps(explanation.to_dict(), indent=2, ensure_ascii=False)
@@ -5544,7 +5566,12 @@ def fix_bug_cmd(
     ctx: typer.Context,
     path: Path = typer.Argument(
         Path("."),
-        help="Repository root (default: current directory)",
+        help="Repository root (default: current directory), OR the bug symptom when a second path argument follows (sibling-consistent `fix-bug <symptom> <path>`).",
+    ),
+    path2: Optional[Path] = typer.Argument(
+        None,
+        help="Repository root when the first argument is the bug symptom.",
+        show_default=False,
     ),
     symptom: Optional[str] = typer.Option(
         None, "--symptom", "-s",
@@ -5582,7 +5609,16 @@ def fix_bug_cmd(
       ask impact <target>   — Propagate impact from a specific class
       ask onboard .         — Full architecture context first
     """
-    # Detect misuse: `fix-bug "symptom text" /path` — path arg looks like a symptom.
+    # Sibling-consistent positional form: `fix-bug <symptom> <path>` (mirrors
+    # `impact <target> <path>` / `explain <symbol> <path>`). When a second positional is
+    # supplied, the first positional is the symptom and the second is the repository path.
+    if path2 is not None:
+        if not symptom:
+            symptom = str(path)
+        path = path2
+
+    # Detect misuse: `fix-bug "symptom text"` alone — the single positional looks like a
+    # symptom, not a path.
     _path_str = str(path)
     _path_looks_like_symptom = (
         not Path(_path_str).exists()
@@ -6495,6 +6531,410 @@ def archetype_cmd(
         typer.echo(out)
 
 
+def _run_retrieval_intent(
+    intent_name: str,
+    path: Path,
+    output_path: Optional[Path],
+    trace: bool,
+    anchors: tuple = (),
+) -> None:
+    """Shared adapter for the experimental Semantic Retrieval commands. The CLI is one
+    thin surface over the CLI-independent engine: it submits a typed RetrievalRequest and
+    prints the structured JSON result (optionally with the runtime trace/profiling)."""
+    import json as _json
+    from sourcecode.retrieval import (
+        RetrievalAnchor,
+        RetrievalIntent,
+        RetrievalRequest,
+        SemanticRetriever,
+    )
+
+    target = Path(path).resolve()
+    retriever = SemanticRetriever.for_repo(target)
+    request = RetrievalRequest(
+        intent=RetrievalIntent(intent_name),
+        anchors=tuple(RetrievalAnchor(kind=k, raw=v) for k, v in anchors),
+    )
+    run = retriever.run(request)
+    payload: dict = run.result.to_dict()
+    if trace:
+        payload = {"result": payload, "runtime": run.report.to_dict()}
+    out = _json.dumps(payload, indent=2, ensure_ascii=False)
+    if output_path:
+        _safe_write_file(output_path, out)
+        typer.echo(f"Retrieval result written to {output_path}")
+    else:
+        typer.echo(out)
+
+
+@retrieve_app.command("architectural-core")
+def retrieve_architectural_core_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write output to a file instead of stdout."
+    ),
+    trace: bool = typer.Option(
+        False, "--trace", help="Include the Query Plan Runtime trace + per-step profiling."
+    ),
+) -> None:
+    """[EXPERIMENTAL] Retrieve the ARCHITECTURAL_CORE characterization as structured JSON.
+
+    A Semantic Retrieval query (Layer 3.5): it consults ONLY existing Knowledge-Layer
+    capabilities (ArchetypeClassifier + GraphEvidenceProvider) — no extraction, no new
+    heuristics, no natural language. Output is fully typed/structured JSON.
+    """
+    _run_retrieval_intent("architectural-core", path, output_path, trace)
+
+
+@retrieve_app.command("architectural-style")
+def retrieve_architectural_style_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(
+        None, "--output", "-o", help="Write output to a file instead of stdout."
+    ),
+    trace: bool = typer.Option(
+        False, "--trace", help="Include the Query Plan Runtime trace + per-step profiling."
+    ),
+) -> None:
+    """[EXPERIMENTAL] Retrieve the ARCHITECTURAL_STYLE characterization as structured JSON.
+
+    Same Query Plan Runtime as architectural-core — this intent differs only in its
+    declarative plan (the archetype dimension). No runtime code changes to add it.
+    """
+    _run_retrieval_intent("architectural-style", path, output_path, trace)
+
+
+@retrieve_app.command("deployment-shape")
+def retrieve_deployment_shape_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] DEPLOYMENT_SHAPE — the deployment-shape archetype dimension.
+    Same plan as architectural-core, different ArchetypeClassifier dimension."""
+    _run_retrieval_intent("deployment-shape", path, output_path, trace)
+
+
+@retrieve_app.command("primary-interface")
+def retrieve_primary_interface_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] PRIMARY_INTERFACE — the primary-interface archetype dimension.
+    Same plan as architectural-core, different ArchetypeClassifier dimension."""
+    _run_retrieval_intent("primary-interface", path, output_path, trace)
+
+
+@retrieve_app.command("blast-radius")
+def retrieve_blast_radius_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN) or file to analyze."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] BLAST_RADIUS — structural change impact (dependents + risk) for a
+    target, via the Semantic Retrieval Engine. Reuses `compute_blast_radius`."""
+    _run_retrieval_intent("blast-radius", path, output_path, trace, anchors=(("symbol", target),))
+
+
+@retrieve_app.command("affected-endpoints")
+def retrieve_affected_endpoints_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN) or file to analyze."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] AFFECTED_ENDPOINTS — HTTP endpoints in the blast cone of a target."""
+    _run_retrieval_intent("affected-endpoints", path, output_path, trace, anchors=(("symbol", target),))
+
+
+@retrieve_app.command("affected-integrations")
+def retrieve_affected_integrations_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN) or file to analyze."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] AFFECTED_INTEGRATIONS — external integrations in the blast cone of a
+    target. Reuses `SemanticIntegrationEngine`."""
+    _run_retrieval_intent(
+        "affected-integrations", path, output_path, trace, anchors=(("symbol", target),)
+    )
+
+
+@retrieve_app.command("transaction-boundaries")
+def retrieve_transaction_boundaries_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN) or file to analyze."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] TRANSACTION_BOUNDARIES — transactional boundaries touched by a
+    target's blast cone."""
+    _run_retrieval_intent(
+        "transaction-boundaries", path, output_path, trace, anchors=(("symbol", target),)
+    )
+
+
+@retrieve_app.command("cross-module-impact")
+def retrieve_cross_module_impact_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN) or file to analyze."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] CROSS_MODULE_IMPACT — subsystems/modules hit by a target's change."""
+    _run_retrieval_intent(
+        "cross-module-impact", path, output_path, trace, anchors=(("symbol", target),)
+    )
+
+
+@retrieve_app.command("transaction-flow")
+def retrieve_transaction_flow_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] TRANSACTION_FLOW — the @Transactional boundary map. Reuses
+    SpringSemanticModel's transaction index."""
+    _run_retrieval_intent("transaction-flow", path, output_path, trace)
+
+
+@retrieve_app.command("transaction-entrypoints")
+def retrieve_transaction_entrypoints_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] TRANSACTION_ENTRYPOINTS — transactional boundaries at the API surface."""
+    _run_retrieval_intent("transaction-entrypoints", path, output_path, trace)
+
+
+@retrieve_app.command("transaction-propagation")
+def retrieve_transaction_propagation_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] TRANSACTION_PROPAGATION — non-default propagation points + propagation
+    risks. Reuses the Spring transaction engine."""
+    _run_retrieval_intent("transaction-propagation", path, output_path, trace)
+
+
+@retrieve_app.command("security-surface")
+def retrieve_security_surface_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] SECURITY_SURFACE — the security audit surface. Reuses run_security_audit."""
+    _run_retrieval_intent("security-surface", path, output_path, trace)
+
+
+@retrieve_app.command("security-chain")
+def retrieve_security_chain_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN) to scope the chain to."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] SECURITY_CHAIN — security findings scoped to a target symbol."""
+    _run_retrieval_intent("security-chain", path, output_path, trace, anchors=(("symbol", target),))
+
+
+@retrieve_app.command("validation-points")
+def retrieve_validation_points_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] VALIDATION_POINTS — request-body validation constraints + gaps.
+    Reuses build_validation_surface."""
+    _run_retrieval_intent("validation-points", path, output_path, trace)
+
+
+@retrieve_app.command("endpoint-inventory")
+def retrieve_endpoint_inventory_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] ENDPOINT_INVENTORY — the repository's HTTP surface.
+    Reuses SpringSemanticModel.endpoint_index."""
+    _run_retrieval_intent("endpoint-inventory", path, output_path, trace)
+
+
+@retrieve_app.command("integration-inventory")
+def retrieve_integration_inventory_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] INTEGRATION_INVENTORY — every detected external integration.
+    Reuses SemanticIntegrationEngine (whole repo, no cone filter)."""
+    _run_retrieval_intent("integration-inventory", path, output_path, trace)
+
+
+@retrieve_app.command("event-topology")
+def retrieve_event_topology_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] EVENT_TOPOLOGY — Spring event publishers/listeners per event type.
+    Reuses SpringSemanticModel.event_graph."""
+    _run_retrieval_intent("event-topology", path, output_path, trace)
+
+
+@retrieve_app.command("subsystem-inventory")
+def retrieve_subsystem_inventory_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] SUBSYSTEM_INVENTORY — the repository's subsystem partition.
+    Reuses the repo IR subsystem model."""
+    _run_retrieval_intent("subsystem-inventory", path, output_path, trace)
+
+
+@retrieve_app.command("subsystem-members")
+def retrieve_subsystem_members_cmd(
+    subsystem: str = typer.Option(..., "--subsystem", "-s", help="Subsystem label or package prefix."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] SUBSYSTEM_MEMBERS — the member symbols of a subsystem.
+    Reuses the repo IR subsystem model."""
+    _run_retrieval_intent(
+        "subsystem-members", path, output_path, trace, anchors=(("subsystem", subsystem),)
+    )
+
+
+@retrieve_app.command("module-dependents")
+def retrieve_module_dependents_cmd(
+    module: str = typer.Option(..., "--module", "-m", help="Module path or package prefix."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] MODULE_DEPENDENTS — modules that depend on the scope.
+    Reuses the module graph (GraphAnalyzer)."""
+    _run_retrieval_intent(
+        "module-dependents", path, output_path, trace, anchors=(("module", module),)
+    )
+
+
+@retrieve_app.command("module-dependencies")
+def retrieve_module_dependencies_cmd(
+    module: str = typer.Option(..., "--module", "-m", help="Module path or package prefix."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] MODULE_DEPENDENCIES — modules the scope depends on.
+    Reuses the module graph (GraphAnalyzer)."""
+    _run_retrieval_intent(
+        "module-dependencies", path, output_path, trace, anchors=(("module", module),)
+    )
+
+
+@retrieve_app.command("type-dependents")
+def retrieve_type_dependents_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Type/symbol (simple name or FQN)."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] TYPE_DEPENDENTS — types that import/implement/inject the target.
+    Reuses the repo IR reverse graph."""
+    _run_retrieval_intent(
+        "type-dependents", path, output_path, trace, anchors=(("symbol", target),)
+    )
+
+
+@retrieve_app.command("endpoint-contract")
+def retrieve_endpoint_contract_cmd(
+    ref: str = typer.Option(..., "--endpoint", "-e", help="Endpoint path or handler symbol."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] ENDPOINT_CONTRACT — the request/validation contract of an endpoint.
+    Reuses build_validation_surface, scoped to one endpoint."""
+    _run_retrieval_intent(
+        "endpoint-contract", path, output_path, trace, anchors=(("endpoint", ref),)
+    )
+
+
+@retrieve_app.command("endpoint-security")
+def retrieve_endpoint_security_cmd(
+    ref: str = typer.Option(..., "--endpoint", "-e", help="Endpoint path or handler symbol."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] ENDPOINT_SECURITY — effective security of an endpoint handler.
+    Reuses the endpoint model's CanonicalSecurity + run_security_audit."""
+    _run_retrieval_intent(
+        "endpoint-security", path, output_path, trace, anchors=(("endpoint", ref),)
+    )
+
+
+@retrieve_app.command("call-neighborhood")
+def retrieve_call_neighborhood_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN/method)."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] CALL_NEIGHBORHOOD — forward callees + reverse callers of a symbol.
+    Reuses SpringSemanticModel.call_adj."""
+    _run_retrieval_intent(
+        "call-neighborhood", path, output_path, trace, anchors=(("symbol", target),)
+    )
+
+
+@retrieve_app.command("execution-paths-through")
+def retrieve_execution_paths_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN/method)."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] EXECUTION_PATHS_THROUGH — multi-hop caller reachability of a symbol.
+    Reuses spring_impact.run_impact_chain."""
+    _run_retrieval_intent(
+        "execution-paths-through", path, output_path, trace, anchors=(("symbol", target),)
+    )
+
+
+@retrieve_app.command("transactions-reaching")
+def retrieve_transactions_reaching_cmd(
+    target: str = typer.Option(..., "--target", "-t", help="Symbol (class/FQN/method)."),
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] TRANSACTIONS_REACHING — @Transactional boundaries that reach a symbol.
+    Reuses run_impact_chain + the tx boundary index."""
+    _run_retrieval_intent(
+        "transactions-reaching", path, output_path, trace, anchors=(("symbol", target),)
+    )
+
+
+@retrieve_app.command("subsystem-coupling")
+def retrieve_subsystem_coupling_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    output_path: Optional[Path] = typer.Option(None, "--output", "-o", help="Write output to a file."),
+    trace: bool = typer.Option(False, "--trace", help="Include the Query Plan Runtime trace."),
+) -> None:
+    """[EXPERIMENTAL] SUBSYSTEM_COUPLING — module-graph hubs/cycles/orphans + subsystems.
+    Reuses the module graph summary + the repo IR subsystem partition."""
+    _run_retrieval_intent("subsystem-coupling", path, output_path, trace)
+
+
 @app.command("cold-start")
 def cold_start_cmd(
     path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
@@ -7199,6 +7639,53 @@ def cache_freshness_cmd(
         typer.echo(f"RIS updated:  {result.get('ris_last_updated_at') or 'never'}")
 
 
+@cache_app.command("context-stats")
+def cache_context_stats_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON."),
+) -> None:
+    """Show AI Context Cache statistics (structured-knowledge reuse metrics).
+
+    This is the provider-agnostic context cache — distinct from the snapshot
+    cache reported by `ask cache status`. It measures reuse of ASK's structured
+    context (entities/evidence/observations/summaries), never prompts or LLM output.
+    """
+    from sourcecode import context_cache as _ctxcache
+    target = _resolve_repo_root(Path(path))
+    stats = _ctxcache.stats_for_repo(target)
+    if json_output:
+        import json as _j
+        typer.echo(_j.dumps(stats, indent=2, ensure_ascii=False))
+    else:
+        typer.echo(f"Cache dir:     {stats['cache_dir']}")
+        typer.echo(f"Enabled:       {stats['enabled']}")
+        typer.echo(f"Contexts:      {stats['contexts']}")
+        typer.echo(f"Hits:          {stats['hits']}")
+        typer.echo(f"Misses:        {stats['misses']}")
+        typer.echo(f"Invalidations: {stats['invalidations']}")
+        typer.echo(f"Stores:        {stats['stores']}")
+        typer.echo(f"Hit ratio:     {stats['hit_ratio']}")
+        typer.echo(f"Avg lookup:    {stats['avg_lookup_ms']} ms")
+        typer.echo(f"Avg build:     {stats['avg_build_ms']} ms")
+        typer.echo(f"Bytes stored:  {stats['bytes_stored']}")
+        typer.echo(f"KL version:    {stats['kl_schema_version']}  producer={stats['producer_version']}")
+
+
+@cache_app.command("context-clear")
+def cache_context_clear_cmd(
+    path: Path = typer.Argument(Path("."), help="Repository path (default: current directory)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Delete the AI Context Cache for a repository (structured context + stats)."""
+    from sourcecode import context_cache as _ctxcache
+    target = _resolve_repo_root(Path(path))
+    if not yes and sys.stdin.isatty():
+        import click as _click
+        _click.confirm(f"Delete AI context cache for {target}?", abort=True, err=True)
+    removed = _ctxcache.clear_for_repo(target)
+    typer.echo(f"Removed {removed} context file(s).", err=True)
+
+
 # ── Entry point ───────────────────────────────────────────────────────────────
 
 def _stderr_is_interactive() -> bool: