init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Events/ISO.md

@@ -0,0 +1,60 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Events/ISO/ExtraPropertiesChangedEvent.cs
+generated_at: "2026-04-16T02:48:09.465052+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "e516fa28d2ce4f6a"
+---
+
+# ISO
+
+### 1. **Purpose**  
+This module defines event infrastructure for propagating changes to a collection of extra properties within the ISO domain layer. Specifically, it provides a Prism-based event (`ExtraPropertiesChangedEvent`) and its argument container (`ExtraPropertiesChangedEventArgs`) to decouple producers of property updates (e.g., data sources, UI components, or business logic modules) from consumers (e.g., view models or services) in a loosely coupled, publish-subscribe pattern. It enables reactive updates to extended metadata associated with ISO-compliant entities, beyond standard properties.
+
+---
+
+### 2. **Public Interface**  
+
+#### `ExtraPropertiesChangedEvent`
+- **Signature**: `public class ExtraPropertiesChangedEvent : CompositePresentationEvent<ExtraPropertiesChangedEventArgs>`
+- **Behavior**: A Prism `CompositePresentationEvent` typed to `ExtraPropertiesChangedEventArgs`. Used to publish and subscribe to notifications when the set of extra properties has changed. Subscribers receive the updated list of properties, along with context about the producer and consumer involved.
+
+#### `ExtraPropertiesChangedEventArgs`
+- **Signature**: `public class ExtraPropertiesChangedEventArgs`
+- **Properties**:
+  - `IList<IExtraProperty> ExtraProperties { get; }`  
+    The new or updated list of extra properties. *Not null* (per constructor requirement), though the list itself may be empty.
+  - `object Producer { get; }`  
+    The object instance that initiated or caused the change (e.g., a data adapter, service, or UI element).
+  - `object Consumer { get; }`  
+    The object instance that is the target or recipient of the change (e.g., a view model or state manager).
+- **Constructor**:  
+  `ExtraPropertiesChangedEventArgs(IList<IExtraProperty> extraProperties, object producer, object consumer)`  
+  Initializes a new instance with the specified property list, producer, and consumer. All parameters are required and stored immutably.
+
+---
+
+### 3. **Invariants**  
+- `ExtraProperties` is never `null`; the constructor enforces this by accepting `IList<IExtraProperty>` directly (though the caller must ensure non-null input).
+- `Producer` and `Consumer` may be `null` (no validation is applied in the constructor), but are semantically expected to be non-null in practice (contextual usage).
+- The event is *publish-only* on change; it does not support partial updates or delta semantics—subscribers receive the *entire* current list of extra properties.
+- The `IList<IExtraProperty>` reference is stored directly (no defensive copy), so callers must avoid mutating the list after construction if immutability is desired.
+
+---
+
+### 4. **Dependencies**  
+- **Depends on**:
+  - `Microsoft.Practices.Prism.Events` (for `CompositePresentationEvent<T>` base class).
+  - `DTS.Common.Interface.ISO.ExtraProperties` (for `IExtraProperty` interface).
+- **Depended on by**:
+  - Any module or layer that needs to publish or subscribe to extra property changes (e.g., ISO data adapters, UI components using Prism event aggregation).
+  - Not directly consumed by other *modules* in this file, but its usage is implied by the namespace (`DTS.Common.Events.ISO`) and naming conventions.
+
+---
+
+### 5. **Gotchas**  
+- **No immutability guarantee**: The `ExtraProperties` list is not defensively copied; external mutation of the passed list after construction will affect the event args. Callers should pass an immutable or defensive copy if needed.
+- **`Producer`/`Consumer` semantics are application-defined**: The interface does not enforce or document what constitutes a valid `producer` or `consumer`. Misuse (e.g., passing `null` or unrelated objects) may lead to ambiguous event tracing.
+- **No versioning or change metadata**: The event carries only the *current* state of properties, not what changed (e.g., additions/removals). Consumers must diff against prior state if granular change tracking is required.
+- **No validation on `IExtraProperty` contents**: The list may contain duplicate, invalid, or inconsistent `IExtraProperty` instances—validation (if any) occurs elsewhere.