feat(ducktyping): complete NativeAOT parity closure with strict compatibility gates

[tonyredondo]

Summary

This PR adds NativeAOT-ready DuckTyping for Datadog.Trace by moving DuckTyping proxy generation to build time and registering those proxies at runtime with strict parity checks against the dynamic implementation.

The final model is intentionally simple:

• one canonical map file (--map-file),
• one discovery command (ducktype-aot discover-mappings),
• one generation command (ducktype-aot generate),
• one strict compatibility gate (ducktype-aot verify-compat --failure-mode strict).

ducktype-aot generate now also supports a one-step mode (--discover-mappings) that discovers compatible mappings and writes --map-file before generation.

Why

NativeAOT support for Datadog.Trace is being built incrementally. DuckTyping was a major blocker because dynamic runtime emit is not compatible with NativeAOT constraints.

This PR closes that gap with deterministic AOT artifacts and strict compatibility validation.

End result

1) Single canonical mapping contract

• ducktype-aot discover-mappings scans type-level mapping attributes ([DuckType], [DuckCopy], [DuckReverse]) and writes canonical map output.
• ducktype-aot generate consumes that canonical --map-file.
• ducktype-aot verify-compat validates compatibility against the same --map-file and fails in strict mode on:
  • missing/extra mapping identities,
  • any mapped entry with non-compatible status.

2) Simpler CLI surface

• Removed --target-assembly from both:
  • ducktype-aot discover-mappings
  • ducktype-aot generate
• Both commands resolve targets from one or more --target-folder inputs.
• --target-filter remains available to constrain scan scope when needed.
• Added one-step generation mode:
  • ducktype-aot generate --discover-mappings ... --map-file ... --output ...
  • runs discovery first and then generation in the same command.

3) Runtime/emitter parity improvements

• Default interface proxies now emit as value-type proxies.
• [DuckAsClass] interface proxies remain class proxies.
• AOT registration adds typed activator paths via RuntimeMethodHandle.
• Bootstrap uses method-handle activator registration.
• Avoidable boxing in typed activator paths is removed where parity allows.
• Required value-type/object boxing at IDuckType boundaries is preserved for parity.
• Property metadata emission was improved so property-shaped contracts emit property metadata (instead of method-only get_/set_ emission).

4) Strict gate and deterministic artifacts

• Build/test gate now uses canonical-map contract with strict verify.
• Discover output can be used for drift checks against the checked-in canonical map.
• Compatibility matrix/report + manifest/trimmer/props artifacts remain deterministic.

5) Tests and docs

• Tooling/runtime/parity tests were expanded and updated for the simplified contract.
• Added coverage for the one-step generate --discover-mappings flow.
• DuckType AOT-focused suites are passing.
• NativeAOT DuckTyping docs and onboarding were updated to match current command contracts.

Quick usage

One-step generate (discover + generate)

dotnet tracer/src/Datadog.Trace.Tools.Runner/bin/Release/Tool/net8.0/Datadog.Trace.Tools.Runner.dll \
  ducktype-aot generate \
  --discover-mappings \
  --proxy-assembly /abs/path/ProxyContracts.dll \
  --target-folder /abs/path/bin/Release/net8.0 \
  --target-filter "*.dll" \
  --map-file /abs/path/ducktype-aot-map.json \
  --output /abs/path/Datadog.Trace.DuckType.AotRegistry.dll

Explicit two-step flow

dotnet tracer/src/Datadog.Trace.Tools.Runner/bin/Release/Tool/net8.0/Datadog.Trace.Tools.Runner.dll \
  ducktype-aot discover-mappings \
  --proxy-assembly /abs/path/ProxyContracts.dll \
  --target-folder /abs/path/bin/Release/net8.0 \
  --target-filter "*.dll" \
  --output /abs/path/ducktype-aot-map.json

dotnet tracer/src/Datadog.Trace.Tools.Runner/bin/Release/Tool/net8.0/Datadog.Trace.Tools.Runner.dll \
  ducktype-aot generate \
  --proxy-assembly /abs/path/ProxyContracts.dll \
  --target-folder /abs/path/bin/Release/net8.0 \
  --target-filter "*.dll" \
  --map-file /abs/path/ducktype-aot-map.json \
  --output /abs/path/Datadog.Trace.DuckType.AotRegistry.dll

Verify strict compatibility

dotnet tracer/src/Datadog.Trace.Tools.Runner/bin/Release/Tool/net8.0/Datadog.Trace.Tools.Runner.dll \
  ducktype-aot verify-compat \
  --compat-report /abs/path/Datadog.Trace.DuckType.AotRegistry.dll.compat.md \
  --compat-matrix /abs/path/Datadog.Trace.DuckType.AotRegistry.dll.compat.json \
  --map-file /abs/path/ducktype-aot-map.json \
  --manifest /abs/path/Datadog.Trace.DuckType.AotRegistry.dll.manifest.json \
  --failure-mode strict

Reviewer focus

Please focus on:

• DuckTypeAotRegistryAssemblyEmitter (proxy shape/IL + activator emission),
• DuckTypeAotEngine (typed activator registration/materialization),
• discover/generate/verify processors (single map contract + strict behavior),
• one-step generate path (--discover-mappings) and map-file semantics,
• build gate wiring and drift-check behavior.