P0: Scope and complete lifecycle, middleware, error, and background surfaces

[shaggitza]

Priority

P0 — framework/effect inventory completeness.

Problem

Framework surfaces are not consistently scoped to the selected application, and common lifecycle/error/middleware/background registrations are omitted or modeled with incorrect confidence.

Evidence:

• src/fastapi_endpoint_detector/parser/custom_surface_extractor.py:218-296,568-741,1050-1135,1243-1279
• src/fastapi_endpoint_detector/presets/framework_v1.yaml:10-135
• src/fastapi_endpoint_detector/analyzer/mypy_analyzer.py:381-399

Reproduced failures:

• Middleware on an unused FastAPI() instance became an established high-confidence surface for the selected app.
• import fastapi; fastapi.FastAPI(lifespan=...), constructor on_startup/on_shutdown, APIRouter lifecycle, and keyword add_event_handler forms were omitted as established-empty.
• Explicit lifespan=None created false limitations.
• An arbitrary lower decorator replacing a lifespan callback still caused the source function's effects to be reported.
• @app.exception_handler, add_exception_handler, project pure-ASGI middleware, indirect BaseHTTPMiddleware subclasses, and singular Response(background=BackgroundTask(fn)) were missed.
• Multiple legitimate middleware/startup handlers collide on duplicate surface IDs and make inventory conditional.

Required design

• Tie every framework surface receiver to the selected app/mount/composition graph.
• Add exact contracts for missing lifecycle forms, exception handlers, pure-ASGI middleware, bounded local MRO middleware lookup, and starlette.background.BackgroundTask.
• Classify module-qualified constructors correctly; treat literal None as absent; support positional-or-keyword selectors.
• Separate decorator application from the registered callback identity. Require trusted contextlib.asynccontextmanager shape for established lifespan phase splitting.
• Add contract-level multiplicity semantics (all execute, last wins, etc.).
• Keep exception handlers as exception-keyed framework surfaces; do not blindly fan them to every endpoint.

Acceptance criteria

• Unused/unmounted apps cannot contribute selected surfaces.
• Direct, constructor, router, include, keyword, mounted, and multiple-handler lifecycle variants are covered.
• Exception handlers, singular/plural background tasks, pure ASGI, and class middleware have focused tests.
• Replacing/untrusted decorators downgrade inventory instead of tracing stale callbacks.
• Every omitted dynamic surface yields a limitation, not established-empty inventory.

Related: #104.