init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Exceptions.md

@@ -0,0 +1,37 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Exceptions/OutOfDataException.cs
+generated_at: "2026-04-16T02:13:54.656604+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "fdc72f1eddeb3763"
+---
+
+# Exceptions
+
+### 1. Purpose  
+The `OutOfDataException` class provides a specialized exception type for scenarios where an operation attempting to read or consume data from a sequential data source (e.g., a stream, buffer, or parser) has exceeded the available data. It extends `System.Exception` to include contextual information—the `Index` at which the shortage occurred—enabling callers to pinpoint the location of the failure and implement recovery or error-reporting logic accordingly.
+
+### 2. Public Interface  
+- **`OutOfDataException(string message, long index)`**  
+  Constructor. Initializes a new instance of the `OutOfDataException` class with a specified error message and the zero-based index in the data source where the shortage occurred. The `index` parameter is stored in the `Index` property and is immutable after construction.
+
+- **`long Index { get; }`**  
+  Read-only property exposing the zero-based index (e.g., byte offset, element position, or token index) in the underlying data source where the exception was thrown. This value is set at construction and cannot be modified.
+
+### 3. Invariants  
+- `Index` is non-negative and represents a position *beyond* the last valid data element (i.e., `Index >= DataLength`).  
+- `Index` is set exactly once during construction and remains constant for the lifetime of the exception instance.  
+- The exception message (`Message` inherited from `Exception`) must clearly describe the nature of the data shortage (e.g., “Unexpected end of input at index 42”).
+
+### 4. Dependencies  
+- **Depends on**: `System.Exception` (via `System` namespace).  
+- **Used by**: Likely consumed by data-parsing, deserialization, or streaming components within the `DTS.Common` namespace (e.g., `DTS.Common.Core`, `DTS.Common.IO`)—though no direct usages are visible in this file, the exception’s design implies integration with data-reading logic.  
+- **No external dependencies** beyond the base .NET runtime.
+
+### 5. Gotchas  
+- The `Index` property uses a zero-based convention, but callers must verify whether the underlying data source uses byte offsets, character positions, or element indices (e.g., in a token stream) to avoid misinterpretation.  
+- The exception does *not* include the total data length; callers must track capacity separately if needed for context.  
+- The `Index` is `long`, suggesting support for large data sources (e.g., >2GB), but callers should ensure consistency with the data source’s indexing scheme (e.g., `int`-based APIs may require casting).  
+- No additional context (e.g., source name, buffer snapshot) is stored—only the index and message—limiting diagnostic depth without external correlation.  
+- None identified from source alone.