[Task] Close plugin contract loop: Documentation, Samples, Benchmarking and NuGet Release

[rian-be]

Summary

Close the publishing and operations loop for the plugin contract: a readable contract README with concrete examples, a realistic OAuth2/OIDC reference plugin, a plugin loading benchmark with defined methodology, and precise, source of truth versioning/packaging pipeline for the AuthKit.Plugins.Abstractions NuGet package.

Goal

Make the contract consumable and maintainable as publishable artifact: documentation people can read, realistic auth example to copy, a repeatable loading baseline for regression detection, and versioned package whose source of truth is unambiguous.

Background

The abstractions project has no dedicated README, no OAuth2/OIDC reference sample, no loading cost baseline as the contract grows, and no single source of truth for package version/changelog/release, so the package cannot be published consistently.

Scope

ID	Deliverable	Shape	Acceptance
H11	Contract README	README.md in the abstractions area: one minimal plugin example covering metadata, health, middleware, security scheme, and lifecycle (where part of the contract), plus pointers to HelloAuthKitPlugin (H7) for the full example. Does not replicate H7 or serve as H6 level API reference.	Single readable entry point no prose duplication of H7/H6.
H12	OAuth2/OIDC reference sample	samples/ plugin declaring realistic AuthKitSecuritySchemeDescriptor (Section E: E3/E5/E9) and loading successfully in the host. Declares the contract surface for OAuth2/OIDC, not a full IdP integration see Non Goals.	Sample compiles, loads via plugin discovery, and PluginContractValidator passes.
H13	Loading benchmark	benchmarks/ project with repeatable benchmark over defined plugin/assembly matrix, recording baseline against which future changes can be compared.	Benchmark is repeatable baseline is recorded for the defined matrix.
H14	NuGet versioning / release	AuthKit.Plugins.Abstractions published with clear source of truth for version, consistent dotnet pack, release tagging, and changelog generation. Scope: packaging and release pipeline, not API change. See boundary note below.	dotnet pack produces consistently versioned package version has single source of truth.

H11 what the README contains (and does not)

README is the single readable entry point: "How do I use the AuthKit plugin contract?"

Role of each doc layer:

Layer	Purpose
README (H11)	How to use the contract
XML-doc / H6	What every property and method means (API detail)
HelloAuthKitPlugin / H7	What complete plugin looks like

README must not replicate H7 or H6. It contains: one minimal plugin example (metadata, health, middleware, security scheme, lifecycle as applicable), pointers to HelloAuthKitPlugin for full detail, and links to the Keycloak sample for a realistic scenario.

H12 host loaded, not bundled IdP

The sample is plugin, not an IdP. It declares realistic AuthKitSecuritySchemeDescriptor with OAuth2/OIDC fields (E3/E5/E9) and loads successfully in the host, showing the contract surface for real world auth scenarios.

Full integration with running Keycloak instance (Docker Compose + real token flow) is valuable follow up, but sits outside this task's scope see Non Goals.

H13 measurement, not performance engineering

Benchmark must answer: what exactly are we measuring, under what conditions?

Defined boundaries (each measured independently where possible):

Discovery -> Assembly loading -> Dependency resolution -> Activation -> Lifecycle initialization

Parameters for the defined matrix:

Parameter	Description
N plugins	number of plugins in the matrix
N assemblies	total assembly count (plugin + transitive)
cold vs warm	first load vs subsequent load (JIT, assembly load context)

Benchmark shape:

• Repeatable, deterministic, with recorded baseline for the defined matrix.
• Documented environment (runtime version, OS, hardware summary) so baselines are comparable.
• Regression threshold documented but no automated CI gate in this task.
• No micro optimization work ships measurement only.

H14 precise versioning, source of truth

Scope boundary: H14 covers the packaging and release pipeline for the public abstractions package. It standardizes how the package is versioned, packed, and released without changing its API surface. Publishing/release engineering is conceptually adjacent to Section H if it grows beyond the abstractions package

Source of truth must be explicit and unambiguous:

Directory.Build.props (<Version>)
        ↓
AuthKit.Plugins.Abstractions.csproj
        ↓
dotnet pack → NuGet package version
        ↓
Git tag → release
        ↓
Changelog (auto generated or manual)

Requirements for H14:

• Single source of truth for the package version (eg. Directory.Build.props; no drift between .csproj, tag, NuGet, changelog).
• dotnet pack produces a consistently versioned AuthKit.Plugins.Abstractions package.
• Release tagging aligned with package version.
• Changelog generation (automated or manual) documents what changed per release.
• Breaking changes require major version bump (documented convention, not yet CI enforced).
• PluginContractValidator remains the contract integrity gate H14 does not replace it.

API compatibility detection (breaking change detection at pack/CI time) is valuable follow up issue, not part of this task.

Decisions

• H11 is the single readable reference for the contract H6 (XML doc) generates API level detail the two do not overlap. README does not replicate HelloAuthKitPlugin.
• H12 depends on Section E (OAuth2 flows/URLs/issuer fields E3/E5/E9), which is currently spec only design. The sample lands together with (or after) the descriptor work.
• H13 only measures no micro optimization work or performance gates ship in this task. Benchmark is repeatable, documented, and records baseline for the defined plugin/assembly matrix.
• H14 standardizes the release pipeline for AuthKit.Plugins.Abstractions; the version source of truth is explicit (eg. Directory.Build.props); no drift between .csproj, tag, NuGet, and changelog. Breaking changes require major bump (convention, not CI enforced in this task).
• H14 sits at the boundary of Section H and future publishing/release section it is included here because the first versioning/pack scope is small enough if it grows, move to dedicated section.

Validation

• Contract README exists, is readable, and contains minimal example + pointers to H7/H12 no prose duplication of H7 or H6.
• Keycloak/OAuth2 sample compiles, loads via plugin discovery, declares an OAuth2/OIDC AuthKitSecuritySchemeDescriptor; PluginContractValidator passes.
• Benchmark is repeatable and records baseline for the defined plugin/assembly matrix (documented environment, N plugins, cold/warm).
• dotnet pack produces consistently versioned AuthKit.Plugins.Abstractions package with no drift between source of truth, .csproj, Git tag, NuGet version, and changelog.
• Breaking change -> major version bump convention documented.

Acceptance Criteria

• The contract has single, readable README that serves as the primary entry point, with no duplication of H7/H6.
• A realistic OAuth2/OIDC plugin example exists and loads in the host.
• A repeatable loading baseline exists for regression detection, with documented methodology and environment.
• The abstractions package is publishable with an unambiguous, single source of truth version and release pipeline.

Non Goals

• No API reference generation in the README (covered by H6/XML doc).
• No Keycloak server bundled the sample is a plugin, not an IdP, full IdP integration is follow up.
• No micro optimization work H13 is measurement only.
• No API surface change in H14 no performance gates or automated CI regression thresholds in this task.
• No API compatibility / breaking change detection tooling in this task (follow up issue).
• No dedicated publishing/release section in this task H14 is the small, first versioning scope within Section H.

Boundary note

Note

H14 (packaging/release) sits at the boundary of Section H (Observability, DX and tests) and future dedicated section (next available letter: L) for publishing and release engineering. If the packaging scope grows beyond AuthKit.Plugins.Abstractions versioning, H14 should move to that section.