Spec 014: Caching decorator — requirements, ADR 0021, and task breakdown (#291)

.agent_instructions/testing.md

@@ -4,6 +4,7 @@
 - Write developer tests using xUnit.
 - Name test methods in the format: When_[condition]_should_[expected_behavior].
 - Name test classes `[Behavior]Tests` — the `When_` convention is for method names and file names only, never class names. For example `QueryProcessorExecuteTests`, `PipelineBuilderDecoratorTests`.
+- Name the class-under-test variable after the class, not `_sut` — for example `defaultCacheKeyGenerator` for `DefaultCacheKeyGenerator`.
 - Prefer a test case per file.
 - Name test files for the test method in the file i.e. When_[condition]_should_[expected_behavior].cs
 - If you decide to use multiple test cases per file, for example shared complex set up, name the file after the happy path test method and the class after the shared behavior.

Darker.Filter.slnf

@@ -10,14 +10,16 @@
       "src\\Paramore.Darker.Validation\\Paramore.Darker.Validation.csproj",
       "src\\Paramore.Darker.Validation.FluentValidation\\Paramore.Darker.Validation.FluentValidation.csproj",
       "src\\Paramore.Darker.Validation.DataAnnotations\\Paramore.Darker.Validation.DataAnnotations.csproj",
+      "src\\Paramore.Darker.Caching\\Paramore.Darker.Caching.csproj",
       "test\\Paramore.Darker.Benchmarks\\Paramore.Darker.Benchmarks.csproj",
       "test\\Paramore.Darker.Tests.AOT\\Paramore.Darker.Tests.AOT.csproj",
       "test\\Paramore.Darker.Core.Tests\\Paramore.Darker.Core.Tests.csproj",
       "test\\Paramore.Darker.Extensions.Tests\\Paramore.Darker.Extensions.Tests.csproj",
       "test\\Paramore.Darker.Extensions.Diagnostics.Tests\\Paramore.Darker.Extensions.Diagnostics.Tests.csproj",
       "test\\Paramore.Darker.Validation.Tests\\Paramore.Darker.Validation.Tests.csproj",
       "test\\Paramore.Darker.Validation.FluentValidation.Tests\\Paramore.Darker.Validation.FluentValidation.Tests.csproj",
-      "test\\Paramore.Darker.Validation.DataAnnotations.Tests\\Paramore.Darker.Validation.DataAnnotations.Tests.csproj"
+      "test\\Paramore.Darker.Validation.DataAnnotations.Tests\\Paramore.Darker.Validation.DataAnnotations.Tests.csproj",
+      "test\\Paramore.Darker.Caching.Tests\\Paramore.Darker.Caching.Tests.csproj"
     ]
   }
 }

Darker.slnx

@@ -70,6 +70,12 @@
       <Configuration Solution="Release|x64" Project="Release|Any CPU" />
       <Configuration Solution="Release|x86" Project="Release|Any CPU" />
     </Project>
+    <Project Path="src\Paramore.Darker.Caching\Paramore.Darker.Caching.csproj">
+      <Configuration Solution="Debug|x64" Project="Debug|Any CPU" />
+      <Configuration Solution="Debug|x86" Project="Debug|Any CPU" />
+      <Configuration Solution="Release|x64" Project="Release|Any CPU" />
+      <Configuration Solution="Release|x86" Project="Release|Any CPU" />
+    </Project>
   </Folder>
   <Folder Name="/test/">
     <Project Path="test\Paramore.Darker.Benchmarks\Paramore.Darker.Benchmarks.csproj">
@@ -120,5 +126,11 @@
       <Configuration Solution="Release|x64" Project="Release|Any CPU" />
       <Configuration Solution="Release|x86" Project="Release|Any CPU" />
     </Project>
+    <Project Path="test\Paramore.Darker.Caching.Tests\Paramore.Darker.Caching.Tests.csproj">
+      <Configuration Solution="Debug|x64" Project="Debug|Any CPU" />
+      <Configuration Solution="Debug|x86" Project="Debug|Any CPU" />
+      <Configuration Solution="Release|x64" Project="Release|Any CPU" />
+      <Configuration Solution="Release|x86" Project="Release|Any CPU" />
+    </Project>
   </Folder>
 </Solution>

Directory.Packages.props

@@ -8,6 +8,9 @@
     <PackageVersion Include="FluentValidation" Version="11.11.0" />
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.9" />
     <PackageVersion Include="Microsoft.CSharp" Version="4.7.0" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.Hybrid" Version="9.10.0" />
+    <!-- TEST-ONLY: FusionCache as a drop-in HybridCache implementation (no production source dependency) -->
+    <PackageVersion Include="ZiggyCreatures.FusionCache" Version="2.6.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.9" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.9" />

specs/.current-spec

@@ -1 +1 @@
-013-validation-decorator
+014-Caching-Decorator

specs/014-Caching-Decorator/.adr-list

@@ -0,0 +1 @@
+0021-caching-decorator-architecture.md

specs/014-Caching-Decorator/.issue-number

@@ -0,0 +1 @@
+291

specs/014-Caching-Decorator/README.md

@@ -0,0 +1,29 @@
+# Caching Decorator
+
+**Spec ID:** 014
+**Created:** 2026-07-20
+**Status:** Requirements
+
+## Overview
+
+An opt-in `[CacheableQuery]` decorator that caches query results through the Darker pipeline, built on Microsoft's `HybridCache` abstraction (FusionCache pluggable via DI). Supports sync + async pathways (sync uses an immediate-completion fast return), pluggable cache keys (`IAmCacheable` with a serialization fallback), TTL expiry plus externally-driven tag eviction via a well-known `IQueryContext.Bag` key, and configurable OpenTelemetry hit/miss signals. See `requirements.md` (linked issue [#291](https://github.com/BrighterCommand/Darker/issues/291)).
+
+## Status Checklist
+
+- [ ] **Requirements** — Define WHAT the feature must do (`/spec:requirements`)
+- [ ] **Design (ADR)** — Define HOW the feature will be built (`/spec:design`)
+- [ ] **Adversarial Review** — Multiple rounds of critical review (`/spec:review`)
+- [ ] **Tasks** — Break the design into implementation tasks (`/spec:tasks`)
+- [ ] **Implementation** — TDD implementation of tasks (`/spec:implement`)
+
+## Artifacts
+
+| Phase | File | Status |
+|-------|------|--------|
+| Requirements | `requirements.md` | Drafted (awaiting approval) |
+| Design | `design.md` (ADR) | Not started |
+| Tasks | `tasks.md` | Not started |
+
+## Notes
+
+_Add any context, links, or decisions here as the spec evolves._