init

enriched-qwen3-coder-next/Common/DTS.Common.Licensing/Messages.md

@@ -0,0 +1,84 @@
+---
+source_files:
+  - Common/DTS.Common.Licensing/Messages/ValidationFailure.cs
+  - Common/DTS.Common.Licensing/Messages/LicenseKey.cs
+  - Common/DTS.Common.Licensing/Messages/ValidationResult.cs
+generated_at: "2026-04-16T03:29:48.963073+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "52e7e10ea2ae6d13"
+---
+
+# Messages
+
+## Documentation: Licensing Validation Messages
+
+### 1. Purpose  
+This module defines core data structures used for representing license validation outcomes and license metadata within the DTS licensing system. It provides strongly-typed message contracts (`ValidationResult`, `ValidationFailure`, `LicenseKey`) that enable consistent communication of license status—such as validity, expiration, version compatibility, and ownership—between licensing validation components and downstream consumers (e.g., UI, service layers, or license enforcement logic). These types serve as the canonical output of license validation operations and are intended to decouple validation logic from business logic by standardizing the shape of validation results.
+
+---
+
+### 2. Public Interface  
+
+#### `ValidationFailure`  
+- **Namespace**: `DTS.Common.Licensing.Messages`  
+- **Properties**:  
+  - `string Message { get; set; }` – A human-readable description of the validation issue (e.g., `"License has expired"`).  
+  - `string HowToResolve { get; set; }` – Guidance on how to remediate the failure (e.g., `"Renew your license at https://example.com/renew"`).  
+- **Behavior**: A simple DTO for encapsulating a single validation failure; no validation or side effects occur upon construction or property assignment.
+
+#### `LicenseKey`  
+- **Namespace**: `DTS.Common.Licensing`  
+- **Properties**:  
+  - `string KeyGuid { get; set; }` – A string representation of the license’s unique identifier (likely a GUID).  
+  - `string PublicKey { get; set; }` – The public key associated with the license (e.g., used for signature verification).  
+- **Behavior**: A lightweight DTO for conveying core license identification and cryptographic material; no validation or processing is performed.
+
+#### `ValidationResult`  
+- **Namespace**: `DTS.Common.Licensing.Messages`  
+- **Properties**:  
+  - `IEnumerable<ValidationFailure> ValidationFailures { get; set; }` – Collection of all validation failures encountered; may be `null` or empty if no failures occurred.  
+  - `bool IsLicenseExpired { get; set; }` – `true` if the license has expired (based on `LicenseExpiration`); `false` otherwise.  
+  - `bool IsLicenseVersionValid { get; set; }` – `true` if the license version is compatible with the current product version; `false` otherwise.  
+  - `Version ProductVersion { get; set; }` – The version of the product being licensed (e.g., `1.2.3.0`).  
+  - `string LicenseVersion { get; set; }` – The version string declared in the license (e.g., `"1.2"`).  
+  - `DateTime? LicenseExpiration { get; set; }` – The expiration date/time of the license; `null` if the license does not expire.  
+  - `bool IsValid { get; set; }` – `true` if *all* validation checks passed (i.e., `ValidationFailures` is empty, `IsLicenseExpired` is `false`, and `IsLicenseVersionValid` is `true`); `false` otherwise.  
+  - `bool IsLicensed { get; set; } = true` – Indicates whether a license file was present and loaded (`true`) or absent (`false`). Default value is `true`.  
+  - `string LicensedTo { get; set; }` – The entity (e.g., company or user name) to whom the license was issued.  
+  - `DataProLicensingEnums.LicenseType LicenseType { get; set; }` – The type of license (e.g., Trial, Standard, Enterprise); defined in `DataProLicensingEnums`.  
+  - `Guid LicenseId { get; set; }` – The unique identifier of the license.  
+- **Behavior**: Encapsulates the complete result of a license validation operation. The `IsValid` property is derived from the combination of other fields (see *Invariants*), not computed independently.
+
+---
+
+### 3. Invariants  
+- **`IsValid` is logically dependent**: `IsValid` must be `true` if and only if:  
+  - `ValidationFailures` is `null` or empty,  
+  - `IsLicenseExpired` is `false`, and  
+  - `IsLicenseVersionValid` is `true`.  
+  *(Note: The source does not enforce this via code—e.g., no setter logic—but it is the intended semantic contract implied by the property name and comments.)*  
+- **`IsLicensed` default**: `IsLicensed` defaults to `true`; a value of `false` explicitly indicates the license file was not found or could not be loaded.  
+- **`LicenseExpiration` may be null**: A `null` value for `LicenseExpiration` signifies a perpetual (non-expiring) license.  
+- **`ValidationFailures` may be null**: The property is not initialized to an empty collection by default, so consumers must handle `null` explicitly.
+
+---
+
+### 4. Dependencies  
+- **Internal dependencies**:  
+  - `System` (via `System.Collections.Generic`, `System.Linq`, `System.Text`, `System.Threading.Tasks`, `System` implicitly for `Version`, `DateTime`, `Guid`).  
+  - `DataProLicensingEnums.LicenseType` (referenced in `ValidationResult.LicenseType`); defined in an external assembly (`DTS.Common.Licensing` namespace implies a dependency on `DTS.Common.Licensing.dll`, but the enum itself is not defined in the provided sources).  
+- **Consumers**:  
+  - Licensing validation services (e.g., a `LicenseValidator` class not shown here) are expected to produce `ValidationResult` instances.  
+  - UI or middleware layers that consume validation results to make decisions (e.g., enabling/disabling features, prompting renewal).  
+- **No external library dependencies** beyond core .NET types (e.g., no third-party packages referenced in the provided files).
+
+---
+
+### 5. Gotchas  
+- **`ValidationFailures` is not initialized**: The property `ValidationFailures` is not auto-initialized to an empty collection (e.g., via `= new List<ValidationFailure>()`), so consumers must check for `null` before enumeration.  
+- **`IsValid` is not computed automatically**: Though logically defined by other properties, `IsValid` is a simple `bool` with no setter logic or computed backing; callers must ensure it is set consistently by the producer (e.g., validation service).  
+- **`IsLicensed` default may be misleading**: Its default value of `true` could cause confusion if a `ValidationResult` is constructed without explicitly setting `IsLicensed = false` when no license file exists.  
+- **`LicenseKey.KeyGuid` is a string, not a `Guid`**: Despite the name suggesting a GUID, it is stored as a `string`, which may include formatting (e.g., with/without dashes) or non-GUID values. Consumers should not assume parseability without validation.  
+- **No version comparison logic in `ValidationResult`**: While `ProductVersion` and `LicenseVersion` are present, the class itself provides no helper for comparing them (e.g., `IsLicenseVersionValid` is set externally).  
+- **Missing `LicenseKey` usage context**: The `LicenseKey` class is defined but no usage or relationship to `ValidationResult`/`ValidationFailure` is evident from these files alone (e.g., whether `LicenseKey` is used as input to validation).