adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/harness/skills/drift-antigravity.md

@@ -0,0 +1,19 @@
+# ADL Drift — predict-edit-prove workflow
+
+ADL Drift indexes Python and Java symbols as a persistent call graph exposed through the `adl-drift` MCP server.
+
+If there is no `.adl-drift/` directory, skip ADL-Drift entirely — indexing is the user's decision. The workflow below applies only when `.adl-drift/` exists at the project root.
+
+1. **Explore read-only questions:** For a symbol's source/details, callers/blast radius, or dependencies, use `drift_explore` before text search or file reading. “What breaks if I delete/change X?” and refactor-safety questions also use `drift_explore`.
+2. **Predict edits:** Before the first edit to a Python/Java function, method, constructor, class, field, constant, or parameter, **MUST call `drift_plan_change`**. It resolves the target itself, so `drift_explore` is not required first. For an addition, plan against the containing or related symbol. Save the returned `baseline`.
+
+   Example: `Add required audit_tag parameter to Python function jsonable_encoder`.
+3. **Edit:** Update the target and affected callers, implementations, entry points, and tests.
+4. **Prove:** After Python/Java edits, **MUST call `drift_verify_change`** with the original `baseline` and all modified Python/Java files in `changed_files`. Fix unintended differences and rerun with the same baseline; report intentional differences or a remaining `INCONSISTENT` verdict accurately.
+5. **Validate:** Run relevant tests and static checks. If checks require further edits, repeat verification and affected checks. Graph consistency does not prove behavioral correctness.
+
+If a target is uncertain, use `drift_explore` to inspect the resolved and ambiguous matches; use `drift_search` only when an exact qualified symbol still needs confirmation. Include parameter types for Java overloads. Treat fuzzy matches and low-confidence/framework-dispatched edges as leads to inspect.
+
+Before the first graph query in a task, call `drift_status`. If the existing index is stale or incomplete, run `drift_scan` on the project root before exploring or planning. Recheck with `drift_status` after external source changes; after your own edits, use `drift_verify_change` with the original baseline. Inspect or report `scan_errors`. Increase `max_tokens` moderately for truncated results.
+
+Use text search for literals, comments, logs, generated files, and files outside Drift's `.py`/`.java` coverage.

package/adl_drift/harness/skills/drift-generic.md

@@ -0,0 +1,19 @@
+# ADL Drift — predict-edit-prove workflow
+
+ADL Drift indexes Python and Java symbols as a persistent call graph exposed through the `adl-drift` MCP server.
+
+If there is no `.adl-drift/` directory, skip ADL-Drift entirely — indexing is the user's decision. The workflow below applies only when `.adl-drift/` exists at the project root.
+
+1. **Explore read-only questions:** For a symbol's source/details, callers/blast radius, or dependencies, use `drift_explore` before text search or file reading. “What breaks if I delete/change X?” and refactor-safety questions also use `drift_explore`.
+2. **Predict edits:** Before the first edit to a Python/Java function, method, constructor, class, field, constant, or parameter, **MUST call `drift_plan_change`**. It resolves the target itself, so `drift_explore` is not required first. For an addition, plan against the containing or related symbol. Save the returned `baseline`.
+
+   Example: `Add required audit_tag parameter to Python function jsonable_encoder`.
+3. **Edit:** Update the target and affected callers, implementations, entry points, and tests.
+4. **Prove:** After Python/Java edits, **MUST call `drift_verify_change`** with the original `baseline` and all modified Python/Java files in `changed_files`. Fix unintended differences and rerun with the same baseline; report intentional differences or a remaining `INCONSISTENT` verdict accurately.
+5. **Validate:** Run relevant tests and static checks. If checks require further edits, repeat verification and affected checks. Graph consistency does not prove behavioral correctness.
+
+If a target is uncertain, use `drift_explore` to inspect the resolved and ambiguous matches; use `drift_search` only when an exact qualified symbol still needs confirmation. Include parameter types for Java overloads. Treat fuzzy matches and low-confidence/framework-dispatched edges as leads to inspect.
+
+Before the first graph query in a task, call `drift_status`. If the existing index is stale or incomplete, run `drift_scan` on the project root before exploring or planning. Recheck with `drift_status` after external source changes; after your own edits, use `drift_verify_change` with the original baseline. Inspect or report `scan_errors`. Increase `max_tokens` moderately for truncated results.
+
+Use text search for literals, comments, logs, generated files, and files outside Drift's `.py`/`.java` coverage.

