[SPoA/Clean Code] Classify and diagnose RuntimeOverlayActivator failures #118

Audit finding

RuntimeOverlayActivator.Activate wraps profile resolution, request construction, native overlay activation and application-state transition in one catch (Exception) block. Every exception is converted into the same user-facing fault path, and this boundary does not emit the full failure through the structured diagnostics authority.

This can make a programming/contract error appear identical to an expected operational overlay failure and can discard the diagnostic context needed to correct the defect.

Target state

Define an explicit activation-failure policy that distinguishes expected runtime/native failures from invariant or programming failures while preserving safe overlay shutdown.

Use the existing Diagnostics and native failure policy rather than adding another logger.

Acceptance criteria

• Every failed activation is reported through Diagnostics with component, operation, activation mode, target handle and exception details.
• Expected operational/native failures disable the overlay, transition to Fault and show the current user-facing notification.
• Contract/invariant failures are not silently reduced to only a user message; they follow an explicit report-and-rethrow or fail-fast policy suitable for production and tests.
• Cleanup failure does not replace the primary activation exception.
• Automatic activation still records the suppressed target needed for recovery behavior.
• Tests cover expected native failure, profile/contract failure, cleanup failure and successful activation.
• Architecture documentation describes the classification boundary.

Completion evidence — 2026-09-24

Implemented in PR #160 and merged as e9ef6373ad8ed4c75c48d544a8b3c3cf978b6c29.

Verified checks:

• DCO run 36002397999 — success;
• full Windows build/test/release-compliance run 36002398000 — success.

Runtime target discovery and user feedback are now separate named ports composed in SightAdaptContext. Overlay activation failures are classified and diagnosed: expected native/availability failures recover into a safe fault state with automatic-target suppression, while contract/programming failures are diagnosed, cleaned up best-effort and rethrown without cleanup replacing the primary exception.