[cDAC] Validate contract presence in interface returning functions

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/CdacHResults.cs

@@ -0,0 +1,66 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.Diagnostics.DataContractReader;
+
+/// <summary>
+/// cDAC-specific <c>HRESULT</c>s surfaced when creating a data-access interface
+/// for a target fails for a reason this cDAC can describe precisely. This covers two stages of
+/// creation: locating and reading the target's contract descriptor (the <c>DESCRIPTOR</c> codes),
+/// and eager validation that this cDAC can service the contracts the descriptor advertises (the
+/// <c>CONTRACT</c> codes, see
+/// <see cref="Microsoft.Diagnostics.DataContractReader.Contracts.CoreCLRContracts.ValidateForDataAccess"/>).
+/// </summary>
+/// <remarks>
+/// The customer bit (bit 29, <c>0x20000000</c>) is set on every value so these codes can never
+/// collide with system or CLR (corerror.h) <c>HRESULT</c>s. All values are failure codes, so
+/// existing <c>FAILED(hr)</c> checks in native callers continue to behave correctly. Native code
+/// and tooling that wants to distinguish the failure modes (for example, to decide whether to fall
+/// back to the brittle DAC) can compare against the literal values documented here.
+/// </remarks>
+public static class CdacHResults
+{
+    /// <summary>
+    /// A contract required to service the SOS interface is not advertised by the target's
+    /// contract descriptor. The target runtime predates the contract or does not expose it.
+    /// </summary>
+    public const int CDAC_E_CONTRACT_NOT_ADVERTISED = unchecked((int)0xA0DAC001);
+
+    /// <summary>
+    /// The target advertises a required contract at a version this cDAC does not recognize,
+    /// typically because the target runtime is newer than this cDAC.
+    /// </summary>
+    public const int CDAC_E_CONTRACT_UNRECOGNIZED = unchecked((int)0xA0DAC002);
+
+    /// <summary>
+    /// The target advertises a required contract at a version this cDAC recognizes but
+    /// intentionally does not implement, typically because the target runtime is too old.
+    /// </summary>
+    public const int CDAC_E_CONTRACT_UNSUPPORTED = unchecked((int)0xA0DAC003);
+
+    /// <summary>
+    /// A required contract could not be validated and the cause could not be classified as one of
+    /// the more specific CONTRACT codes above. This is the default HRESULT carried by the
+    /// <see cref="ContractNotAvailableException"/> base type.
+    /// </summary>
+    public const int CDAC_E_CONTRACT_UNAVAILABLE = unchecked((int)0xA0DAC004);
+
+    /// <summary>
+    /// No usable cDAC contract descriptor could be located for the target: the contract locator
+    /// did not produce a descriptor address, the descriptor header could not be read, or the bytes
+    /// at the descriptor address are not a contract descriptor (bad magic). This typically means the
+    /// target is not a cDAC-capable .NET runtime (for example, a non-.NET target or a runtime that
+    /// predates the cDAC contract descriptor), and tooling should fall back to the brittle DAC
+    /// rather than treat it as a hard error.
+    /// </summary>
+    public const int CDAC_E_DESCRIPTOR_NOT_FOUND = unchecked((int)0xA0DAC011);
+
+    /// <summary>
+    /// A cDAC contract descriptor was found but could not be consumed: a field could not be read,
+    /// the embedded JSON failed to parse, or the descriptor content is internally inconsistent
+    /// (for example, duplicate names or an out-of-range pointer-data index). This indicates a
+    /// corrupt dump or a descriptor format this cDAC cannot understand, and is distinct from a
+    /// recognized-but-unsupported contract version (<see cref="CDAC_E_CONTRACT_UNSUPPORTED"/>).
+    /// </summary>
+    public const int CDAC_E_DESCRIPTOR_MALFORMED = unchecked((int)0xA0DAC012);
+}

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/ContractNotAvailableException.cs

