[Feature] Structural Health Checks

[rian-be]

Summary

Extend the AuthKit plugin contract and host health infrastructure with structured plugin health checks.

The goal is to replace simple health signaling with strongly typed and extensible health model that allows plugins to report health status, diagnostic information, and classification metadata while allowing the host to execute, aggregate, cache, and expose health information safely and efficiently.

Goal

Provide complete, first class implementation of structural health checks across the AuthKit plugin contract and host infrastructure.

The implementation should allow the host to determine plugin health and readiness while preserving backward compatibility with existing plugins wherever possible.

Problem

The current plugin contract does not provide structured health reporting model.

A simple boolean health result cannot express:

• healthy, degraded, and unhealthy states,
• failure reasons,
• plugin diagnostic information,
• classification and filtering metadata,
• multiple health observations,
• structured aggregation by the host,
• or execution related information observed by the host.

In addition, health checks may require scoped dependencies, cancellation support, and result caching to avoid expensive operations being performed on every health request.

Scope

This is the parent issue for Section D.

Implementation is divided into the following sub- ssues:

• [Task] Introduce PluginHealthResult and Structured Health Status #14
• [Task] Extend the Plugin Health Check Contract #15
• [Task] Add Health Metadata, Tags, and Diagnostics #16
• [Task] Host Health Execution, Caching, and Scoped Dependencies #17

Design Expectations

• Implementation must remain consistent with the existing AuthKit.Plugins.Abstractions style, including interfaces, records, naming, and XML documentation.
• Changes should be additive and preserve existing plugin compatibility where possible.
• Existing plugins, including DevTokens, should continue to compile and load without modification.
• Health APIs should remain straightforward to test through unit and integration tests.
• Avoid introducing new external dependencies without explicit agreement.
• Health checks must not introduce unbounded or unnecessary work on every host health request.
• Strongly typed health properties must remain authoritative over arbitrary diagnostic metadata.
• Plugin diagnostic metadata and host-observed execution metadata must remain semantically distinct.

Compatibility

• Preserve existing IAuthKitPlugin compatibility where possible.
• Existing plugins must not require immediate source changes.
• Default behavior for plugins that do not implement the extended health contract must remain explicitly defined.
• No existing interface method may have its return type silently replaced in breaking manner.
• No breaking contract changes may be introduced without an explicit migration or compatibility path.
• Existing plugin behavior outside the health infrastructure must remain unchanged.

Validation

dotnet build AuthKit.Plugins.Abstractions
dotnet test
PluginContractValidator

Validation across Section D must include:

• structured health result serialization,
• health contract compatibility,
• strongly typed health status behavior,
• diagnostic metadata preservation,
• health tag preservation and filtering,
• cancellation behavior,
• multiple health result handling,
• host side aggregation behavior,
• scoped dependency resolution,
• scope disposal,
• execution latency measurement,
• result caching and TTL expiration,
• concurrent health request behavior,
• and continued DevTokens compatibility.

Acceptance Criteria

• All Section D sub issues are closed and meet their individual acceptance criteria.
• Structured plugin health reporting is available through the plugin contract.
• Healthy, Degraded, and Unhealthy remain explicitly distinguishable.
• Plugin health results support optional reasons, diagnostic data, and classification tags.
• Existing plugins remain compatible according to the defined migration and default behavior.
• The health contract supports cancellation according to the execution contract defined by Section D.
• Multiple plugin health results can be preserved and consumed by the host.
• The host can execute plugin health checks safely using appropriate dependency injection scopes.
• Scoped dependencies are correctly disposed after health check execution.
• Host observed execution latency is measured without requiring plugins to implement their own timing logic.
• Expensive health checks can be cached by the host using a defined TTL policy.
• Cached results expire and refresh according to the configured host policy.
• Concurrent health requests do not corrupt cached results or cause cross-plugin result contamination.
• PluginContractValidator passes.
• DevTokens continues to compile and load successfully.
• Relevant documentation is updated.

Non Goals

• No custom dependency injection framework.
• No custom configuration engine.
• No requirement to introduce new external health check framework.
• No unrelated redesign of IAuthKitPlugin.
• No distributed health-result cache unless separately required.
• No fixed global registry of health tags or diagnostic keys.
• No breaking changes without an explicit migration path.