P0: Build a shared hybrid evidence graph and source inventory

[shaggitza]

Priority

P0 — architecture required to execute the accuracy roadmap without fragmenting evidence.

Problem

The current pipeline needs one shared evidence model and source inventory. Several advertised controls are declared but not consumed:

• include_patterns
• exclude_patterns
• follow_imports
• include_test_endpoints
• integrations.use_mypy
• integrations.mypy_config

Evidence:

• src/fastapi_endpoint_detector/config.py:31-49,69-78,165-178
• src/fastapi_endpoint_detector/analyzer/mypy_analyzer.py:473-554

A probe confirmed that use_mypy=False with exclusions covering all Python still constructed MypyAnalyzer. Non-Python/configuration changes can disappear without candidates, orphan, or warning.

Target architecture

baseline + target source snapshots
        |-- shared source/import inventory
        |-- CPython AST registration graph
        |-- typed semantic providers (mypy; optional SCIP/Pyright)
        |-- bounded CFG/callable/receiver analysis
        `-- optional positive runtime observations
                         |
                 versioned evidence graph
 nodes: symbols, registrations, endpoints, resources, observations
 edges: calls, references, includes, mounts, invokes, observes
 provenance: side, file span, engine/version, strength, limitation

No engine disagreement should silently promote an endpoint. Ambiguous or bounded inference remains LOW. Abstention must trigger broader testing rather than “unaffected.”

Engine decisions

• Retain CPython AST as the framework-registration/source-range core.
• Extend mypy first; it has the highest immediate semantic ROI.
• Use a deterministic import graph for source scope, cache invalidation, and roots, never as execution evidence.
• Keep SCIP optional until call edges, inheritance, relative imports, and persistent indexing are hardened.
• Timebox Pyright as a differential typed oracle/provider.
• Use tree-sitter only for parse recovery and changed-region census.
• Use LibCST only where concrete syntax/source metadata is needed.
• Evaluate CodeQL as an offline dataflow oracle, subject to latency/deployment/licensing gates.
• Runtime observations may confirm positive edges but absence proves nothing. Pylance is not an adoptable backend.

Acceptance criteria

• One canonical source inventory is consumed by AST, mypy, SCIP, caches, and benchmarks.
• Every configuration option is implemented end-to-end or rejected when non-default.
• Non-Python/config/contract changes appear as explicit unsupported/unresolved evidence unless a finite dependency contract exists.
• Evidence nodes/edges preserve baseline/target side, source span, engine version, confidence, and limitations.
• Import graph and provider outputs cannot independently promote execution claims.
• Differential-provider disagreements become stored regression fixtures.
• Dynamic imports, reflection, plugins, monkeypatching, native extensions, and production configuration remain explicit soundness limits.

Related: #20, #107, #109, #110.