@@ -0,0 +1,109 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+
+namespace Microsoft.Diagnostics.DataContractReader;
+
+/// <summary>
+/// Exception for failures to retrieve a data contract from a target. The concrete subclasses
+/// describe the specific cause; this base type is also thrown directly for an unclassified
+/// validation failure. Each concrete subclass sets a distinct <see cref="CdacHResults"/> value on
+/// <see cref="System.Exception.HResult"/> so both the eager validation path
+/// (<see cref="Microsoft.Diagnostics.DataContractReader.Contracts.CoreCLRContracts.ValidateForDataAccess"/>)
+/// and the lazy SOS data-access path surface the same self-describing failure code with no wrapping
+/// or translation. The base defaults to <see cref="CdacHResults.CDAC_E_CONTRACT_UNAVAILABLE"/> so an
+/// unclassified failure still carries a cDAC-specific failure code rather than <c>S_OK</c>.
+/// </summary>
+public class ContractNotAvailableException : Exception
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContractNotAvailableException"/> class.
+    /// </summary>
+    /// <param name="contractName">The name of the requested contract.</param>
+    /// <param name="contractVersion">The target-advertised version of the requested contract, or <see langword="null"/> if the target did not advertise the contract.</param>
+    /// <param name="message">The exception message.</param>
+    public ContractNotAvailableException(string contractName, string? contractVersion, string message)
+        : base(message)
+    {
+        ContractName = contractName;
+        ContractVersion = contractVersion;
+        HResult = CdacHResults.CDAC_E_CONTRACT_UNAVAILABLE;
+    }
+
+    /// <summary>
+    /// Gets the name of the requested contract.
+    /// </summary>
+    public string ContractName { get; }
+
+    /// <summary>
+    /// Gets the target-advertised version of the requested contract, or <see langword="null"/> if the target did not advertise the contract.
+    /// </summary>
+    public string? ContractVersion { get; }
+}
+
+/// <summary>
+/// Exception thrown when the target's contract descriptor does not advertise the requested contract.
+/// </summary>
+public sealed class ContractMissingException : ContractNotAvailableException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContractMissingException"/> class.
+    /// </summary>
+    /// <param name="contractName">The name of the requested contract.</param>
+    public ContractMissingException(string contractName)
+        : base(contractName, null, $"Contract '{contractName}' is not advertised by the target.")
+    {
+        HResult = CdacHResults.CDAC_E_CONTRACT_NOT_ADVERTISED;
+    }
+}
+
+/// <summary>
+/// Exception thrown when the target advertises the requested contract, but this cDAC cannot provide an implementation for the advertised version.
+/// </summary>
+public abstract class ContractUnsupportedException : ContractNotAvailableException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContractUnsupportedException"/> class.
+    /// </summary>
+    /// <param name="contractName">The name of the requested contract.</param>
+    /// <param name="contractVersion">The target-advertised version of the requested contract.</param>
+    /// <param name="message">The exception message.</param>
+    protected ContractUnsupportedException(string contractName, string contractVersion, string message)
+        : base(contractName, contractVersion, message)
+    { }
+}
+
+/// <summary>
+/// Exception thrown when the target advertises a contract version that this cDAC does not recognize, typically because the target runtime is newer than this cDAC.
+/// </summary>
+public sealed class ContractUnrecognizedException : ContractUnsupportedException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContractUnrecognizedException"/> class.
+    /// </summary>
+    /// <param name="contractName">The name of the requested contract.</param>
+    /// <param name="contractVersion">The target-advertised version of the requested contract.</param>
+    public ContractUnrecognizedException(string contractName, string contractVersion)
+        : base(contractName, contractVersion, $"Contract '{contractName}' version {contractVersion} is advertised by the target but is not recognized by this cDAC.")
+    {
+        HResult = CdacHResults.CDAC_E_CONTRACT_UNRECOGNIZED;
+    }
+}
+
+/// <summary>
+/// Exception thrown when the target advertises a contract version that this cDAC recognizes but intentionally does not implement, typically because the target runtime is too old.
+/// </summary>
+public sealed class ContractObsoleteException : ContractUnsupportedException
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContractObsoleteException"/> class.
+    /// </summary>
+    /// <param name="contractName">The name of the requested contract.</param>
+    /// <param name="contractVersion">The target-advertised version of the requested contract.</param>
+    public ContractObsoleteException(string contractName, string contractVersion)
+        : base(contractName, contractVersion, $"Contract '{contractName}' version {contractVersion} is advertised by the target and recognized by this cDAC, but is intentionally not implemented.")
+    {
+        HResult = CdacHResults.CDAC_E_CONTRACT_UNSUPPORTED;
+    }
+}

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/ContractRegistry.cs

@@ -157,19 +157,19 @@ public abstract class ContractRegistry
     /// <param name="contract">
     /// When this method returns <see langword="true"/>, contains the requested contract instance; otherwise, <see langword="null"/>.
     /// </param>
