marioarce · marioarce · Aug 25, 2026 · Jul 23, 2026 · Jul 23, 2026 · Aug 20, 2026
diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
@@ -27,6 +27,7 @@ on:
           - features     # PowerCSharpFeaturesVersion — Features.Abstractions, Features, BuiltInFeatures
           - cache        # PowerCSharpFeatureCacheVersion — Feature.Cache.*, Feature.Cache.BitFaster, Feature.Cache.Disk
           - sanitization # PowerCSharpFeatureSanitizationVersion — Feature.Sanitization.*, Feature.Sanitization
+          - operational  # PowerCSharpOperationalVersion — Operational.Abstractions, Operational
 
 permissions:
   contents: write
@@ -265,6 +266,10 @@ jobs:
             VERSION_ELEMENT="PowerCSharpFeatureSanitizationVersion"
             TAG_PREFIX="sanitization-v"
             ;;
+          "operational")
+            VERSION_ELEMENT="PowerCSharpOperationalVersion"
+            TAG_PREFIX="operational-v"
+            ;;
           *)
             VERSION_ELEMENT="PowerCSharpVersion"
             TAG_PREFIX="v"

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -80,6 +80,13 @@ PowerCSharp.Feature.Cache.Abstractions      cache contracts + NoOp (netstandard2
        ├─ PowerCSharp.Feature.Cache.BitFaster   BitFaster-backed LRU (isolates BitFaster.Caching)
        └─ PowerCSharp.Feature.Cache.Disk        disk-backed LRU (cross-process locking) — own CLAUDE.md
 
+--- Operational Package Family (independent versioning family) ---
+PowerCSharp.Operational.Abstractions        contracts, models, NoOp (netstandard2.0 + net8.0)
+  └─ PowerCSharp.Operational               diagnostics, issue capture, logging, event-log writer,
+                                           HTTP retry/circuit-breaker (net8.0, ASP.NET Core).
+                                           Optional PowerCSharp.Features integration via
+                                           OperationalFeatureModule; usable standalone otherwise.
+
 --- Roadmapped, confirmed in scope (see src/Features/CLAUDE.md) ---
 PowerCSharp.Feature.Sitecore                 third-party GraphQL/Sitecore integration — not started
 ```
@@ -110,6 +117,8 @@ Centrally managed in `Directory.Build.props` as independently-bumped "families":
 | `PowerCSharpCompatibilityVersion` | Compatibility | manual edit in `Directory.Build.props` |
 | `PowerCSharpFeaturesVersion` | Features.Abstractions, Features, BuiltInFeatures | `workflow_dispatch` → `package_family: features` |
 | `PowerCSharpFeatureCacheVersion` | Feature.Cache.Abstractions, Feature.Cache, Feature.Cache.BitFaster, Feature.Cache.Disk | `workflow_dispatch` → `package_family: cache` |
+| `PowerCSharpFeatureSanitizationVersion` | Feature.Sanitization.Abstractions, Feature.Sanitization | `workflow_dispatch` → `package_family: sanitization` |
+| `PowerCSharpOperationalVersion` | Operational.Abstractions, Operational | `workflow_dispatch` → `package_family: operational` |
 
 If you are adding to an existing package, bump its existing family. If you are standing up a new
 pluggable `Feature.<Name>` family (e.g. `Feature.Sitecore`), it earns its own
@@ -199,3 +208,5 @@ The .NET Framework compatibility layer is **not** covered by the commands above
   Feature package, pluggable or built-in.
 - `docs/EDGE_CASES_AND_SECURITY.md` — per-API edge-case and security notes; consult before
   changing the behavior of any existing public extension/utility method.
+- `docs/PowerCSharp.Operational.md` and `docs/PowerCSharp.Operational.Architecture.md` — Operational
+  package family API reference and architecture rationale/decision log.
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -8,13 +8,16 @@
     <PowerCSharpFeaturesVersion>1.0.3</PowerCSharpFeaturesVersion>
 
     <!-- Per-pluggable-feature versions — ship independently. -->
-    <!-- Cache family bumped to 1.3.0: realigns Cache + BitFaster onto the post-split
-         PowerCSharp.Feature.Cache.Abstractions ICacheService (stale 1.2.0 predated the split). -->
-    <PowerCSharpFeatureCacheVersion>1.3.2</PowerCSharpFeatureCacheVersion>
+
+    <PowerCSharpFeatureCacheVersion>1.3.4</PowerCSharpFeatureCacheVersion>
 
     <!-- Sanitization family: Feature.Sanitization.Abstractions + Feature.Sanitization -->
     <PowerCSharpFeatureSanitizationVersion>1.0.0</PowerCSharpFeatureSanitizationVersion>
 
+    <!-- Operational family: Operational.Abstractions + Operational (diagnostics, issue capture,
+         structured logging, disk event-log writing, HTTP retry/circuit-breaker resilience) -->
+    <PowerCSharpOperationalVersion>1.0.0</PowerCSharpOperationalVersion>
+
     <!-- Common package metadata -->
     <Authors>Mario Arce</Authors>
     <Copyright>Copyright © Mario Arce 2026</Copyright>

diff --git a/PowerCSharp.sln b/PowerCSharp.sln
@@ -59,6 +59,14 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PowerCSharp.Feature.Sanitiz
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PowerCSharp.Feature.Sanitization.Tests", "tests\PowerCSharp.Feature.Sanitization.Tests\PowerCSharp.Feature.Sanitization.Tests.csproj", "{2D2654C2-072D-47D7-BDF2-CA3A706E1271}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "PowerCSharp.Operational", "PowerCSharp.Operational", "{73CB515B-D195-472C-856B-DC6B46374EC7}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PowerCSharp.Operational.Abstractions", "src\PowerCSharp.Operational\PowerCSharp.Operational.Abstractions\PowerCSharp.Operational.Abstractions.csproj", "{92F00BFF-2F5A-40C0-BF94-A139EA410ABB}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PowerCSharp.Operational", "src\PowerCSharp.Operational\PowerCSharp.Operational\PowerCSharp.Operational.csproj", "{8175E456-92E7-4A2C-97DF-1DFFC14C5737}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PowerCSharp.Operational.Tests", "tests\PowerCSharp.Operational.Tests\PowerCSharp.Operational.Tests.csproj", "{3B5C8108-0149-4E88-9B87-AE927CF9D67C}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -160,6 +168,18 @@ Global
 		{2D2654C2-072D-47D7-BDF2-CA3A706E1271}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{2D2654C2-072D-47D7-BDF2-CA3A706E1271}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{2D2654C2-072D-47D7-BDF2-CA3A706E1271}.Release|Any CPU.Build.0 = Release|Any CPU
+		{92F00BFF-2F5A-40C0-BF94-A139EA410ABB}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{92F00BFF-2F5A-40C0-BF94-A139EA410ABB}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{92F00BFF-2F5A-40C0-BF94-A139EA410ABB}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{92F00BFF-2F5A-40C0-BF94-A139EA410ABB}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8175E456-92E7-4A2C-97DF-1DFFC14C5737}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8175E456-92E7-4A2C-97DF-1DFFC14C5737}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8175E456-92E7-4A2C-97DF-1DFFC14C5737}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8175E456-92E7-4A2C-97DF-1DFFC14C5737}.Release|Any CPU.Build.0 = Release|Any CPU
+		{3B5C8108-0149-4E88-9B87-AE927CF9D67C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{3B5C8108-0149-4E88-9B87-AE927CF9D67C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{3B5C8108-0149-4E88-9B87-AE927CF9D67C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{3B5C8108-0149-4E88-9B87-AE927CF9D67C}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{73835311-BC0A-4107-9E6D-4950DF565C46} = {493BDE4C-2EBA-49EE-BF44-10AAB73634D6}
@@ -187,5 +207,9 @@ Global
 		{F17178B0-967E-4922-BA9C-34A771E84F52} = {8396894C-0CAD-4C19-ADF6-E9E65735A3BC}
 		{2C6E4B9A-8B2C-4B1E-9C3F-6A7D8E9F0A1B} = {8396894C-0CAD-4C19-ADF6-E9E65735A3BC}
 		{2D2654C2-072D-47D7-BDF2-CA3A706E1271} = {8507D629-2649-468E-8345-212CFC547FA8}
+		{73CB515B-D195-472C-856B-DC6B46374EC7} = {006F80FE-AC82-4752-972B-081BA6C6A651}
+		{92F00BFF-2F5A-40C0-BF94-A139EA410ABB} = {73CB515B-D195-472C-856B-DC6B46374EC7}
+		{8175E456-92E7-4A2C-97DF-1DFFC14C5737} = {73CB515B-D195-472C-856B-DC6B46374EC7}
+		{3B5C8108-0149-4E88-9B87-AE927CF9D67C} = {8507D629-2649-468E-8345-212CFC547FA8}
 	EndGlobalSection
 EndGlobal
diff --git a/README.md b/README.md
@@ -25,6 +25,8 @@ Enhanced C# extension methods and utilities for .NET developers
 [![NuGet](https://img.shields.io/nuget/v/PowerCSharp.BuiltInFeatures.svg)](https://www.nuget.org/packages/PowerCSharp.BuiltInFeatures)
 [![NuGet](https://img.shields.io/nuget/v/PowerCSharp.Feature.Cache.svg)](https://www.nuget.org/packages/PowerCSharp.Feature.Cache)
 [![NuGet](https://img.shields.io/nuget/v/PowerCSharp.Feature.Sanitization.svg)](https://www.nuget.org/packages/PowerCSharp.Feature.Sanitization)
+[![NuGet](https://img.shields.io/nuget/v/PowerCSharp.Operational.Abstractions.svg)](https://www.nuget.org/packages/PowerCSharp.Operational.Abstractions)
+[![NuGet](https://img.shields.io/nuget/v/PowerCSharp.Operational.svg)](https://www.nuget.org/packages/PowerCSharp.Operational)
 
 PowerCSharp is a comprehensive library of extension methods, utilities, and helper classes designed to enhance your C# development experience. Built by a senior C# architect with 20+ years of experience, this library provides practical, well-tested solutions for common programming challenges.
 
@@ -35,6 +37,7 @@ PowerCSharp is a comprehensive library of extension methods, utilities, and help
 - **Built-in Features**: `PowerCSharp.BuiltInFeatures` bundle — runtime-flag-toggled ASP.NET Core capabilities (CORS), toggled via `PowerFeatures:<Key>:Enabled`
 - **Cache Feature Family**: `PowerCSharp.Feature.Cache` (module + options), `PowerCSharp.Feature.Cache.Abstractions` (contracts + NoOp, `netstandard2.0` + `net8.0`), `PowerCSharp.Feature.Cache.BitFaster` (BitFaster-backed LRU), `PowerCSharp.Feature.Cache.Disk` (disk-backed LRU with cross-process locking)
 - **Sanitization Feature Family**: `PowerCSharp.Feature.Sanitization.Abstractions` (engine + contracts + NoOp, `netstandard2.0` + `net8.0`) and `PowerCSharp.Feature.Sanitization` (module + options) — log injection (CWE-117), file-path traversal (CWE-22), sensitive-data masking (CWE-200), and regex-injection/ReDoS validation (CWE-400/CWE-730)
+- **Operational Package Family**: `PowerCSharp.Operational.Abstractions` (contracts + NoOp, `netstandard2.0` + `net8.0`) and `PowerCSharp.Operational` (net8.0) — cross-cutting issue capture, in-app diagnostics, structured logging, disk event-log writing, and HTTP retry/circuit-breaker resilience. Optional `PowerCSharp.Features` integration; usable standalone.
 - **EditorConfig**: Comprehensive coding standards applied across the entire codebase
 - **Directory Extensions**: `TrySafeDelete` and related safe I/O helpers
 - **Code Quality**: Nullable annotations, member ordering, and namespace cleanup throughout
@@ -70,6 +73,11 @@ PowerCSharp is organized into focused, independently versioned packages.
 - **[PowerCSharp.Feature.Sanitization.Abstractions](src/Features/PowerCSharp.Feature.Sanitization.Abstractions/README.md)** - Sanitization engine, contracts, and NoOp safe-off implementation covering log injection, file-path traversal, sensitive-data masking, and regex-injection/ReDoS. Targets `netstandard2.0` + `net8.0`.
 - **[PowerCSharp.Feature.Sanitization](src/Features/PowerCSharp.Feature.Sanitization/README.md)** - Sanitization feature module, options, and `AddSanitizationFeature()` wiring. No separate provider package — registers the real service directly.
 
+### Operational Package Family (`v1.0.0`)
+
+- **[PowerCSharp.Operational.Abstractions](src/PowerCSharp.Operational/PowerCSharp.Operational.Abstractions/README.md)** - Contracts (`IDiagnosticsService`, `IIssueManager`, `IEventViewerService`), models, enums, and NoOp safe-off implementations. Zero third-party dependencies. Targets `netstandard2.0` + `net8.0`.
+- **[PowerCSharp.Operational](src/PowerCSharp.Operational/PowerCSharp.Operational/README.md)** - In-app diagnostics, centralized issue/error capture, a custom `ILogger` provider, disk event-log writing (NDJSON), and HTTP retry/circuit-breaker resilience (via Polly). Works standalone via `AddOperational()`/`UseOperational()`, or through `PowerCSharp.Features` via the optional `OperationalFeatureModule`. Targets `net8.0` (ASP.NET Core).
+
 ### 🏗️ Architecture
 
 PowerCSharp follows a clean architectural pattern with **centralized interfaces** in PowerCSharp.Core:
@@ -117,6 +125,13 @@ dotnet add package PowerCSharp.Feature.Sanitization.Abstractions  # engine — u
 dotnet add package PowerCSharp.Feature.Sanitization               # module — Features Framework + DI wiring
 ```
 
+### Operational package family
+
+```bash
+dotnet add package PowerCSharp.Operational.Abstractions  # contracts + NoOp — usable standalone, no DI required
+dotnet add package PowerCSharp.Operational               # diagnostics, issue capture, logging, event-log writer, retry/circuit-breaker
+```
+
 ## 💡 Usage Examples
 
 ### String Extensions (PowerCSharp.Extensions)
@@ -256,6 +271,39 @@ var sanitizer = app.Services.GetRequiredService<ISanitizationService>();
 var result = sanitizer.SanitizeForLogInjection(untrustedInput);
 ```
 
+### Operational (PowerCSharp.Operational)
+
+```csharp
+// Program.cs
+builder.Services.AddOperational(builder.Configuration);
+// ...
+app.UseOperational();
+```
+
+```csharp
+using PowerCSharp.Operational.Abstractions;
+
+public class OrderController(IDiagnosticsService diagnostics, IIssueManager issues)
+{
+    public IActionResult Get(int id)
+    {
+        diagnostics.AddTrace($"Looking up order {id}");
+
+        try
+        {
+            return Ok(GetOrder(id));
+        }
+        catch (Exception ex)
+        {
+            issues.CaptureException(ex, new { orderId = id });
+            throw;
+        }
+    }
+}
+```
+
+Enable per-request diagnostics with the `debug: true` header (add `debugVerbose: true` to disable auto-obfuscation, `traceLevel: <0-6>` to filter, `eventLog: true` to also write to disk). Disabled or unconfigured, `PowerCSharp.Operational.Abstractions` NoOp floors keep every call site safe.
+
 ### LINQ & Dynamic Query Extensions (PowerCSharp.Extensions)
 
 ```csharp
@@ -415,10 +463,10 @@ string random = CryptoHelper.GenerateRandomString(10);
 
 ## 🎯 Target Frameworks
 
-- **Modern .NET**: .NET 8.0 — core libraries, Features engine, BuiltInFeatures, Cache and Sanitization feature modules
-- **.NET Standard 2.0 + .NET 8.0**: `PowerCSharp.Features.Abstractions`, `PowerCSharp.Feature.Cache.Abstractions`, `PowerCSharp.Feature.Cache.BitFaster`, `PowerCSharp.Feature.Sanitization.Abstractions` — usable from .NET Framework and .NET Core
+- **Modern .NET**: .NET 8.0 — core libraries, Features engine, BuiltInFeatures, Cache, Sanitization, and Operational feature modules
+- **.NET Standard 2.0 + .NET 8.0**: `PowerCSharp.Features.Abstractions`, `PowerCSharp.Feature.Cache.Abstractions`, `PowerCSharp.Feature.Cache.BitFaster`, `PowerCSharp.Feature.Sanitization.Abstractions`, `PowerCSharp.Operational.Abstractions` — usable from .NET Framework and .NET Core
 - **.NET Framework**: 4.6.2, 4.7.2, 4.8 — via `PowerCSharp.Compatibility`
-- **ASP.NET Core**: .NET 8.0 — `PowerCSharp.Extensions.AspNetCore`, Features engine, BuiltInFeatures
+- **ASP.NET Core**: .NET 8.0 — `PowerCSharp.Extensions.AspNetCore`, Features engine, BuiltInFeatures, `PowerCSharp.Operational`
 
 ## 🧪 Testing
 
@@ -455,6 +503,10 @@ dotnet test
 - **[PowerCSharp.Feature.Sanitization.Abstractions](src/Features/PowerCSharp.Feature.Sanitization.Abstractions/README.md)** - Engine and contracts reference
 - **[PowerCSharp.Feature.Sanitization](src/Features/PowerCSharp.Feature.Sanitization/README.md)** - Module guide
 
+**Operational package family**
+- **[PowerCSharp.Operational.Abstractions](src/PowerCSharp.Operational/PowerCSharp.Operational.Abstractions/README.md)** - Contracts, models, and NoOp reference
+- **[PowerCSharp.Operational](src/PowerCSharp.Operational/PowerCSharp.Operational/README.md)** - Diagnostics, issue capture, logging, event-log writer, and retry/circuit-breaker guide
+
 ### Detailed API Documentation
 - **[PowerCSharp.Core API](docs/PowerCSharp.Core.md)** - Complete core API reference
 - **[PowerCSharp.Extensions API](docs/PowerCSharp.Extensions.md)** - Cross-platform extensions documentation
@@ -468,6 +520,8 @@ dotnet test
 - **[Features Flag Reference](docs/PowerCSharp.Features.FlagReference.md)** - Flag schema and provider precedence
 - **[Cache Feature API](docs/PowerCSharp.Feature.Cache.md)** - Cache family API reference
 - **[Sanitization Feature API](docs/PowerCSharp.Feature.Sanitization.md)** - Sanitization family API reference
+- **[Operational Package API](docs/PowerCSharp.Operational.md)** - Operational family API reference
+- **[Operational Architecture](docs/PowerCSharp.Operational.Architecture.md)** - Operational design rationale and decision log
 
 ### Development Documentation
 - [Examples and Samples](samples/) - Working code examples