package/adl_drift/harness/skills/drift.md

@@ -0,0 +1,25 @@
+---
+name: adl-drift
+description: Persistent Python/Java call graph for symbol details, dependencies,
+  blast radius, and mandatory predict-edit-prove checks around source changes.
+---
+
+# ADL Drift — predict-edit-prove workflow
+
+ADL Drift indexes Python and Java symbols as a persistent call graph exposed through the `adl-drift` MCP server.
+
+If there is no `.adl-drift/` directory, skip ADL-Drift entirely — indexing is the user's decision. The workflow below applies only when `.adl-drift/` exists at the project root.
+
+1. **Explore read-only questions:** For a symbol's source/details, callers/blast radius, or dependencies, use `drift_explore` before text search or file reading. “What breaks if I delete/change X?” and refactor-safety questions also use `drift_explore`.
+2. **Predict edits:** Before the first edit to a Python/Java function, method, constructor, class, field, constant, or parameter, **MUST call `drift_plan_change`**. It resolves the target itself, so `drift_explore` is not required first. For an addition, plan against the containing or related symbol. Save the returned `baseline`.
+
+   Example: `Add required audit_tag parameter to Python function jsonable_encoder`.
+3. **Edit:** Update the target and affected callers, implementations, entry points, and tests.
+4. **Prove:** After Python/Java edits, **MUST call `drift_verify_change`** with the original `baseline` and all modified Python/Java files in `changed_files`. Fix unintended differences and rerun with the same baseline; report intentional differences or a remaining `INCONSISTENT` verdict accurately.
+5. **Validate:** Run relevant tests and static checks. If checks require further edits, repeat verification and affected checks. Graph consistency does not prove behavioral correctness.
+
+If a target is uncertain, use `drift_explore` to inspect the resolved and ambiguous matches; use `drift_search` only when an exact qualified symbol still needs confirmation. Include parameter types for Java overloads. Treat fuzzy matches and low-confidence/framework-dispatched edges as leads to inspect.
+
+Before the first graph query in a task, call `drift_status`. If the existing index is stale or incomplete, run `drift_scan` on the project root before exploring or planning. Recheck with `drift_status` after external source changes; after your own edits, use `drift_verify_change` with the original baseline. Inspect or report `scan_errors`. Increase `max_tokens` moderately for truncated results.
+
+Use text search for literals, comments, logs, generated files, and files outside Drift's `.py`/`.java` coverage.

package/adl_drift/harness/watch.py

