fix(admin): union/TypeVar-safe bean introspection — admin bean-graph 500 (v26.06.99)

[ancongui]

Summary

Fixes the admin dashboard #bean-graph 500 (and /beans, /beans/{name}) that occurs whenever a bean's registration key is not a plain class.

Root cause: the idiomatic @bean def make_foo(self) -> Foo | None. typing.get_type_hints preserves Foo | None as a types.UnionType, and ApplicationContext._process_configurations registered that union object directly as a _registrations key. A types.UnionType (and TypeVar) has no __name__/__qualname__/__module__, so BeansProvider — which derived bean names/types straight from the key — raised AttributeError: 'types.UnionType' object has no attribute '__name__'.

⚠️ This only became visible after the v26.06.95 union-safe startup fix: before, a union bean crashed startup (you never reached the dashboard); after, the app boots and the bean-graph endpoint crashes instead. None of the v26.06.95–98 commits touched beans_provider.py, so pulling alone did not fix it.

Fix (defense in depth, 3 layers)

Layer	Change
Source	ApplicationContext no longer registers a non-class return hint as a _registrations key. The concrete type(result) registration already backs single-bean resolution, so nothing is lost.
Provider	BeansProvider derives names/types via union/TypeVar-safe _key_name/_key_qualname helpers; condition values coerced JSON-safe; a raising on_class check() is reported not-passed; a raising descriptor in the autowired scan is skipped.
Backstop	Admin API handlers convert any unexpected error into a logged, structured JSON 500 instead of a raw Starlette 500.

Also covers three additional reproduced /beans/{name} detail 500s (generic-alias conditions, raising on_class check, raising descriptor), and realigns the stale pyfly.__version__ (26.06.94 → 26.06.99) that fed the dashboard framework_version, CLI banner, SBOMs, and admin asset cache-busting.

Why it slipped through

The prior admin tests (test_beans_provider_enhanced.py) use a mocked container whose keys are always vanilla classes — real type-hint resolution was never exercised. New regression tests drive the real ApplicationContext/Container:

• tests/context/test_bean_method_union_return.py (the exact @bean -> Foo | None scenario, end to end through the admin provider)
• tests/admin/test_beans_provider_realcontext.py (union/TypeVar keys, generic-alias conditions, raising check, raising descriptor)

Verification

• ruff check ✓ · ruff format --check ✓ · mypy src/pyfly --strict ✓ (changed files)
• Affected suites green: tests/admin tests/context tests/container tests/cli tests/observability → 807 passed
• New regression tests fail on main, pass here.

🤖 Generated with Claude Code