init

enriched-qwen3-coder-next/DataPRO/DbAPI/Errors.md

@@ -0,0 +1,57 @@
+---
+source_files:
+  - DataPRO/DbAPI/Errors/ErrorCodes.cs
+generated_at: "2026-04-16T04:26:28.421504+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "0b2f1f90c61e6679"
+---
+
+# Errors
+
+## 1. Purpose  
+This module defines a centralized set of error codes and a string conversion utility for the `DbAPI` layer of the proprietary codebase. It serves as a canonical source of error constants (e.g., `ERROR_ACCESS_DENIED`, `INVALID_SESSIONID`) used throughout database-related operations, enabling consistent error reporting and handling. The `ResultToString` method maps numeric error codes to human-readable string representations, facilitating debugging and logging.
+
+## 2. Public Interface  
+- **`public const ulong ERROR_SUCCESS = 0x0`**  
+  Indicates successful operation.  
+- **`public const ulong ERROR_INVALID_FUNCTION = 0x1`**  
+  Generic error for an invalid or unsupported function call.  
+- **`public const ulong ERROR_FILE_NOT_FOUND = 0x2`**  
+  Indicates a requested file could not be located.  
+- **`public const ulong ERROR_PATH_NOT_FOUND = 0x3`**  
+  Indicates a requested path (directory) could not be located.  
+- **`public const ulong ERROR_ACCESS_DENIED = 0x5`**  
+  Indicates insufficient permissions to perform the requested operation.  
+- **`public const ulong ERROR_NOT_SUPPORTED = 0x32`**  
+  Indicates the requested operation is not supported.  
+- **`public const ulong INVALID_SESSIONID = 0x200`**  
+  Indicates an invalid or expired session identifier was provided.  
+- **`public const ulong ERROR_UNKNOWN = 0x201`**  
+  Fallback error code for unrecognized or unclassified errors.  
+- **`public const ulong ERROR_NOUSER = 0x202`**  
+  Indicates no user context is available (e.g., unauthenticated or deleted user).  
+- **`public const ulong ERROR_LOGINFAILED = 0x203`**  
+  Indicates authentication failure (e.g., invalid credentials).  
+- **`public const ulong ERROR_MISSING_PARAMETER = 0x204`**  
+  Indicates a required parameter was omitted in a function call.  
+- **`public static string ResultToString(ulong hr)`**  
+  Converts a numeric error code (`hr`) to a descriptive string (e.g., `"ACCESS_DENIED"`). For unrecognized codes, returns the hex representation (e.g., `"205"` for `0x205`).  
+
+## 3. Invariants  
+- All error codes are `const ulong` and assigned explicit hexadecimal values.  
+- `ResultToString` is deterministic: the same input `hr` always produces the same output string.  
+- The `switch` statement in `ResultToString` is exhaustive for all defined constants; any value not explicitly handled falls back to hex formatting.  
+- No mutable state exists in this class (it is `abstract` and contains only constants and a static method).  
+
+## 4. Dependencies  
+- **Internal dependencies**: None (no external references in the provided source).  
+- **Consumers**: This module is expected to be referenced by other components in the `DbAPI` layer (e.g., database connection, query execution, or session management modules) to standardize error reporting.  
+- **No external libraries or frameworks** are imported or referenced in this file.  
+
+## 5. Gotchas  
+- The `abstract` modifier on `ErrorCodes` is unusual for a pure constants class (typically `static class` is used in C# for this pattern); this may imply intentional extensibility (e.g., subclassing for environment-specific codes), but no subclasses are present in the provided source.  
+- The `default` case in `ResultToString` returns `hr.ToString("X")`, which omits the `0x` prefix (e.g., `"205"` instead of `"0x205"`), potentially reducing clarity in logs.  
+- The constant `ERROR_LOGINFAILED` uses a string literal `"LOGIN_FAILED"` instead of `@"LOGIN_FAILED"` (consistent verbatim string usage elsewhere suggests this may be unintentional).  
+- No error codes between `0x205` and `0x201` (e.g., `0x205`–`0x201` is invalid range; likely meant `0x205`–`0x209`) are defined, suggesting possible gaps or future expansion points.  
+- None identified from source alone.