init

enriched-qwen3-coder-next/Common/DTS.Common.CPU/Classes.md

@@ -0,0 +1,97 @@
+---
+source_files:
+  - Common/DTS.Common.CPU/Classes/BREngine.cs
+  - Common/DTS.Common.CPU/Classes/CPUEngine.cs
+generated_at: "2026-04-16T03:28:53.637809+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "66174fba615f1ce2"
+---
+
+# Classes
+
+## Documentation: `CPUEngine` Module
+
+---
+
+### 1. **Purpose**
+
+The `CPUEngine` class serves as a core infrastructure component responsible for managing cross-cutting concerns in the CPU-related domain of the DTS system—specifically, event-driven UI notifications and status updates via Prism’s interaction patterns and event aggregation. It acts as a bridge between internal system events (e.g., status changes, notifications) and UI-level interaction requests, enabling decoupled communication between backend logic and the presentation layer. It does *not* implement CPU-specific computation logic (as suggested by the empty `BREngine` class), but rather provides a reusable base for UI interaction coordination within the CPU domain.
+
+---
+
+### 2. **Public Interface**
+
+#### `CPUEngine()`  
+- **Signature**: `public CPUEngine()`  
+- **Behavior**: Constructor. Initializes Prism dependencies (`IUnityContainer`, `IEventAggregator`, `IServiceLocator`) via the current `ServiceLocator`. Registers handlers for `RaiseNotification` and `ShowStatus` events. Instantiates `NotificationRequest` and `ConfirmationRequest` interaction requests.
+
+#### `NotificationRequest`  
+- **Signature**: `public InteractionRequest<Notification> NotificationRequest { get; private set; }`  
+- **Behavior**: Exposes a Prism `InteractionRequest` for displaying notifications (e.g., informational popups). Triggered internally via `OnRaiseNotification` when a `RaiseNotification` event is published.
+
+#### `ConfirmationRequest`  
+- **Signature**: `public new InteractionRequest<Confirmation> ConfirmationRequest { get; private set; }`  
+- **Behavior**: Exposes a Prism `InteractionRequest` for confirmation dialogs (e.g., yes/no prompts). *Currently unused*—no code raises this request.
+
+#### `OnPropertyChanged(string propertyName)`  
+- **Signature**: `public void OnPropertyChanged(string propertyName)`  
+- **Behavior**: Raises the `PropertyChanged` event for data binding (implements `INotifyPropertyChanged` via `ICPUEngine`). Used to notify UI of property changes.
+
+#### `PropertyChanged`  
+- **Signature**: `public new event PropertyChangedEventHandler PropertyChanged;`  
+- **Behavior**: Standard .NET event for property change notifications. Overridden from base interface `ICPUEngine`.
+
+---
+
+### 3. **Invariants**
+
+- **Event Subscription Consistency**: Upon construction, `_eventAggregator` *must* successfully resolve `IEventAggregator` and subscribe to `RaiseNotification` and `ShowStatus` events. Failure to do so would break notification/status handling.
+- **Service Locator Dependency**: The class *requires* that `ServiceLocator.Current` is set and returns a valid `IServiceLocator` containing registered implementations for `IUnityContainer`, `IServiceLocator`, and `IEventAggregator`. If not, constructor throws.
+- **Notification Payload Transformation**: When handling `RaiseNotification`, the internal `NotificationContentEventArgs` is *always* transformed into a `NotificationContentEventArgs` (note: same name, likely a typo—see *Gotchas*) with `Title` extracted separately. The `Content` of the `Notification` object is *always* a `NotificationContentEventArgs` (without title), and `Title` is taken from the event args.
+- **No-op Status Handler**: `OnStatusChange` is currently commented out—no status update logic is active. Thus, `IsBusy`, `IsBusyMessage`, and related properties (if any) are *not* updated.
+
+---
+
+### 4. **Dependencies**
+
+#### **External Dependencies (Imports/Usings)**  
+- **Prism Libraries**:  
+  - `Microsoft.Practices.Prism.Events` (`IEventAggregator`, `RaiseNotification`, `ShowStatus`)  
+  - `Microsoft.Practices.Prism.Interactivity.InteractionRequest` (`InteractionRequest<T>`, `Notification`, `Confirmation`)  
+  - `Microsoft.Practices.Prism.Regions` (`IRegionManager`)  
+  - `Microsoft.Practices.Unity` (`IUnityContainer`)  
+  - `Microsoft.Practices.ServiceLocation` (`IServiceLocator`)  
+- **DTS Internal Libraries**:  
+  - `DTS.Common.Events` (`RaiseNotification`, `ShowStatus`, `StatusInfo`, `NotificationContentEventArgs`)  
+  - `DTS.Common.Interface` (`ICPUEngine`)  
+  - `DTS.Common.Base` (likely contains base types like `NotificationContentEventArgs`)
+
+#### **Internal Dependencies**  
+- **Consumers**: Any module needing to trigger notifications or status updates can publish `RaiseNotification` or `ShowStatus` events via `_eventAggregator`.  
+- **Consumed By**: UI layers (e.g., views/view models) that bind to `NotificationRequest`/`ConfirmationRequest` for modal dialogs.
+
+#### **Required Services in Container**  
+- `IUnityContainer`  
+- `IServiceLocator`  
+- `IEventAggregator`  
+- `IRegionManager` (declared but unused in current implementation)
+
+---
+
+### 5. **Gotchas**
+
+- **`new` Keyword on `IRegionManager`**: `_regionManager` is declared as `private new IRegionManager _regionManager;` but is *never assigned or used*. This suggests incomplete refactoring or legacy code.  
+- **`NotificationContentEventArgs` Ambiguity**:  
+  - In `OnRaiseNotification`, a new `NotificationContentEventArgs` is constructed from `eventArgsWithTitle.Message`, `MessageDetails`, and `Image`.  
+  - However, the source does not define whether `NotificationContentEventArgs` has a constructor accepting these parameters—nor is there a `NotificationContentEventArgsWithoutTitle` type (mentioned in the comment) referenced elsewhere. This implies either:  
+    - A missing type definition,  
+    - Or a naming collision (same class name used for two purposes),  
+    - Or a typo (e.g., `NotificationContentEventArgsWithoutTitle` should be `NotificationContentEventArgs`).  
+  - **Critical risk**: If `NotificationContentEventArgs` lacks the expected constructor, runtime exceptions occur.  
+- **`ShowStatus` Handler is Dead Code**: `OnStatusChange` is fully commented out. If status tracking is expected, this is a functional gap.  
+- **No `ConfirmationRequest` Usage**: `ConfirmationRequest` is instantiated but never raised—either unused or intended for future implementation.  
+- **`ICPUEngine` Contract Unknown**: Since `ICPUEngine` is not provided, we cannot verify if `OnPropertyChanged` and `PropertyChanged` are correctly implemented per interface expectations (e.g., `new` keyword usage may conflict with interface implementation).  
+- **No Null Checks**: `ServiceLocator.Current` and `_unityContainer.Resolve<T>()` calls lack null/error handling—could throw if services are missing.  
+
+> **Note**: No CPU-specific logic (e.g., instruction execution, register management) is present. The class name `CPUEngine` is likely a domain label, not a functional description.