-    /// <param name="failureReason">
-    /// When this method returns <see langword="false"/>, contains a human-readable explanation of why the contract could not be retrieved; otherwise, <see langword="null"/>.
+    /// <param name="failureException">
+    /// When this method returns <see langword="false"/>, contains the exception that describes why the contract could not be retrieved; otherwise, <see langword="null"/>.
     /// </param>
     /// <returns>
     /// <see langword="true"/> if the requested contract is present and was retrieved successfully; <see langword="false"/> if the contract is not present or registered"/>.
     /// </returns>
-    public abstract bool TryGetContract<TContract>([NotNullWhen(true)] out TContract contract, out string? failureReason) where TContract : IContract;
+    public abstract bool TryGetContract<TContract>([NotNullWhen(true)] out TContract contract, [NotNullWhen(false)] out System.Exception? failureException) where TContract : IContract;
 
     public TContract GetContract<TContract>() where TContract : IContract
     {
-        if (!TryGetContract(out TContract contract, out string? failureReason))
+        if (!TryGetContract(out TContract contract, out System.Exception? failureException))
         {
-            throw new NotImplementedException($"Contract '{typeof(TContract).Name}' is not supported by the target. Reason: {failureReason ?? "no reason provided"}");
+            throw failureException ?? new ContractMissingException(TContract.Name);
         }
         return contract;
     }
@@ -179,13 +179,44 @@ public bool TryGetContract<TContract>([NotNullWhen(true)] out TContract contract
         return TryGetContract(out contract, out _);
     }
 
+    /// <summary>
+    /// Determines whether this cDAC can provide the requested contract for the target. Implementations
+    /// should resolve the target-advertised version against the registered implementations only, without
+    /// instantiating the contract, so that validation performs no target memory reads (safe on partial or
+    /// triage dumps) and never triggers contract-to-contract chaining.
+    /// </summary>
+    /// <typeparam name="TContract">The contract type to validate.</typeparam>
+    /// <param name="failureException">
+    /// When this method returns <see langword="false"/>, contains the exception describing why the
+    /// contract cannot be provided; otherwise, <see langword="null"/>.
+    /// </param>
+    /// <returns>
+    /// <see langword="true"/> if the contract is advertised by the target and a matching implementation
+    /// is registered; otherwise, <see langword="false"/>.
+    /// </returns>
+    /// <remarks>
+    /// The default implementation delegates to <see cref="TryGetContract{TContract}(out TContract, out System.Exception?)"/>,
+    /// which instantiates the contract and therefore does read target memory. Registries that need the
+    /// no-instantiation guarantee above must override this method (<c>CachingContractRegistry</c> does).
+    /// </remarks>
+    public virtual bool TryValidate<TContract>([NotNullWhen(false)] out System.Exception? failureException) where TContract : IContract
+    {
+        return TryGetContract<TContract>(out _, out failureException);
+    }
+
     /// <summary>
     /// Register a contract implementation for a specific version.
     /// External packages use this to add contract versions or entirely new contract interfaces.
     /// </summary>
     public abstract void Register<TContract>(string version, Func<Target, TContract> creator)
         where TContract : IContract;
 
+    /// <summary>
+    /// Register a contract version that is recognized but intentionally not implemented.
+    /// </summary>
+    public abstract void RegisterUnsupported<TContract>(string version)
+        where TContract : IContract;
+
     /// <summary>
     /// Flush all cached data held by contracts in this registry for the given
     /// <paramref name="scope"/>. Called when the target process state may have changed

src/native/managed/cdac/Microsoft.Diagnostics.DataContractReader.Abstractions/Target.cs

@@ -339,6 +339,16 @@ public readonly record struct FieldInfo
     /// </summary>
     public abstract ContractRegistry Contracts { get; }
 
+    /// <summary>
+    /// <see langword="true"/> when the named sub-descriptor has been published by the target and
+    /// parsed into the registry (or was never advertised). A sub-descriptor is written lazily by a
+    /// subordinate module (for example the GC), so a target attached very early - before that module
+    /// publishes its sub-descriptor address (see dotnet/runtime#128215) - reports <see langword="false"/>
+    /// for that name until a later <see cref="Flush"/> picks it up.
+    /// </summary>
+    /// <param name="name">The sub-descriptor name (for example <c>"GC"</c>).</param>
+    public virtual bool IsSubDescriptorResolved(string name) => true;
+
     /// <summary>
     /// Clear cached data held by this target for the given <paramref name="scope"/>.
     /// Called when the target process state may have changed (e.g. on resume).