sourcecode 2.4.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.4.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"}
         ]
       }
@@ -5558,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",
@@ -5596,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()
@@ -6509,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)"),

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/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).