enriched-qwen3-coder-next/Common/DTS.Common.CPU/Properties.md

@@ -0,0 +1,115 @@
+---
+source_files:
+  - Common/DTS.Common.CPU/Properties/AssemblyInfo.cs
+  - Common/DTS.Common.CPU/Properties/Annotations.cs
+generated_at: "2026-04-16T03:29:08.777780+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "2ecad58ebc9f0db4"
+---
+
+# Properties
+
+## Documentation: `DTS.Common.CPU.Annotations` Namespace
+
+### 1. Purpose  
+This module provides a comprehensive set of JetBrains-style code annotation attributes for use in static analysis (e.g., by ReSharper or Rider) to improve nullability, contract, and usage intent expressiveness in C# code. It does not contain executable logic or business functionality; rather, it serves as a *metadata layer* to guide compiler/tooling behavior and human understanding of API contracts. The attributes are applied via attributes on types, methods, parameters, and properties to convey semantic constraints (e.g., nullability, immutability, usage patterns) that static analyzers interpret to generate warnings or suggestions.
+
+### 2. Public Interface  
+All types reside in the `DTS.Common.CPU.Annotations` namespace. All attributes are `sealed` and inherit from `Attribute`. Below are the key public types:
+
+#### Core Nullability Annotations  
+- **`CanBeNullAttribute`**  
+  Indicates the marked element *may* be `null`. Applies to methods, parameters, properties, fields, events, delegates, classes, interfaces, and generic parameters.  
+- **`NotNullAttribute`**  
+  Indicates the marked element *must never* be `null`. Applies to the same targets as `CanBeNullAttribute`.  
+- **`ItemCanBeNullAttribute`**  
+  For `IEnumerable<T>`, `Task<T>`, or `Lazy<T>`: indicates the *item/result/value* may be `null`.  
+- **`ItemNotNullAttribute`**  
+  For `IEnumerable<T>`, `Task<T>`, or `Lazy<T>`: indicates the *item/result/value* is guaranteed non-null.  
+- **`ImplicitNotNullAttribute`**  
+  Applies to types or assemblies: implicitly enforces `[NotNull]`/`[ItemNotNull]` on all members within scope.
+
+#### Contract & Behavior Annotations  
+- **`StringFormatMethodAttribute(string formatParameterName)`**  
+  Marks a method as building a string from a format string (like `string.Format`). `formatParameterName` specifies which parameter holds the format string.  
+- **`ValueProviderAttribute(string name)`**  
+  Indicates a parameter/property/field must be one of a limited set of values, defined by fields of the type specified by `name`.  
+- **`InvokerParameterNameAttribute`**  
+  For parameters expected to be string literals matching a caller’s parameter name (e.g., `ArgumentNullException` parameter).  
+- **`NotifyPropertyChangedInvocatorAttribute(string parameterName = null)`**  
+  Marks methods used to notify property changes (e.g., `INotifyPropertyChanged`). Supports `NotifyChanged(string)`, `NotifyChanged(params string[])`, expression-based overloads, and `SetProperty` patterns.  
+- **`ContractAnnotationAttribute(string contract, bool forceFullStates = false)`**  
+  Declares input-output dependencies (e.g., `"s:null => true"`, `"null => null; notnull => notnull"`). Supports multiple instances per method.  
+- **`MustUseReturnValueAttribute(string justification = null)`**  
+  Indicates the return value of a method *must* be used.  
+- **`PureAttribute`**  
+  Indicates the method has no observable side effects (like `System.Diagnostics.Contracts.PureAttribute`).  
+- **`InstantHandleAttribute`**  
+  For delegate/`IEnumerable` parameters: indicates the parameter is used *immediately* within the method (e.g., executed or enumerated synchronously).  
+- **`ProvidesContextAttribute`**  
+  Marks a member as the canonical source for a context value (e.g., a service instance).  
+- **`CollectionAccessAttribute(CollectionAccessType type)`**  
+  Describes how a method/constructor/property affects a collection’s content. `CollectionAccessType` values:  
+  - `None` (0)  
+  - `Read` (1)  
+  - `ModifyExistingContent` (2)  
+  - `UpdatedContent` (7 = `ModifyExistingContent | 4`)  
+- **`AssertionMethodAttribute`** + **`AssertionConditionAttribute(AssertionConditionType)`**  
+  Marks assertion methods (e.g., `Guard.NotNull`). `AssertionConditionType` values: `IS_TRUE`, `IS_FALSE`, `IS_NULL`, `IS_NOT_NULL`.  
+- **`LinqTunnelAttribute`**  
+  Marks pure LINQ methods to enable `InstantHandle` inference for delegate parameters in chains.  
+- **`NoEnumerationAttribute`**  
+  Indicates an `IEnumerable` parameter is *not* enumerated.  
+- **`LocalizationRequiredAttribute(bool required = true)`**  
+  Marks elements requiring localization.  
+- **`CannotApplyEqualityOperatorAttribute`**  
+  Indicates `==`/`!=` operators are invalid for the type (except `null` comparisons).  
+- **`UsedImplicitlyAttribute(ImplicitUseKindFlags, ImplicitUseTargetFlags)`** + **`MeansImplicitUseAttribute(...)`**  
+  Marks symbols used implicitly (e.g., via reflection) to suppress unused warnings. `ImplicitUseKindFlags`: `Access`, `Assign`, `InstantiatedWithFixedConstructorSignature`, `InstantiatedNoFixedConstructorSignature`. `ImplicitUseTargetFlags`: `Itself`, `Members`, `WithMembers`.  
+- **`PublicAPIAttribute(string comment = null)`**  
+  Marks publicly exposed API that must not be removed. Internally uses `[MeansImplicitUse(ImplicitUseTargetFlags.WithMembers)]`.  
+- **`SourceTemplateAttribute`** + **`MacroAttribute`**  
+  Marks extension methods as source templates for IDE expansion (e.g., `forEach` snippets).  
+- **`PathReferenceAttribute(string basePath = null)`**  
+  Indicates a parameter is a file/folder path in a web project.  
+
+#### ASP.NET MVC & Razor-Specific Annotations  
+- **`AspMvc*Attribute`** (e.g., `AspMvcActionAttribute`, `AspMvcAreaAttribute`, `AspMvcControllerAttribute`, `AspMvcViewAttribute`, `AspMvcSuppressViewErrorAttribute`, etc.)  
+  Marks parameters/methods for MVC/Razor view resolution (e.g., action names, areas, controllers, views). Many have optional `anonymousProperty` constructor.  
+- **`AspChildControlTypeAttribute(string tagName, Type controlType)`**  
+  Specifies child control types for ASP.NET server controls.  
+- **`AspDataFieldAttribute`**, **`AspDataFieldsAttribute`**, **`AspMethodPropertyAttribute`**, **`AspRequiredAttributeAttribute(string attribute)`**, **`AspTypePropertyAttribute(bool createConstructorReferences)`**  
+  ASP.NET-specific metadata for data binding and property resolution.  
+- **`Razor*Attribute`** (e.g., `RazorSectionAttribute`, `RazorImportNamespaceAttribute`, `RazorInjectionAttribute`, `RazorDirectiveAttribute`, `RazorWriteLiteralMethodAttribute`, `RazorWriteMethodAttribute`, `RazorHelperCommonAttribute`, `RazorLayoutAttribute`)  
+  Razor view engine metadata for section resolution, imports, and helper methods.  
+- **`XamlItemsControlAttribute`** + **`XamlItemBindingOfItemsControlAttribute`**  
+  XAML binding context resolution for `ItemsControl`-derived types.  
+
+#### Utility  
+- **`NoReorder`**  
+  Prevents IDE member reordering for the marked class.  
+
+### 3. Invariants  
+- **No runtime behavior**: All attributes are metadata-only. They have no effect at runtime unless consumed by tooling (e.g., ReSharper, analyzers).  
+- **Attribute targets**: Each attribute’s `AttributeUsage` is strictly defined (e.g., `CanBeNullAttribute` targets methods, parameters, properties, etc.). Applying to an unsupported target is a compile-time error.  
+- **Nullability semantics**: `[NotNull]` and `[CanBeNull]` are mutually exclusive for the same element. Tooling expects consistency; mixing them may cause conflicting warnings.  
+- **ContractAnnotation syntax**: The `contract` string must follow the specified FDT (Function Definition Table) syntax. Invalid syntax may cause analyzer errors or ignored annotations.  
+- **`StringFormatMethodAttribute`**: The `formatParameterName` must match an actual parameter name; otherwise, tooling may produce false warnings.  
+- **`AssertionConditionAttribute`**: Only valid on parameters of methods marked with `[AssertionMethod]`.  
+
+### 4. Dependencies  
+- **No external dependencies**: This module is self-contained. It uses only `System` and `System.Runtime.CompilerServices` (via attributes like `AttributeUsage`).  
+- **Consumers**: Any project referencing `DTS.Common.CPU` can use these annotations. They are intended for use in *other* modules within the `DTS.Common.*` family (e.g., `DTS.Common.CPU` itself likely consumes them, though not visible in the provided files).  
+- **Tooling dependency**: Full benefit requires ReSharper/Rider or compatible analyzers (e.g., JetBrains.Annotations NuGet package). Without tooling, attributes are inert.  
+
+### 5. Gotchas  
+- **`AssemblyInfo.cs` is metadata-only**: The assembly version (`1.0.0.0`) and GUID (`a68ef337-debf-4265-8dec-8acf01e76ee6`) are fixed and should not be changed without coordination.  
+- **`Annotations.cs` is a copy of JetBrains.Annotations**: This is a vendored copy of JetBrains’ annotation definitions (MIT-licensed). Do *not* modify it unless aligning with upstream changes.  
+- **`[Obsolete]` on `TerminatesProgramAttribute`**: The `TerminatesProgramAttribute` is deprecated in favor of `[ContractAnnotation("=> halt")]`. Using it will trigger an obsolete warning.  
+- **`AspMvc*` attributes are framework-specific**: These only make sense in ASP.NET MVC/Razor contexts. Using them in non-MVC projects may confuse tooling without benefit.  
+- **`SourceTemplate`/`Macro` require IDE support**: These attributes only function in IDEs that support template expansion (e.g., ReSharper). They are ignored in standard compilation.  
+- **`ImplicitUse*` flags are subtle**: Misusing `ImplicitUseKindFlags` (e.g., omitting `InstantiatedNoFixedConstructorSignature` when constructors are used reflectively) may cause false "unused constructor" warnings.  
+- **No runtime validation**: Attributes like `[NotNull]` do *not* enforce null checks at runtime. Developers must still write defensive code.  
+
+None identified beyond what is apparent from the source.