@@ -0,0 +1,84 @@
+"""`adl-drift watch` — keep the index fresh while files are being edited.
+
+A polling loop, not an OS watcher: the cheap pass stats mtimes of every
+tracked backend source file; only when something moved does it run an incremental
+scan, where `IncrementalScanner`'s content-hash classification filters
+spurious mtime bumps (touch/checkout without content change). This keeps
+the dependency surface at zero — the same trade web.py makes for the viz.
+
+The watcher is optional. `MCPHandlers._build_full_graph()` re-classifies
+files per call, so agents never read a stale graph even without it; the
+watcher just moves the rescan cost off the agent's first tool call.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Callable, Dict, Optional
+
+from adl_drift.cli.commands import DriftCommands
+
+Snapshot = Dict[Path, float]
+
+
+def _snapshot(commands: DriftCommands, language: Optional[str] = None) -> Snapshot:
+    snap: Snapshot = {}
+    for fp in commands._find_files(commands.project_path, language):
+        try:
+            snap[fp] = fp.stat().st_mtime
+        except OSError:
+            continue  # deleted between listing and stat — next pass catches it
+    return snap
+
+
+def watch(
+    project_path: Path,
+    interval: float = 2.0,
+    settle: float = 0.5,
+    max_iterations: Optional[int] = None,
+    on_event: Optional[Callable[[str], None]] = None,
+    language: Optional[str] = None,
+) -> int:
+    """Poll for changes and incrementally rescan. Blocks until interrupted
+    (or until *max_iterations* polls, for tests). Returns rescan count."""
+    project_path = Path(project_path).resolve()
+    commands = DriftCommands(project_path)
+    emit = on_event or (lambda msg: None)
+
+    emit(f"watching {project_path} (poll every {interval:.0f}s, Ctrl-C to stop)")
+    results = commands.scan(project_path, incremental=True, language=language)
+    # Snapshot BEFORE emitting so any listener-triggered write is not captured
+    # in `last` (which would hide the subsequent change from the poll loop).
+    last = _snapshot(commands, language)
+    emit(f"initial index: {len(results)} patterns, {len(commands.last_scan_errors)} errors")
+    rescans = 0
+    iterations = 0
+
+    while max_iterations is None or iterations < max_iterations:
+        iterations += 1
+        time.sleep(interval)
+        current = _snapshot(commands, language)
+        if current == last:
+            continue
+        time.sleep(settle)  # let a save burst finish before rescanning
+        current = _snapshot(commands, language)
+
+        changed_paths = [
+            fp for fp in current
+            if last.get(fp) != current[fp]
+        ] + [fp for fp in last if fp not in current]
+        start = time.monotonic()
+        results = commands.scan(project_path, incremental=True, language=language)
+        elapsed = time.monotonic() - start
+        rescans += 1
+        emit(
+            f"rescan #{rescans}: {len(changed_paths)} file(s) changed, "
+            f"{len(results)} patterns, {len(commands.last_scan_errors)} errors "
+            f"({elapsed:.1f}s)"
+        )
+        for err in commands.last_scan_errors:
+            emit(f"  scan error: {err['file']} — {err['error']}")
+        last = current
+
+    return rescans

package/adl_drift/lang/__init__.py

@@ -0,0 +1,8 @@
+"""Language-backend extension seam (P4.0, PROBLEMS.md).
+
+`adl_drift.lang` is the boundary between the language-agnostic engine
+(scanner, cli/commands, server/handlers, cortex) and language-coupled
+analysis (parsing, symbol extraction, detectors, name resolution, CFG/taint,
+framework detection). See `lang.base.LanguageBackend` for the contract and
+`lang.registry` for backend dispatch.
+"""

package/adl_drift/lang/base.py

@@ -0,0 +1,464 @@
+"""The `LanguageBackend` contract — single source of truth for P4.1-P4.11.
+
+See PROBLEMS.md P4.0 for the full design writeup. This module defines the
+seam a language plugs into; it does not implement any language (with one
+exception: `LanguageParser`, the grammar-agnostic tree-sitter wrapper, is a
+real class as of P4.1 — see its docstring). The rest of the Python pipeline
+(extractor.py, detectors/, the resolver in graph/builder.py, graph/cfg.py,
+detectors/taint.py, utils/config.py) is migrated behind this contract in
+P4.2-P4.7. A Java backend plugs in the same way without forking the engine
+layer (scanner, cli/commands, server/handlers, cortex) — those call sites ask
+`lang.registry` for a backend, never import a concrete one.
+
+Boundary rules (P4.0):
+- The graph data model (`graph/node.py`, `graph/edges.py`, `EdgeType`, the
+  `module:qualname` node-id shape) stays shared and is untouched here.
+- `Symbol` / `Pattern` / `AnalysisResult` (`utils/types.py`) stay shared
+  dataclasses; language-specific needs are additive fields (P4.9), not new
+  per-language types.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    FrozenSet,
+    List,
+    Optional,
+    Protocol,
+    Tuple,
+    runtime_checkable,
+)
+
+from tree_sitter import Language, Node, Parser, Query, QueryCursor, Tree
+
+from adl_drift.utils.types import AnalysisResult, ImportRecord, Symbol
+
+if TYPE_CHECKING:
+    # `BaseDetector` is only used as a type annotation here. Keep the import
+    # type-checker-only so the language contract does not load detector plugins.
+    from adl_drift.detectors.base import BaseDetector
+    # Same story for `CallGraphBuilder`: `graph/builder.py` lazily imports
+    # concrete `CallResolver` subclasses *inside a method body* (P4.4), so
+    # there is no real runtime cycle — but importing the class at module
+    # scope here just to spell out a type hint would still be needless
+    # coupling for a module whose whole job is staying grammar/engine-agnostic.
+    from adl_drift.graph.builder import CallGraphBuilder
+
+__all__ = [
+    "ParseResult",
+    "LanguageParser",
+    "SymbolExtractor",
+    "ResolverConfig",
+    "CallResolver",
+    "CFGConfig",
+    "ProjectConfig",
+    "LanguageBackend",
+]
+
+
+@dataclass
+class ParseResult:
+    """Output of a single parse. Already language-agnostic — unchanged by
+    P4.1 (Tree + source bytes + error nodes + parse time, whatever the
+    grammar)."""
+
+    tree: Tree
+    source_bytes: bytes
+    parse_time_ms: float = 0.0
+    errors: List[Node] = field(default_factory=list)
+    file_path: Optional[Path] = None
+
+    @property
+    def has_errors(self) -> bool:
+        return len(self.errors) > 0
+
+
+class LanguageParser:
+    """Grammar-agnostic tree-sitter wrapper (P4.1, PROBLEMS.md).
+
+    Generalized out of `parser/core.py::PythonParser`: takes a
+    `tree_sitter.Language` and a query-name -> query-string map at
+    construction instead of relying on a module-global grammar. Error-node
+    collection, byte-offset -> `SourcePosition` conversion (`node_position`),
+    and the `node_text` helper are unchanged from the Python-only version.
+
+    `lang/python/parser.py` and `lang/java/parser.py` each own the grammar
+    load (`tree_sitter_python`/`tree_sitter_java`) and query map, and
+    construct one of these configured for their language.
+    """
+
+    def __init__(self, language: Language, queries: Dict[str, str]) -> None:
+        self.language = language
+        self.queries = queries
+        self._parser = Parser(language)
+
+    def parse_string(self, source: str, file_path: Optional[Path] = None) -> ParseResult:
+        source_bytes = source.encode("utf-8")
+        start = time.perf_counter()
+        tree = self._parser.parse(source_bytes)
+        elapsed = (time.perf_counter() - start) * 1000.0
+        errors = self._collect_error_nodes(tree.root_node)
+        return ParseResult(
+            tree=tree,
+            source_bytes=source_bytes,
+            parse_time_ms=elapsed,
+            errors=errors,
+            file_path=file_path,
+        )
+
+    def parse_file(self, path: Path) -> ParseResult:
+        path = Path(path)
+        source = path.read_text(encoding="utf-8", errors="replace")
+        return self.parse_string(source, file_path=path)
+
+    def query_nodes(self, tree: Tree, query_name: str) -> List[Node]:
+        if query_name not in self.queries:
+            raise KeyError(f"Unknown query: {query_name}")
+        query = Query(self.language, self.queries[query_name])
+        captures = QueryCursor(query).captures(tree.root_node)
+        if isinstance(captures, dict):
+            nodes: List[Node] = []
+            for vals in captures.values():
+                nodes.extend(vals)
+            return nodes
+        return [n for n, _ in captures]
+
+    @staticmethod
+    def node_text(node: Node, source: bytes) -> str:
+        return source[node.start_byte : node.end_byte].decode("utf-8", errors="replace")
+
+    @staticmethod
+    def node_position(node: Node):
+        from adl_drift.utils.types import SourcePosition
+
+        sr, sc = node.start_point
+        er, ec = node.end_point
+        return SourcePosition(line=sr + 1, column=sc, end_line=er + 1, end_column=ec)
+
+    @classmethod
+    def _collect_error_nodes(cls, node: Node) -> List[Node]:
+        out: List[Node] = []
+        if node.type == "ERROR" or node.is_missing:
+            out.append(node)
+        for child in node.children:
+            out.extend(cls._collect_error_nodes(child))
+        return out
+
+
+class SymbolExtractor:
+    """CST -> `AnalysisResult` (P4.2, PROBLEMS.md).
+
+    Promoted from a placeholder `Protocol` to a real base class: owns the
+    parts of symbol extraction that do not depend on any one grammar —
+    `extract()`/`extract_string()` (parse then delegate to `_build()`), the
+    depth-first CST walk (`_walk`), the dedupe-by-`(scope_chain, parent,
+    name)` key used to drop duplicate variable/attribute symbols
+    (`_dedupe_key`), and final `AnalysisResult` assembly including the
+    `ImportRecord`/`imports` plumbing and parse-error formatting
+    (`_finalize`). `_build()` itself — the node-type dispatch table — is
+    grammar-specific and left abstract here; `lang/python/extractor.py` and
+    `lang/java/extractor.py` each implement it against their own CST node
+    types.
+    """
+
+    def __init__(self, parser: "LanguageParser") -> None:
+        self.parser = parser
+
+    def extract(self, file_path: Path) -> AnalysisResult:
+        parse = self.parser.parse_file(file_path)
+        return self._build(parse, file_path)
+
+    def extract_string(
+        self, source: str, file_path: Optional[Path] = None
+    ) -> AnalysisResult:
+        parse = self.parser.parse_string(source, file_path=file_path)
+        return self._build(parse, file_path or Path("<string>"))
+
+    def _build(self, parse: ParseResult, file_path: Path) -> AnalysisResult:
+        """Grammar-specific CST walk -> `AnalysisResult`. Implemented per language."""
+        raise NotImplementedError
+
+    def _walk(self, node: Node):
+        yield node
+        for child in node.children:
+            yield from self._walk(child)
+
+    @staticmethod
+    def _dedupe_key(symbol: Symbol) -> Tuple[Tuple[str, ...], str, str]:
+        """Uniqueness key for symbols that may be visited more than once
+        (e.g. variable/attribute-style declarations). Not applied to
+        function/method symbols — legitimate Java overloads share this key
+        and must stay distinct (P4.5's `signature_key` is what disambiguates
+        them, not this dedupe pass)."""
+        return (tuple(symbol.scope_chain), symbol.parent or "", symbol.name)
+
+    @staticmethod
+    def _finalize(
+        parse: ParseResult,
+        file_path: Path,
+        symbols: List[Symbol],
+        imports: List[str],
+        import_records: List[ImportRecord],
+        *,
+        language: str = "python",
+        module_name: Optional[str] = None,
+    ) -> AnalysisResult:
+        return AnalysisResult(
+            file_path=file_path,
+            symbols=symbols,
+            imports=imports,
+            import_records=import_records,
+            errors=[f"parse error at {n.start_point}" for n in parse.errors],
+            parse_time_ms=parse.parse_time_ms,
+            language=language,
+            module_name=module_name,
+        )
+
+
+@dataclass
+class ResolverConfig:
+    """Name-resolution *policy* for the language-agnostic call-resolution
+    seam (P4.4, PROBLEMS.md).
+
+    `LanguageBackend.resolver_config()` returns one of these.
+    `CallGraphBuilder._get_resolver()` uses `resolver_factory` to build the
+    `CallResolver` instance that actually walks this language's CST and
+    applies the policy below. Splitting declarative policy (this dataclass)
+    from CST-coupled mechanics (`CallResolver`) mirrors how P4.2 split
+    `SymbolExtractor._build()` (grammar-specific) from the shared parts of
+    that base class. Graph mechanics that stay language-agnostic — edge
+    dedupe (`CallGraphBuilder._add_edge`), the MultiDiGraph, confidence
+    persistence, impact BFS, and the id-resolution helpers
+    (`_resolve_name`/`_contains_child`/`_find_method_on_ancestors`/
+    `_resolve_annotation`, which walk CONTAINS/INHERITS edges rather than
+    any grammar) are *not* part of this config; they live on
+    `CallGraphBuilder` and are reused unchanged by every language.
+
+    - `receiver_self_names`: identifiers meaning "the enclosing instance"
+      (Python: ``("self", "cls")``; Java: ``("this",)``).
+    - `receiver_super_names`: identifiers meaning "walk the ancestor chain"
+      (Python: ``("super",)``; Java: ``("super",)``).
+    - `builtins_deny_list`: names the fuzzy / over-approximation strategies
+      must never resolve through (P2.7's `PYTHON_BUILTINS`; Java's
+      `java.lang.Object` methods + common collection methods).
+    - `annotation_stub_table`: decorator/annotation simple name -> the set
+      of names it contributes, read differently per language
+      (`DECORATOR_STUB_TABLE`: exact attribute names a Python decorator adds
+      to the wrapped callable; `JAVA_ANNOTATION_STUB_TABLE`: name *prefixes*
+      Lombok-style annotations generate on the annotated class, since those
+      names are field-dependent and not a fixed set).
+    - `resolver_factory`: builds the `CallResolver` for this policy. Kept on
+      the config rather than a new `LanguageBackend` method so P4.0's
+      `LanguageBackend` Protocol surface stays exactly as originally specified.
+    """
+
+    receiver_self_names: Tuple[str, ...] = ()
+    receiver_super_names: Tuple[str, ...] = ()
+    builtins_deny_list: FrozenSet[str] = frozenset()
+    annotation_stub_table: Dict[str, FrozenSet[str]] = field(default_factory=dict)
+    resolver_factory: Optional[
+        Callable[["CallGraphBuilder", "ResolverConfig"], "CallResolver"]
+    ] = None
+
+
+class CallResolver:
+    """Per-language call-resolution strategy (P4.4, PROBLEMS.md).
+
+    Owns everything CST-coupled about turning a function/method body into
+    CALLS/INSTANTIATES/AWAITS/REFERENCES edges for one language: what a call
+    site looks like in this grammar, how a bare/qualified receiver resolves
+    to a name, and (Java) overload/erasure handling. Grammar-agnostic id
+    resolution over the graph itself (`_resolve_name`, `_contains_child`,
+    `_find_method_on_ancestors`, `_resolve_annotation`, edge dedupe) stays on
+    `CallGraphBuilder` and is reached via `self.builder`.
+
+    `lang/python/resolver.py::PythonCallResolver` and
+    `lang/java/resolver.py::JavaCallResolver` are the two implementations.
+    Never constructed directly — `CallGraphBuilder._get_resolver()` builds
+    one lazily via `ResolverConfig.resolver_factory`.
+    """
+
+    def __init__(self, builder: "CallGraphBuilder", config: ResolverConfig) -> None:
+        self.builder = builder
+        self.config = config
+
+    def resolve_calls(
+        self,
+        parses: Dict[Path, "ParseResult"],
+        results: Dict[Path, AnalysisResult],
+    ) -> int:
+        """Emit CALLS/INSTANTIATES/AWAITS/REFERENCES edges for every call
+        site in `parses`. Returns the number of CALLS/INSTANTIATES edges
+        added."""
+        raise NotImplementedError
+
+    def resolve_decorator_types(
+        self,
+        parses: Dict[Path, "ParseResult"],
+        results: Dict[Path, AnalysisResult],
+    ) -> None:
+        """Optional pre-pass building decorator/annotation-stub bindings
+        consulted by `resolve_calls()`. No-op unless a language needs one
+        (Python's P2.15 stub table + narrow own-inference; Java's simpler
+        annotation-stub lookup resolves inline and needs no pre-pass)."""
+        return None
+
+    def harvest_literal_candidates(
+        self,
+        parses: Dict[Path, "ParseResult"],
+        results: Dict[Path, AnalysisResult],
+    ) -> int:
+        """Optional low-confidence candidate-edge pass over literal/dynamic
+        dispatch idioms (Python's P2.13/P2.22/P2.23 dict-router patterns).
+        No-op by default; returns edges added."""
+        return 0
+
+
+@dataclass
+class CFGConfig:
+    """Statement-kind -> CFG-effect mapping + taint source/sink tables (P4.6).
+
+    `LanguageBackend.cfg_config()` returns one of these.  It is consumed by
+    two generic engines that stay language-agnostic (P4.6, PROBLEMS.md):
+    `graph/cfg.py::CFGBuilderBase`/`ReachingDefinitions` (the GEN/KILL
+    fixpoint + `DefUseFact` emission) and `detectors/taint.py::TaintAnalyzer`
+    (the cross-function taint worklist + `TaintPath` dataclass +
+    `taint_paths` persistence). Neither of those engines is CST-coupled —
+    they operate on `CFGBlock`/`CFGDef` graphs and `(tainted, TaintPath,
+    _OutCall)` triples respectively, never on raw tree-sitter node types —
+    so, mirroring how P4.4 split `ResolverConfig` (declarative policy) from
+    `CallResolver` (CST-coupled mechanics), this dataclass carries only
+    *data* (the tables below) plus two factories that build the CST-coupled
+    mechanics classes: `cfg_builder_factory` (a fresh
+    `graph.cfg.CFGBuilderBase` subclass instance per build — Python's is
+    `lang/python/cfg.py::PythonCFGBuilder`, Java's is
+    `lang/java/cfg.py::JavaCFGBuilder`) and `taint_strategy_factory` (a
+    `detectors.taint.TaintStrategy` subclass instance — `PythonTaintStrategy`
+    / `JavaTaintStrategy`, living next to their respective `CFGBuilder`).
+
+    Every table defaults to empty so an unset field is simply "this language
+    has no such source/sink shape" rather than raising — e.g. Python has no
+    constructor-based sink (`taint_sink_constructors` stays `{}`) and no
+    parameter-annotation source (`taint_source_param_annotations` stays
+    `{}`), while Java populates both and leaves the legacy `taint_sources`
+    prefix-list empty (its sources are receiver-agnostic method names /
+    annotations, not RHS-text prefixes).
+    """
+
+    # ---- taint sources -----------------------------------------------
+    taint_sources: Tuple[str, ...] = ()
+    """Prefix-matched against a def/argument's *full* RHS text — Python's
+    original P2.18/P2.19 mechanism (`request.GET`, `os.environ.get`, ...)."""
+
+    taint_source_methods: Dict[str, str] = field(default_factory=dict)
+    """Final call-target identifier (any receiver) -> source label. Java's
+    `getParameter`/`getHeader`/`getQueryString` are receiver-name-agnostic
+    (an `HttpServletRequest` variable can be called anything), unlike
+    Python's conventionally-named `request` object. Empty for Python."""
+
+    taint_source_param_annotations: Dict[str, str] = field(default_factory=dict)
+    """Annotation simple name on a formal parameter -> source label. Java's
+    `@RequestParam`/`@PathVariable`/`@RequestBody`/JAX-RS `@QueryParam`/
+    `@PathParam` mark a parameter as tainted at function entry regardless of
+    caller (unlike an ordinary parameter, which only becomes tainted via
+    cross-function propagation). Empty for Python (no parameter-annotation
+    sources)."""
+
+    # ---- taint sinks ----------------------------------------------------
+    taint_sinks: Dict[str, str] = field(default_factory=dict)
+    """Exact dotted-callable text -> vulnerability category. Python's
+    `eval`/`os.system`/`pickle.load`; Java's `System.getenv`-shaped exact
+    calls have no sink equivalent today, so this stays receiver-qualified
+    calls only (e.g. none needed beyond the method-name table below for the
+    current Java sink set)."""
+
+    sink_methods: Dict[str, str] = field(default_factory=dict)
+    """Final call-target identifier (any receiver) -> category. Python's
+    `execute`/`executemany`/`raw`; Java's `executeQuery`/`executeUpdate`/
+    `createNativeQuery`/`readObject`/`exec`/`eval`/`invoke`/`forName`."""
+
+    sink_constructors: Dict[str, str] = field(default_factory=dict)
+    """Constructed type simple name (`new X(...)`) -> category. Java's
+    `ProcessBuilder`. Empty for Python (no constructor-based sink)."""
+
+    # ---- CST-coupled mechanics factories --------------------------------
+    cfg_builder_factory: Optional[Callable[["CFGConfig"], "CFGBuilderBase"]] = None
+    """Builds this language's `graph.cfg.CFGBuilderBase` subclass instance.
+    Mirrors `ResolverConfig.resolver_factory`."""
+
+    taint_strategy_factory: Optional[Callable[["CFGConfig"], "TaintStrategy"]] = None
+    """Builds this language's `detectors.taint.TaintStrategy` subclass
+    instance."""
+
+
+@runtime_checkable
+class ProjectConfig(Protocol):
+    """Framework auto-detection result for a project root.
+
+    Placeholder shape only, matched structurally to the existing
+    `utils.config.ProjectConfig` (Python-only today) so it satisfies this
+    Protocol without modification. A Java equivalent parsing `pom.xml` /
+    `build.gradle` lands in P4.7.
+    """
+
+    project_path: Path
+    frameworks: List[str]
+
+    def has_framework(self, name: str) -> bool: ...
+
+
+@runtime_checkable
+class LanguageBackend(Protocol):
+    """The extension seam every P4 sub-issue plugs into.
+
+    An implementation owns everything language-coupled for one language:
+    parsing, symbol extraction, detectors, name-resolution policy, CFG/taint
+    tables, framework detection, and module-id derivation. The engine layer
+    (scanner, cli/commands, server/handlers, cortex) is expected to obtain a
+    backend from `lang.registry` and never import a concrete implementation.
+    """
+
+    name: str
+    """Backend identifier, e.g. "python" | "java"."""
+
+    file_extensions: Tuple[str, ...]
+    """Source file suffixes this backend claims, e.g. (".py",) | (".java",)."""
+
+    project_markers: Tuple[str, ...]
+    """Files whose presence in a project root signals this language, e.g.
+    ("pyproject.toml", "setup.py") | ("pom.xml", "build.gradle")."""
+
+    def parser(self) -> LanguageParser:
+        """P4.1 — tree-sitter `Language` + query map for this grammar."""
+        ...
+
+    def extractor(self) -> SymbolExtractor:
+        """P4.2 — CST -> `AnalysisResult` symbol walk."""
+        ...
+
+    def detectors(self) -> List[BaseDetector]:
+        """P4.3 — this language's detector set."""
+        ...
+
+    def resolver_config(self) -> ResolverConfig:
+        """P4.4 — name-resolution rules + deny-list."""
+        ...
+
+    def cfg_config(self) -> CFGConfig:
+        """P4.6 — CFG node kinds + taint sources/sinks."""
+        ...
+
+    def project_config(self, root: Path) -> ProjectConfig:
+        """P4.7 — framework detection for the project rooted at `root`."""
+        ...
+
+    def module_name(self, file: Path, root: Path) -> str:
+        """P4.5 — derive the `module:qualname` module id for `file`."""
+        ...

package/adl_drift/lang/java/__init__.py

@@ -0,0 +1,6 @@
+"""Landing spot for the Java `LanguageBackend` (P4.1, PROBLEMS.md).
+
+Implemented pieces: parser (P4.1), symbol extraction (P4.2), detectors (P4.3),
+package/overload identity (P4.5), shared model support (P4.9), and Maven/Gradle
+project configuration (P4.7). Resolution and CFG/taint land later.
+"""