Proposal: Replace autoTypes.json DECLARE_HANDLE entries with header annotations

[jevansaks]

Summary

Adds a validated proposal to shift the ~166 DECLARE_HANDLE entries from autoTypes.json into header annotations, mirroring the conditional-declaration pattern from the enum remapping proposal (#2247).

The approach defines DECLARE_HANDLE_WIN32METADATA(name, ...) plus _Close_handle_with_ / _Invalid_handle_ / _Also_usable_for_ macros. Under -D_WIN32METADATA_=1, DECLARE_HANDLE expands to a wrapper struct that ClangSharp v18 emits directly with [NativeAnnotation] attributes; MetadataSyntaxTreeCleaner translates them into the existing [RAIIFree], [InvalidHandleValue], [AlsoUsableFor], and [NativeTypedef]. The winmd output is byte-identical to today.

Validated end-to-end with ClangSharp v18.1.0.4 (test files in obj/handle-annotation-test/).

What's in the proposal

• Core mechanism — annotated DECLARE_HANDLE redefinition + SAL-style annotation macros
• Empirical evidence — 11 patterns tested through ClangSharp v18; only the struct [[attr]] NAME { ... } shape preserves annotations on the right declaration. C++11 attributes cannot precede struct at namespace scope, which is why we need a macro that takes attributes via __VA_ARGS__.
• Projection behavior — confirmed by reading CsWin32 and windows-rs source: both projections read the attributes by name, generate conversion code (implicit operators / From + CanInto) for [NativeTypedef] structs, and require no projection-side changes.
• Scope — explicitly DECLARE_HANDLE-only; sibling DECLARE_TYPEDEF_WIN32METADATA(name, type, ...) macro sketched for the remaining ~83 typedef-style handles and value wrappers (BCRYPT, EVT, MSI, BOOL, HRESULT, NTSTATUS, BSTR, etc.) as a follow-up.
• One drop — recommend deleting DEVPROPKEY=[AlsoUsableFor("PROPERTYKEY")] from emitter.settings.rsp; both CsWin32 and windows-rs only generate AlsoUsableFor code for [NativeTypedef]-shaped structs, so this entry is dormant.

Open questions called out in the proposal

1. [InvalidHandleValueAttribute] constructor takes long — annotation strings need the right parsing
2. Where to host the same-namespace validation that NativeTypedefStructsCreator does today
3. Empty-namespace handle entries (~38) — namespace currently derived from CloseApi's namespace; with shift-left it comes from header partition placement
4. Overlay headers vs. in-place SDK header patches for prototyping (matches the approach used in Proposal: Replace enums.json with conditional C++ enum declarations #2247)

Companion changes

Also updates annotation-validation-results.md with a summary table of the remaining shift-left categories after the enum proposal landed, so future readers can see where this fits in the larger workstream.